Anthropic 的 Agent Skills 是一种开放标准，用于为 AI 代理（如 Claude）创建自定义能力包。每个技能是一个文件夹，包含核心文件 SKILL.md 和可选的子文件夹（如 scripts/ 用于脚本、references/ 用于参考文档、assets/ 用于模板）。技能通过 YAML 前置元数据和 Markdown 内容定义，Claude 会根据描述动态发现和加载它们。以下是开发的基本步骤：

1. 创建技能文件夹：

   • 在项目目录中创建一个新文件夹，例如 my-skill/。
   • 在其中添加 SKILL.md 文件，这是必需的核心文件。

2. 编写 YAML 前置元数据：

   • 在 SKILL.md 开头添加 YAML 块，例如：

     ---
     name: my-skill-name  # 必需，小写、连字符分隔，≤64 字符
     description: Extracts data from PDFs for analysis. Use when handling PDF files.  # 必需，≤1024 字符，描述技能作用和触发场景
     allowed-tools: Read,Write,Bash  # 可选，指定允许的工具
     model: claude-sonnet-3.5  # 可选，指定模型
     ---
     

   • 名称使用动名词形式（如 analyzing-data），描述要具体、行动导向，便于 Claude 识别触发时机。

3. 撰写技能内容：

   • 在 YAML 后使用 Markdown 结构化内容，例如：

     ## Overview
     This skill processes PDFs to extract text and tables.
     
     ## Instructions
     1. Use Read tool to load the PDF.
     2. Run scripts/extract.py if needed.
     3. Output in JSON format.
     
     ## Examples
     Input: report.pdf
     Output: {"text": "...", "tables": [...]}
     

   • 保持 SKILL.md 简洁（<500 行），使用渐进式披露：核心指令放主文件，细节引用子文件（如 Read({baseDir}/references/details.md)）。
   • 对于复杂任务，分解成步骤清单、反馈循环（验证-修复-重复）和条件工作流。
   • 集成可执行代码：添加 scripts/ 中的 Python 或 Bash 脚本，提高可靠性，并处理错误（例如，添加 try-except）。避免时间敏感信息，使用一致术语。

4. 添加辅助资源：

   • scripts/：放置自动化脚本（如 init.py 生成模板）。
   • references/：存储额外文档或 JSON 数据。
   • assets/：模板文件或二进制资源。
   • 使用 {baseDir} 引用路径，确保跨环境兼容。

5. 放置技能：

   • 将文件夹放入 Claude 支持的路径，如 ~/.config/claude/skills/（全局）或项目内的 .claude/skills/。
   • 重启 Claude 或代理以加载新技能。

开发时，从评估开始：先运行代理在代表性任务上，识别能力差距，然后增量构建技能。使用 Claude 本身迭代：让一个 Claude 实例设计技能，另一个测试。

调试 Agent Skills 的方法

调试重点在于观察 Claude 的行为、迭代测试，并修复常见问题。技能不是直接代码，而是提示模板，Claude 通过推理调用它们（无算法匹配）。

1. 测试技能：

   • 跨模型测试：在 Haiku（指导性强）、Sonnet（清晰度）和 Opus（避免过度解释）上运行，确保兼容。
   • 评估驱动：先定义成功标准（例如，JSON 文件指定预期行为），创建 3+ 场景测试差距，比较基线 vs. 使用技能的表现。
   • 真实使用测试：在实际工作流中应用，收集团队反馈。观察 Claude 是否正确触发技能（基于 description）。

2. 监控和观察：

   • 观看 Claude 使用技能的过程：注意意外路径、忽略规则或过度依赖某些部分。
   • 检查日志：查看 UI 中的 <command-message>（如 “The ‘my-skill’ is loading”）和 API 中的隐藏元提示（isMeta: true）。
   • 让 Claude 自我反思：如果任务偏轨，问它 “什么出错了？”，用洞见优化技能。

3. 修复常见问题：

   • 技能不触发：描述太模糊，添加关键触发词（如 “when handling PDFs”）。
   • 不完整加载：避免嵌套引用，使用 TOC 在长文件；保持 SKILL.md <5000 词以防上下文溢出。
   • 脚本失败：手动运行脚本验证，添加错误处理；检查依赖和路径（用正斜杠，如 scripts/helper.py）。
   • 权限问题：验证 allowed-tools 范围合适，不太宽松。
   • 其他：确认 YAML 有效，无禁用标志；重启代理后重测。

4. 迭代优化：

   • 基于观察返回到开发循环：精炼描述、添加例子或反馈机制。
   • 使用 MCP（Model Context Protocol）集成外部工具，如果需要更高级功能（如服务器访问数据）。

建议从 Anthropic 的示例仓库或内置技能（如 skill-creator）起步，逐步自定义。更多资源可在 Claude Docs 或 GitHub 上找到。