企业官网建设流程全解析

WordPress Agent Skills 创作指南：如何从零编写一个高质量 SKILL.md

【免费下载链接】agent-skillsExpert-level WordPress knowledge for AI coding assistants - blocks, themes, plugins, and best practices项目地址: https://gitcode.com/gh_mirrors/agents/agent-skills

WordPress Agent Skills 是教 AI 编程助手（Claude、Copilot、Cursor 等）用正确方式开发 WordPress 的可移植技能包。本文是一份从零开始编写高质量 SKILL.md 的完整指南，无需编程基础，只需清晰描述你的 WordPress 知识 📚

什么是 Agent Skills 和 SKILL.md？

每个技能（Skill）都是一个自包含的文件夹，AI 助手在执行 WordPress 相关任务时会读取它，并按文档中的流程操作而不是靠猜。这正是 README.md 中强调的核心理念：

skills/wp-block-development/ ├── SKILL.md # 主指令（何时使用、流程、验证） ├── references/ # 特定主题的深入文档 └── scripts/ # 确定性辅助脚本（检测、校验）

其中SKILL.md 是技能的"大脑"，包含 YAML 前置元数据和六大核心章节；references/存放深度资料；scripts/存放确定性检查脚本。想快速上手，建议先阅读官方 创作指南 和 设计原则。

SKILL.md 的完整结构：前置元数据 + 六大章节

打开任意现成技能，比如 skills/wp-env/SKILL.md，都会看到统一的结构：

① YAML 前置元数据（必填 3 个字段）

② 六大核心章节（缺一不可）

1. When to use（何时使用）——触发条件清单：用户说了什么话、项目里存在什么文件
2. Inputs required（所需输入）——AI 动手前要先收集什么（Docker 状态、Node 版本、项目类型……）
3. Procedure（操作流程）——编号的分步检查清单，每步给出具体命令
4. Verification（验证）——可勾选的验证项，例如"访问 localhost:8888 能看到后台"
5. Failure modes / debugging（故障模式）——常见症状、原因、修复方法对照表
6. Escalation（何时求助）——超出技能范围、需要人类介入的情形

💡 小技巧：description是 AI 判断"该不该用这个技能"的唯一依据，写清触发词（用户可能提到的关键词）比写功能介绍更重要。

一键脚手架：30 秒生成合规骨架

不用手写模板。仓库提供了 scaffold-skill.mjs 脚手架脚本，克隆仓库后执行：

git clone https://gitcode.com/gh_mirrors/agents/agent-skills cd agent-skills node shared/scripts/scaffold-skill.mjs my-skill "Use when <描述触发场景>"

它会自动完成三件事：

• 创建skills/my-skill/SKILL.md，预填好全部六大章节标题
• 创建eval/scenarios/my-skill.json评估场景占位文件
• 内置名称校验（拒绝大写、超长、连续连字符），从源头避免格式错误

填充六大章节：像写检查清单一样写 SKILL.md

官方黄金法则只有一条最重要的：SKILL.md 保持短小、流程化，把深度内容推到references/和脚本中（见 CONTRIBUTING.md 的 "Keep It Small" 章节）。

写每一章时可以自问：

以 skills/wp-env/SKILL.md 为例，它的 Failure modes 章节就是一张 10 行的"症状-原因-修复"表，AI 遇到 "Port 8888 already in use" 时能直接定位到--auto-port方案，而不是瞎试。

深度放 references/，确定性放 scripts/

docs/principles.md 给出了两条关键设计原则：

• 文件引用保持 1 跳：references/直接从 SKILL.md 链接，避免 A→B→C 的深层嵌套
• 能用脚本就不让 AI 猜：凡是需要检测仓库类型、版本、构建系统的地方，优先写一个scripts/下的确定性脚本。参考 skills/wp-plugin-development/scripts/detect_plugins.mjs——AI 运行它拿到 JSON 结果，比让它"目测"目录结构可靠得多

⚠️ 上游官方文档是权威来源。技能里放"面向 AI 的检查清单和决策树"，深度知识通过链接指向官方文档即可，不要复制粘贴大段文档。

兼容性契约：锁定 WordPress 7.0+

所有技能必须声明统一的版本目标（见 docs/compatibility-policy.md）：

• WordPress 核心7.0+
• PHP7.4.0+

compatibility:字段必须包含WordPress 7.0和PHP 7.4.0两个字样，否则结构校验会直接报错。同时遵循指南：优先稳定 API，优先"检测 + 护栏"而非硬编码假设，避免推荐经典主题、Gutenberg 之前的遗留模式。

每个技能必须配一个评估场景

黄金法则第四条：没有评估场景的技能不许入库。在eval/scenarios/下添加一个<技能名>.json文件，包含 5 个字段（详见 eval/scenarios/README.md）：

{ "name": "my-skill", "skills": ["my-skill"], "query": "一个真实的用户提问示例", "expected_behavior": ["AI 应该做什么"], "success_criteria": ["怎样算成功"] }

脚手架已经帮你生成了占位文件，你只需要填入一个真实的提问和预期行为。提交 PR 时请手动运行该场景并把结果写进 PR 说明——仓库目前还没有自动评估运行器。

提交前必做：运行结构校验

提交前的最后一道关卡是 validate-skills.mjs：

node shared/scripts/validate-skills.mjs

它会自动检查全部技能目录，任何一项不合规都会明确报错：

• ✅ 每个技能存在SKILL.md且带 YAML 前置元数据
• ✅name与目录名一致、命名合法（小写、≤64 字符）
• ✅description≤1024 字符，compatibility≤500 字符且符合 WP 7.0 / PHP 7.4.0 契约
• ✅ 项目分诊脚本（triage detector）输出正常

看到OK: skill metadata and triage report sanity checks passed.就可以放心提交 PR 了 🎉

常见错误清单

用 AI 辅助起草技能

这个项目本身就是AI 辅助创作 + 确定性护栏的产物（见 docs/ai-authorship.md）。用 LLM 起草技能时，官方推荐的提示模板包含：

1. 仓库分诊 JSON 输出
2. 用户的任务描述
3. 版本约束和非目标
4. 要求输出：SKILL.md+ 提到的references/*.md+ 所需的scripts/脚本桩 + 一个评估场景 JSON

然后由人类审阅编辑——这就是"AI 打草稿、规范做护栏"的高效组合。

开始创作：完整工作流回顾

1. 先路由：从 skills/wordpress-router/SKILL.md 入手分类项目、选定领域
2. 收输入：项目类型、WP/PHP/Node 版本、已有工具链
3. 脚手架：node shared/scripts/scaffold-skill.mjs <名称> "<描述>"
4. 写流程：填充六大章节，短小、可执行、可验证
5. 加护栏：检测类逻辑写成scripts/脚本
6. 加场景：补齐eval/scenarios/中的评估 JSON
7. 跑校验：node shared/scripts/validate-skills.mjs通过后提交 PR 🚀

你不需要是编程高手——"代码"本质上是流程检查清单、决策树和参考文档。只要你能把某个 WordPress 概念讲清楚，就能为一个技能做出真实贡献。

【免费下载链接】agent-skillsExpert-level WordPress knowledge for AI coding assistants - blocks, themes, plugins, and best practices项目地址: https://gitcode.com/gh_mirrors/agents/agent-skills