SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场skills-development

skills-development

智能体与模型

查看项目

更新于 10-16 07:45

技能介绍

用途

Skills Development 用于创建符合 Agent Skills 规范的技能（skill），并编写对应的 SKILL.md 文件。Agent Skills 是一种开放格式，被 Claude Code、Cursor、VS Code、GitHub 及其他智能体产品支持。当需要“create skill”“new skill”“validate skill”或涉及“SKILL.md”时，应使用该技能。

主要能力

该技能提供一套五阶段工作流：

  1. Discovery（发现）：明确技能要解决的问题、主要能力、触发短语，以及技能应存放的位置（个人目录 ~/.claude/skills/、项目目录 .claude/skills/ 或插件目录）。
  2. Archetype Selection（原型选择）：从五种原型中选择最合适的模式，包括 simple（基础技能，无脚本）、api-wrapper（封装外部 API）、document-processor（处理文件格式）、dev-workflow（自动化开发任务）、research-synthesizer（收集与综合信息）。模板位于 templates/skill-archetypes/。
  3. Initialization（初始化）：运行初始化脚本生成技能结构，命令为： bun run ${CLAUDE_PLUGIN_ROOT}/skills/skills-development/scripts/init-skill.ts <skill-name> <output-dir> --template <archetype>
  4. Customization（定制）：按需调整目录结构、frontmatter 字段、描述公式，并针对所选原型进行定制。
  5. Validation（校验）：提交前使用 CLI 或手动检查清单验证质量，命令为：skills-ref validate ./my-skill。

使用方式

目录结构

skill-name/
├── SKILL.md           # 必需：指令 + 元数据
├── scripts/           # 可选：可执行代码
├── references/        # 可选：文档
└── assets/            # 可选：模板、资源

Frontmatter 字段

  • name（必需）：1-64 字符，小写字母/数字/连字符，必须与目录名一致。
  • description（必需）：1-1024 字符，说明“做什么”和“何时使用”。
  • user-invocable（可选）：布尔值，启用 /skill-name 命令（Claude Code）。
  • license（可选）：许可证名称或引用。
  • compatibility（可选）：1-500 字符，环境要求。
  • allowed-tools（可选，实验性）：空格分隔的工具列表。
  • metadata（可选）：自定义字段对象。

自定义字段必须嵌套在 metadata 下，顶层自定义字段不被允许，可能导致解析错误。

描述公式

[WHAT] + [WHEN] + [TRIGGERS]

示例：Extracts text and tables from PDF files, fills forms, merges documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.

检查项：说明 WHAT（能力）、声明 WHEN（触发条件）、包含 3-5 个触发关键词、使用第三人称、少于 200 词。

各原型定制要点

  • api-wrapper：更新 scripts/client.ts 中的 API 端点，添加认证说明，若 API 较大则创建 references/endpoints.md。
  • document-processor：更新 scripts/process.ts 中的格式逻辑，添加库依赖，记录支持的操作。
  • dev-workflow：更新 scripts/run.ts 中的命令，为破坏性操作添加安全检查，记录可用命令。
  • research-synthesizer：定义来源优先级顺序，指定输出格式，设置引用风格。

校验清单

  • YAML Frontmatter：第 1 行以 --- 开头并以 --- 结尾；name 和 description 存在；使用空格而非制表符；特殊字符加引号。
  • 命名：仅小写字母、数字、连字符（1-64 字符）；与父目录名一致；无 --、无首尾连字符；名称中不含 anthropic 或 claude。
  • 描述质量：WHAT、WHEN、TRIGGERS 齐全；第三人称。
  • 结构：SKILL.md 少于 500 行；所有引用文件存在；无 TODO/占位符；渐进式披露（细节放在 references/）。

核心原则

  • 简洁至上：上下文窗口共享，只包含智能体尚不知道的内容。
  • 第三人称描述：描述会注入系统提示，应写“Extracts text from PDFs”而非“I can help you extract text from PDFs”。
  • 渐进式披露：SKILL.md 保持在 500 行以内，细节移至 references/、scripts/、assets/。
  • 自由度匹配：高自由度（文本）、中自由度（伪代码）、低自由度（脚本）。

工具限制

使用 allowed-tools 限制能力（实验性）：

# 只读
allowed-tools: Read Grep Glob

# 带 shell 访问
allowed-tools: Bash(git:*) Bash(jq:*) Read

# 完全访问（默认）
# 省略该字段

适用场景

  • 需要为 Claude Code、Cursor、VS Code、GitHub 等智能体产品创建新技能。
  • 编写或修改 SKILL.md 文件。
  • 校验已有技能是否符合 Agent Skills 规范。
  • 将技能打包为插件或提交到 git 进行分发。

限制

  • 资料中未提供该技能的收费、价格信息。
  • 资料中未提供该技能的具体平台支持范围之外的信息。
  • allowed-tools 字段标注为实验性。
  • 自定义字段必须嵌套在 metadata 下，顶层自定义字段不被允许。
  • 技能名称中不能包含 anthropic 或 claude。
  • SKILL.md 应保持在 500 行以内。

创建后步骤

  1. 校验：运行 Phase 5 清单或 skills-ref validate。
  2. 测试：提出一个应触发该技能的问题。
  3. 迭代：修复问题直至通过。
  4. 分享：提交到 git 或通过插件分发。

故障排查

# 查找所有技能
find ~/.claude/skills .claude/skills -name "SKILL.md" 2>/dev/null

# 检查制表符（YAML 需要空格）
grep -P "\t" SKILL.md

# 查找损坏的 markdown 链接
grep -oE '\[[^]]+\]\([^)]+\)' SKILL.md | while read link; do
  file=$(echo "$link" | sed 's/.*(\(.*\))/\1/')
  [ ! -f "$file" ] && echo "Missing: $file"
done

参考资料

  • patterns.md：自由度、脚本设计、变体组织、写作模式。
  • best-practices.md：社区模式、测试策略、高级技巧。
  • quick-reference.md：快速清单和单行命令。
  • implementations.md：各工具存储路径。
  • invocations.md：工具如何激活技能。
  • compatibility.md：路径兼容性矩阵。
  • Claude Code：claude.md。
  • Codex CLI：codex.md。

外部资源包括 Agent Skills Specification、Best Practices Guide、skills-ref Validation Library。