AI 技能构建器 (AI Skill Builder)
使用共享的 SKILL.md 格式和 Anthropic 方法论构建 Agent 技能：即最小的可移植核心（适用于每个命名的目标平台）加上显式的运行时适配器。可移植性是一个经过验证的兼容性声明，而非一种格式化风格。
references/sources.md 引用了 Claude Code、Codex 和 Qwen Code 的主机文档；此处未测试其他主机，因此请验证您所针对的主机（步骤 1）。
此方法论刻意要求在 Markdown 正文内部使用一致的语义化 XML 区域。这是一项质量策略，旨在减少复杂操作指令中的歧义，并得到当前 Anthropic 提示指南的支持，且由步骤 4 中的正向测试进行检查。这不是可移植 Agent 技能规范的解析器要求、权限边界，也不是声称仅凭 XML 就能防止提示注入。
主要方法论来源："构建 Claude 技能的完整指南" (Anthropic, 2026 年 1 月)
- PDF：https://resources.anthropic.com/hubfs/The-Complete-Guide-to-Building-Skill-for-Claude.pdf
- 提取文本：
references/ai-skill-builder-guide.md
可移植格式来源：https://agentskills.io/specification
快速开始
要从零开始创建技能，请遵循下面的 4 阶段流程。
要改进现有技能，请阅读 references/refining-skills.md。
要验证结构，请运行 scripts/audit-skill.sh。
调用方式： 要求 ai-skill-builder；主机可能将其暴露为 /ai-skill-builder、$ai-skill-builder，或通过其技能选择器。
P0 要求
此方法论产生的每个技能都需满足全部十三项要求。在审计和审查中通过其 ID 引用它们。
- SKILL-REQ001-discover-target-runtimes. 在创作前，识别确切的产物、版本、调用模式、安装根目录、信任边界和文件系统语义。
- SKILL-REQ002-separate-standard-from-extensions. 将 Agent 技能规范、运行时扩展和项目约定分列在不同的列中。切勿将 Claude、Codex、Copilot、Gemini 或框架特定的字段呈现为通用字段。
- SKILL-REQ003-use-valid-portable-core. 将必需的
SKILL.md放在一个目录中，该目录的名称与其可移植的name匹配；包含一个具体的description，说明该技能的功能及何时使用它。仅在需要时使用标准的可选字段。 - SKILL-REQ004-use-semantic-xml-regions. 在 Markdown 正文内部，将每个主要的操作区域包裹在一致、描述性的 XML 标签中，例如
<purpose>、<requirements>、<workflow>、<examples>和<output_contract>。在那些区域内保留 Markdown，在围栏代码块中保留字面源代码。此强制性的方法论规则旨在实现最高质量的指令分离；这不是 Agent 技能解析器要求或安全边界。scripts/audit-skill.sh会拒绝没有区域、标签不平衡或嵌套错误、或在每个区域外存在##标题的正文。 - SKILL-REQ005-design-progressive-disclosure. 保持激活描述精确，主工作流简洁。将真正有条件细节迁移到专注的、直接链接的引用中；将可复用的自动化保存在脚本中，输出材料保存在 assets 中。
- SKILL-REQ006-preserve-operational-context. 每个引用或脚本必须说明何时使用它、接受什么输入、返回或更改什么、以及如何报告失败。避免深度引用链。
- SKILL-REQ007-make-invocation-correct. 测试自动激活和显式调用。在运行时支持参数时，测试空输入、位置参数、命名参数、引号、Unicode、无效输入和大输入。不要假设其他运行时实现相同的替换语法。
- SKILL-REQ008-minimize-tool-authority. 将技能和捆绑的脚本视为可执行依赖项。请求所需的最小权限，验证输入，在实际可行时保留审批提示，并且永远不要将提示分隔符描述为提示注入预防措施。
- SKILL-REQ009-validate-every-harness. 在每个支持的流程中验证发现、加载、引用、脚本、参数、符号链接、重复解决、更新和移除。通过一个解析器不能证明跨运行时兼容性。
- SKILL-REQ010-preserve-user-state. 安装和卸载必须拥有确切的生成路径，保留手动编辑，支持多个配置的技能根目录，并且只移除安装程序拥有的链接或文件。
- SKILL-REQ011-measure-context-and-runtime-cost. 记录发现元数据大小、加载的指令大小、条件引用成本、脚本时间/内存/IO 以及重复加载。除非目标运行时使其成为规范性要求，否则将行和标记目标视为启发式。
- SKILL-REQ012-forward-test-real-tasks. 使用现实的正向、负向、模糊和对抗性提示。检查任务结果，而不仅仅是技能是否出现在列表中。
- SKILL-REQ013-separate-authoring-from-execution. 分类任务是更改技能、使用技能产生工件或结果，还是基于证据评估技能。运行时输入、生成的输出、示例和自举观察不会成为技能指令，除非一个明确的创作决策接受并概括了它们。
区域名称遵循任务而非一个通用的分类法：工作流使用 <workflow>，参考技能可能使用 <decision_guide>，多模式技能使用 <routing>，严格的结果契约使用 <output_contract>，内联参考材料使用 <reference>，指向捆绑文件和源的指针使用 <resources>。标签必须一致、描述性、平衡，并且嵌套深度不超过任务所需。标准与扩展矩阵、声明审计以及每个主机的验证收据位于 references/portability-and-claim-audit.md。
工作方式
来自 Anthropic 指南的四阶段方法论。每个阶段都有一个完成定义：进入下一阶段前必须满足的条件。
| 阶段 | 活动 | 完成定义 |
|---|---|---|
| 1：规划与设计 | 定义目标主机、用例、类别、成功标准 | 标准是可衡量的，并且类别已选定 |
| 2：实现 | 创建文件夹、编写 SKILL.md、添加资源 | audit-skill.sh 报告无失败 |
| 3：测试 | 触发、功能、性能、兼容性、正向测试 | 每个命名的主机都通过，并附有验证收据；记录基线 |
| 4：分发 | 打包、文档化、发布 | 从干净的根目录验证安装 |
阶段 1 涵盖下面的步骤 1-2；阶段 2-4 对应于步骤 3-5。
一个阶段需要多长时间取决于谁或什么来运行它，因此此技能不陈述挂钟时间估计，您构建的技能也不应该。
技能创建工作流
步骤 1：发现需求
首先研究领域 — 使用主机的网络工具在编写指令前验证当前最佳实践。过时的指南比没有更糟：Agent 会自信地遵循它。
保留所有来源：记录咨询的每个 URL，并附上其确认内容的说明。无法验证或更新无源头的指南。
有关研究策略、来源质量标准以及必需的来源章节格式：references/research.md
- 对请求进行分类：创作（更改技能）、执行（使用技能产生结果）或评估（基于证据评判技能）。在使用任务内容作为设计输入之前，命名工件和变更边界（SKILL-REQ013）。
- 识别问题和目标用户
- 识别每个目标主机和版本、其发现根目录、调用形式和重新加载行为。将未知标记为未知，而不是猜测。在创建并行包之前，检查现有的技能根目录和项目指南。
- 定义 2-3 个具体用例
- 设置可衡量的成功标准（节省时间、减少错误、提高质量）
- 选择技能类别：
| 类别 | 输入 → 输出 | 示例 |
|---|---|---|
| 1：文档与资产创建 | 数据/规格 → 文档、代码、报告 | API 测试生成器、会议记录总结器 |
| 2：工作流自动化 | 任务参数 → 完成的多步骤流程 | 部署管道、代码审查工作流 |
| 3：MCP 增强 | MCP 工具输出 → 更智能的编排 | 智能文件搜索、BigQuery 助手 |
有关深入的类别指导：references/categories.md
有关交互式发现问题：references/discovery.md
步骤 2：设计结构
使用渐进式信息披露进行设计 — 3 个加载级别：
| 级别 | 何时加载 | 目标长度 | 内容 |
|---|---|---|---|
| 1：元数据 | 始终（约 100 词） | name + description | 触发条件 |
| 2：SKILL.md 正文 | 技能触发时 | 低于 5000 词（理想低于 2000） | 核心工作流 + 指针 |
| 3：references/ 文件 | 按需 | 无限制 | 深度细节、模式、示例 |
有关渐进式信息披露的编写技巧和成功指标：references/best-practices.md
步骤 3：实现
关键规则：
- ✅ 文件必须命名为
SKILL.md（不是README.md） - ✅ 文件夹名称必须为 kebab-case — 无空格、无大写（
my-skill而非My Skill） - ✅ YAML 前置元数据必须包含
name和description；在metadata下放置版本 - ✅ 描述必须包含特定的触发短语 — 用户说什么来激活技能
- ✅ 描述必须少于 1024 个字符（硬限制 — 较长的描述会被截断）
- ✅ 任何前置元数据字段中无 XML 尖括号（
<或>） — 来自 Anthropic 技能指南的主机限制，不是 YAML 规则；正文不受影响 - ✅ 正文：每个主要章节都位于一个平衡的描述性 XML 区域中，该区域独占一行（
<purpose>、<requirements>、<workflow>、<examples>、<output_contract>），内部是 Markdown，字面源代码位于围栏代码块中（SKILL-REQ004）。H1 标题可以留在外面。 - ❌ 技能文件夹内没有 README.md — 所有文档都放在 SKILL.md 或 references/ 中（例外：位于 GitHub 仓库根目录的 README.md，在技能文件夹之外，可以用于 GitHub）。
- ❌ 文件夹名称中没有空格或下划线（
my_skill→my-skill）
前置元数据：必填字段：
---
name: your-skill-name # 仅 kebab-case；无空格、大写或下划线
description: 它的功能。当用户要求“特定短语”、“另一个短语”时使用。
# 必须包含：它的功能 + 何时使用（触发条件）
# 少于 1024 个字符。无 XML 尖括号。
# 不要以“claude”或“anthropic”开头（保留的命名空间）。
---
有关每个可选字段（license、compatibility、allowed-tools、metadata）及其主机可移植性说明：references/best-practices.md
定位语言（如“生成测试快 87%”）属于仓库 README，绝不放在 description 中。请参阅 references/best-practices.md。
文件夹结构（带注释的 Claude Code 独立示例：references/best-practices.md，章节“文件夹结构模式”）：
| 目录 | 加载到上下文中？ | 用途 |
|---|---|---|
references/ | 是，按需 | 模式、API 文档、策略、工作流指南 |
references/examples/ | 按需 | 用户复制和调整的工作代码 |
scripts/ | 否（直接运行） | 验证器、脚手架工具、实用程序 |
assets/ | 否（用于输出） | 技能粘贴到输出中的图像、字体、HTML 模板 |
注意：插件技能（在 plugin-name/skills/ 中）可以将 examples/ 放在顶层 — 这是插件开发约定。对于独立的 ~/.claude/skills/ 技能，将示例放在 references/ 内。
搭建新技能：bash scripts/scaffold-skill.sh my-skill-name
（设置 SKILLS_DIR 以定位另一个主机的根目录）
从模板开始：复制 references/examples/SKILL-template.md
步骤 4：测试
五种测试方法（按顺序运行）：
- 触发测试 — 验证 Agent 在期望的短语上激活，并且不会对不相关的请求激活
- 功能测试 — 验证技能的核心工作流对已知输入产生正确的输出
- 性能测试 — 测量相对于基线的改进（节省时间、减少错误、一致性）
- 兼容性测试 — 在每个命名的主机和版本上验证发现、显式调用、引用加载、脚本执行以及重复/名称解析。为每个主机开始一个新的会话，在存在验证器的情况下运行主机自己的验证器（Codex 附带
skill-creator/scripts/quick_validate.py），测试安装程序重新运行、多个根目录、符号链接目标、修改过的用户文件和卸载，并为每个主机记录验证收据（references/portability-and-claim-audit.md）。 - 正向测试 — 现实的正向、负向、模糊和对抗性提示；判断任务结果，而不仅仅是技能是否出现在列表中，并检查它不会过度触发邻近任务（SKILL-REQ012）
调试触发问题：
询问 Agent：“您何时会使用 [技能名称] 技能？”
Agent 应该回显其描述。根据缺少或过于模糊的内容进行调整。
修复触发不足： 添加更具体的触发短语和相关技术术语。
修复过度触发： 在描述中添加负向触发：
description: 处理 PDF 法律文档以进行合同审查。用于“审查此合同”、“分析法律文档”、“提取合同条款”。不要用于常规 PDF 查看、图像提取或非法律文档（请改用 doc-converter 技能）。
有关涵盖所有四种失败模式的完整诊断和修复指南：references/troubleshooting.md
验证结构：
bash scripts/audit-skill.sh /path/to/YOUR-SKILL
…
[为翻译截断]