SuperAPI AI 工具集

skill-writer

编程与开发

查看项目

更新于 11-05 16:17

技能介绍

用途

Skill Writer 用于为 Claude Code 技能生态生成结构正确的 SKILL.md 文件。所有技能遵循相同的 frontmatter 约定与目录结构。适用场景包括:创建新的智能体角色技能、创建工作流或元技能、审查现有技能是否符合规范、为编排构建添加角色。

技能目录结构

skill-name/
├── SKILL.md              # 必需 — frontmatter + 指令
└── references/           # 可选 — 按需加载
    └── detailed-guide.md

渐进式披露

技能采用三级加载:

  • 元数据(约 100 tokens)— name + description,始终在上下文中
  • SKILL.md 正文(不超过 5,000 词;超过 500 行软警告)— 技能触发时加载
  • 参考文件(无限制)— 通过显式读取按需加载

正文应保持简洁,将详细清单、模板和参考表移至 references/ 并给出明确指引。

创建新技能的步骤

第 1 步:选择技能类型

类型 目录 用途
智能体角色 roles/{name}/ 编排构建的实现智能体
元技能 meta/{name}/ 技能生态自身的工具
工作流 workflows/{name}/ 跨领域流程
合约 contracts/{name}/ 集成合约管理
编排器 orchestrator/ 主导协调者(单例)

第 2 步:编写 frontmatter

每个 SKILL.md 以 YAML frontmatter 开头,完整字段参考见 references/frontmatter-spec.md。必填字段:

  • name — kebab-case,最多 64 字符。claude-* / anthropic-* 前缀为 Anthropic 保留;仅在技能面向对应 Anthropic 产品时作为有记录的例外使用(如 claude-design-brief)。
  • version — semver(从 1.0.0 开始),顶层字段
  • description — [What] + [When] + [Capabilities] 结构(目标不超过 200 字符,硬上限 1024)

description 是主要触发机制,应写得“主动”,列举技能应激活的上下文。模板与三槽位结构见 references/description-patterns.md。

第 3 步:编写正文

正文应围绕以下结构:

  • 角色声明 — 一段话定义该智能体/技能做什么
  • 输入 — 接收的参数
  • 流程 — 编号步骤,祈使语气
  • 协调规则 — 与其他智能体的交互方式
  • 指南 — 原则与常见陷阱

保持正文简短可靠的写作原则:

  • 锚定一个主导词:将技能行为挂在一个模型已知的强预训练概念上(如“对抗性”“分诊”“复盘”),而不是在多处重复三段式定义。若同一想法出现在 description、引言和步骤中,将其收敛为承载它的那个词。
  • 整句删除空操作:模型默认就会遵守的句子(“要乐于助人”“写干净代码”“考虑边界情况”)纯属上下文成本,应删除整句而非缩短成更短的空操作。
  • 陈述目标行为而非单纯禁止:“不要做 X”让模型猜测替代方案;“做 Y(因为 Z)”则明确替代方案。仅当禁止形式本身是最强锚点时保留禁止(Forbidden: 反模式命名约定)。
  • 为保留的警告标明代价:写明真实返工成本的警告(“耗尽智能体的整个上下文”“返工在后续阶段才浮现”)会被权衡;未标价的警告会被当作风格建议在压力下跳过。参见 references/patterns.md 中的 Cost-Tagged Anti-Patterns。

智能体角色技能还应包含:

  • 第 0 步:读取合约 — 每个角色技能应在任何实现之前先读取合约与领域规则
  • 所有权 — 独占的目录/文件,并注明编排器提示优先于 frontmatter 默认值
  • 禁区 — 该智能体绝不能触碰的内容
  • 规模适配 — 适应项目复杂度的指引
  • 验证 — 链接到 references/validation-script-pattern.md,了解如何将验证步骤接入新技能正文

第 4 步:创建参考文件

将详细内容移至 references/:

  • 含具体命令的验证清单
  • 模板与示例
  • 详细技术指南
  • 超过 20 行的表格

从正文引用参考文件并说明何时阅读,例如:

完整验证流程见 references/quick-checklist.md,在报告完成前阅读。

第 5 步:添加触发测试

每个技能必须带有具体触发测试 — 至少一个必须激活技能的用户措辞示例,最好再有一个不应激活的近似示例。这是验证 description 是否真正触发的依据(不仅是读起来通顺)。将其记录在技能中(如简短的“Triggering test”说明或 references/quick-checklist.md 中的一行),以便审查者重新运行。

第 6 步:验证技能

一次只做一项聚焦改动 — 单次编辑后重新验证(lint + 触发测试),再进入下一项。不要将多个不相关改动混在一次处理中。

检查项:

  • frontmatter 包含所有必填字段
  • name 为 kebab-case;若以 claude- 或 anthropic- 开头,属于有记录的例外(技能面向对应 Anthropic 产品)
  • frontmatter 中任何位置不含 < 或 >
  • description 不超过 200 字符(目标)且“主动”;绝不超过 1024 字符(上限)
  • 正文不超过 5,000 词(超过 500 行软警告)
  • 文件所有权不与现有智能体重叠(检查 v1.1 已解决冲突)
  • 目录所有权优先于模式所有权
  • 参考文件从正文链接
  • 正文与参考文件之间无重复内容
  • 已记录触发测试(至少 1 个必须触发的措辞;最好有 1 个不应触发的近似示例)

第 7 步:赚取上下文成本(可选,建议用于非简单技能)

可选地对比有/无技能时的行为 — 在一两个代表性提示上做快速基线评估 — 确认技能可测量地改善输出并值得其给每个上下文增加的 token。简单技能可跳过;实质性技能应执行。

常见错误

  • 描述模糊 — “帮助处理后端相关事务”不会触发,应具体。
  • 正文过长 — 接近 5,000 词或 500 行时,将内容移至 references。
  • 缺少所有权 — 智能体角色必须声明拥有与禁区的文件。
  • 所有权重叠 — 两个智能体不能拥有同一目录;目录所有权优先于模式所有权(见 references/frontmatter-spec.md §Ownership Resolution Rules)。
  • 忽略已解决冲突 — 在声明对 contracts/、.claude/handoffs/、CLAUDE.md、README.md 或 tests/performance/ 的所有权前,检查 references/frontmatter-spec.md §Resolved Conflicts(v1.0 → v1.1)。
  • 硬编码项目细节 — 全局技能不随项目变化,应使用 profile.yaml。

参考文件

  • references/frontmatter-spec.md — 完整字段参考,含类型、规则与示例
  • references/description-patterns.md — 编写有效触发描述的模板
  • references/body-template.md — Anthropic 推荐的 SKILL.md 正文结构,及各技能类型的偏差(智能体角色、元技能、编排器、工作流)
  • references/patterns.md — 五种架构技能模式(顺序工作流、多 MCP 协调、迭代精炼、上下文感知工具选择、领域特定智能)
  • references/quick-checklist.md — 交付前清单:frontmatter、description、正文长度、触发、交叉引用
  • references/performance-notes.md — 何时以及如何添加 Performance Notes 部分以对抗模型惰性
  • references/validation-script-pattern.md — 如何编写并接入确定性验证脚本