WordPress 代理技能

教会 AI 编码助手以正确的方式构建 WordPress。

代理技能是一组可移植的指令、检查清单和脚本，可帮助 AI 助手（Claude、Copilot、Codex、Cursor 等）理解 WordPress 开发模式、避免常见错误并遵循最佳实践。

AI 著作声明： 这些技能由官方 Gutenberg 和 WordPress 文档中的 GPT-5.2 Codex（高阶推理）生成，随后由 WordPress 贡献者审核和编辑。我们已使用 AI 助手对这些技能进行了测试，并根据结果不断迭代。目前为 v1 版本，随着社区的使用和贡献修复，技能将持续改进。详情请参阅 docs/ai-authorship.md。（WordPress AI 指南）

为什么需要代理技能？

AI 编码助手功能强大，但它们常常：

• 生成过时的 WordPress 模式（Gutenberg 之前、区块主题之前）
• 在插件开发中忽略关键的安全考量
• 跳过正确的区块弃用流程，导致“无效区块”错误
• 忽视仓库中已有的工具链

代理技能通过为 AI 助手提供它们能够实际使用的 专家级 WordPress 知识 来解决这些问题。

可用技能

技能	教授内容
wordpress-router	对 WordPress 项目进行分类，并引导至正确的开发流程
wp-project-triage	自动检测项目类型、工具链和版本
wp-block-development	Gutenberg 区块：block.json、属性、渲染、弃用处理
wp-block-themes	区块主题：theme.json、模板、模式、样式变体
wp-plugin-development	插件架构、钩子、设置 API、安全性
wp-rest-api	REST API 路由/端点、Schema、认证及响应格式化
wp-interactivity-api	使用 data-wp-* 指令和状态管理实现前端交互
wp-abilities-api	基于能力的权限控制与 REST API 认证
wp-wpcli-and-ops	WP-CLI 命令、自动化、多站点管理、搜索替换
wp-performance	性能分析、缓存、数据库优化、Server-Timing
wp-phpstan	PHPStan 静态分析用于 WordPress 项目（配置、基线、WordPress 特定类型系统）
wp-playground	WordPress Playground，用于快速搭建本地环境
wpds	WordPress 设计系统
blueprint	WordPress Playground 蓝图，用于声明式 Playground 环境搭建

快速开始

为 Claude Code 全局安装

# 克隆 agent-skills
git clone https://github.com/WordPress/agent-skills.git
cd agent-skills

# 构建分发包
node shared/scripts/skillpack-build.mjs --clean

# 将所有技能全局安装（在所有项目中可用）
node shared/scripts/skillpack-install.mjs --global

# 或仅安装特定技能
node shared/scripts/skillpack-install.mjs --global --skills=wp-playground,wp-block-development

这会将技能安装到 ~/.claude/skills/，Claude Code 将自动发现它们。

安装到您的项目中

# 克隆 agent-skills
git clone https://github.com/WordPress/agent-skills.git
cd agent-skills

# 构建分发包
node shared/scripts/skillpack-build.mjs --clean

# 安装到您的 WordPress 项目
node shared/scripts/skillpack-install.mjs --dest=../your-wp-project --targets=codex,vscode,claude,cursor

这会将技能复制到：

• .codex/skills/ 用于 OpenAI Codex
• .github/skills/ 用于 VS Code / GitHub Copilot
• .claude/skills/ 用于 Claude Code（项目级别）
• .cursor/skills/ 用于 Cursor（项目级别）

为 Cursor 全局安装

node shared/scripts/skillpack-install.mjs --targets=cursor-global

这会将技能安装到 ~/.cursor/skills/，Cursor 将自动发现它们。

可用选项

# 列出可用技能
node shared/scripts/skillpack-install.mjs --list

# 干运行（预览而不安装）
node shared/scripts/skillpack-install.mjs --global --dry-run

# 将特定技能安装到项目中（例如 Claude + Cursor）
node shared/scripts/skillpack-install.mjs --dest=../my-repo --targets=claude,cursor --skills=wp-wpcli-and-ops

手动安装

将 skills/ 目录下的任意技能文件夹复制到您项目的 AI 助手指令目录中即可。

工作原理

每个技能包含：

skills/wp-block-development/
├── SKILL.md              # 主要说明（何时使用、操作步骤、验证方法）
├── references/           # 关于特定主题的深入文档
│   ├── block-json.md
│   ├── deprecations.md
│   └── ...
└── scripts/              # 确定性辅助工具（检测、验证）
    └── list_blocks.mjs

当您让 AI 助手处理 WordPress 代码时，它会读取这些技能并按照文档中的步骤执行，而不是凭猜测行事。

兼容性

• WordPress 6.9+（PHP 7.2.24+）
• 适用于任何支持项目级指令的 AI 助手

贡献

我们欢迎您的贡献！ 该项目是分享您 WordPress 专业知识的好机会——您无需成为编码高手。大多数技能以 Markdown 格式编写，重点在于清晰的操作步骤和最佳实践。

有关如何入门的详细信息，请参阅 CONTRIBUTING.md。

快捷命令：

# 搭建新技能框架
node shared/scripts/scaffold-skill.mjs <技能名称> "<描述>"

# 验证技能
node eval/harness/run.mjs

文档

• 创作指南 - 如何创建和改进技能
• 原则 - 设计哲学
• 打包 - 构建与分发
• 兼容性政策 - 版本定位策略

许可证

GPL-2.0 或后续版本

agent-skills 快速上手指南

agent-skills 是一套专为 WordPress 开发设计的 AI 助手技能包。它能教会 Claude、Copilot、Cursor 等 AI 工具遵循最新的 WordPress 最佳实践（如 Gutenberg 区块、现代主题架构），避免生成过时代码或忽略安全规范。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统：Linux、macOS 或 Windows (WSL)
• Node.js：已安装 Node.js 运行环境（用于执行构建和安装脚本）
• Git：已安装 Git 用于克隆仓库
• 目标 AI 工具：已安装并配置好以下任一工具：
  • Claude Code
  • Cursor
  • VS Code (配合 GitHub Copilot)
  • OpenAI Codex

注意：本项目主要面向 WordPress 6.9+ 及 PHP 7.2.24+ 环境。

安装步骤

1. 克隆项目并构建

首先从 GitHub 克隆仓库并构建分发包。

# 克隆 agent-skills 仓库
git clone https://github.com/WordPress/agent-skills.git
cd agent-skills

# 构建分发包
node shared/scripts/skillpack-build.mjs --clean

2. 选择安装方式

根据您的使用习惯，选择以下一种方式进行安装：

方案 A：全局安装（推荐）

适用于希望所有项目都能自动调用这些技能的场景。

为 Claude Code 全局安装：

node shared/scripts/skillpack-install.mjs --global

技能将被安装至 ~/.claude/skills/

为 Cursor 全局安装：

node shared/scripts/skillpack-install.mjs --targets=cursor-global

技能将被安装至 ~/.cursor/skills/

仅安装特定技能（例如只安装区块开发和 WP-CLI 相关）：

node shared/scripts/skillpack-install.mjs --global --skills=wp-block-development,wp-wpcli-and-ops

方案 B：项目级安装

适用于仅在当前 WordPress 项目中启用技能，便于团队协作和版本控制。

# 将技能安装到指定的 WordPress 项目目录，并适配多种 AI 工具
node shared/scripts/skillpack-install.mjs --dest=../your-wp-project --targets=codex,vscode,claude,cursor

执行后，技能文件会自动复制到目标项目的 .codex/skills/, .github/skills/, .claude/skills/, .cursor/skills/ 等对应目录中。

方案 C：手动安装

如果您偏好手动管理，可以直接将 skills/ 目录下的任意技能文件夹复制到您 AI 助手的指令目录中。

基本使用

安装完成后，无需额外配置，AI 助手会在上下文中自动识别并应用这些技能。

使用示例

假设您已全局安装了 wp-block-development 技能，现在需要在 Cursor 或 Claude Code 中创建一个新区块。

操作步骤：

1. 打开您的 WordPress 项目终端或 AI 聊天窗口。
2. 直接输入自然语言指令，例如：

"请帮我创建一个名为 'latest-posts' 的 Gutenberg 动态区块，包含显示文章标题和摘要的功能，并确保符合最新的 block.json 规范和去重处理逻辑。"

预期效果： AI 助手将读取已安装的 wp-block-development 技能包，自动执行以下操作：

• 生成标准的 block.json 配置文件。
• 编写符合现代 WordPress 规范的 PHP 渲染回调或 React 编辑组件。
• 自动包含必要的区块弃用（deprecations）处理逻辑，防止未来升级导致区块失效。
• 遵循安全性检查，避免常见的插件开发漏洞。

查看可用技能

如果您想查看当前所有可用的技能列表，可运行：

node shared/scripts/skillpack-install.mjs --list

常用核心技能包括：

• wp-block-development: 区块开发规范
• wp-block-themes: 区块主题 (theme.json) 开发
• wp-plugin-development: 插件架构与安全
• wp-rest-api: REST API 路由与认证
• wp-interactivity-api: 前端交互指令