如何用Cole's AI Skills的skills-create技能写出你的第一个SKILL.md?

原创2026-11-01 16:37:581,870 阅读

如何用Cole's AI Skills的skills-create技能写出你的第一个SKILL.md?

Cole's AI Skills 是一套为编码 Agent(如 Claude Code)准备的开源技能集合,其中 skills-create 是一个"元技能"(meta-skill)——专门用来帮你创建新技能的技能。如果你发现同样的提示词自己重复输入了 3 次,就值得把它沉淀成一个 SKILL.md。本文带你完整走一遍 skills-create 的工作流,从零写出你的第一个结构规范的技能。

📥 获取代码:git clone https://gitcode.com/gh_mirrors/skills57/skills,所有技能都在 .claude/skills/ 目录下,每个技能就是一个文件夹。

什么是 Skill?一个文件夹 + 一个 SKILL.md

Skill 的结构非常朴素:一个文件夹,里面放一个 SKILL.md,核心就三要素:

  • name:技能名(小写连字符命名,如 skills-create)
  • description:什么时候用 + 触发它的字面短语
  • 正文(body):Agent 匹配到任务后要遵循的操作步骤

Agent 启动时只加载所有技能的 description(占用极少的上下文),任务真正匹配时才读完整的 SKILL.md——这就是 progressive disclosure(渐进披露) 机制,也是技能比一份 2000 行的 CLAUDE.md 更能规模化的原因。

一个标准技能文件夹长这样:

skill-name/
├── SKILL.md          # 必需:YAML frontmatter + Markdown 正文
├── references/       # 按需读取的细节资料
├── templates/        # 输出要遵循的固定形状
└── scripts/          # 直接执行的脚本

📌 一个实用的阈值(Rule of Three):同一件事你提示过 ~3 次,就该做成技能;一次性任务不值得,别人的工具已有好技能时也别重复造。

第一步 — 收集上下文:先定"何时触发"

skills-create 的第一步不是写代码,而是收集上下文(见 references/creating-skills.md)。它只会问你四类问题:

  1. Triggers(触发词):你会输入/说出哪些话就该触发这个技能?收集 3–6 个具体短语
  2. Task(任务):从头到尾做什么,最终产物是什么
  3. Gotchas(坑点):非显性的领域知识、仓库中要参照的既有模式
  4. Scope boundary(边界):一个技能 = 一个能力,两个不相关的能力就拆成两个技能

实际使用时,直接说"用 /skills-create create <技能名>",或者随口一句"帮我把这段 prompt 变成技能",它就会开始提问。

第二步 — 规划资源:什么内容放哪里

在动笔前,把任务的每个部分分好类。这是技能设计里最容易被跳过、也最影响质量的一步:

内容类型 放哪里
每次都要跑、要确定性高的代码 scripts/
参考性细节(schema、模式、边缘情况) references/
输出要遵循的固定形状 templates/
不归属你、上游可能变的内容 正文里引用路径/URL,不要拷贝
只有运行时才存在的信息 指示 Agent 运行时自行收集

把这串清单写下来,它就是技能的蓝图。

第三步 — 创建骨架:复制官方模板

skills-create 自带一个开箱即用的骨架 SKILL.template.md:

mkdir -p .claude/skills/<name>
cp .claude/skills/skills-create/templates/SKILL.template.md .claude/skills/<name>/SKILL.md

两条命名规则要记住:目录名用 lowercase-hyphen;目录名就是斜杠命令名(my-skill/ 文件夹对应的就是 /my-skill)。

第四步 — 先写主干:description 是触发的关键

核心原则叫 progressive success:先让最小版本能被触发、能跑起来,再回头补 reference 细节。一个不触发的技能,比没人读到的完美参考资料更值得优先修复。

写 description 的要点(规则详见 references/skill-standards.md):

  • ✅ 用第三人称,先说明它做什么
  • ✅ 再写 "Use when …",原样引用第一步收集的字面触发短语
  • ✅ 包含 /name 调用方式
  • ✅ 控制在 1024 字符以内

skills-create 自己的 description 就是个范本:

Author a new Claude Code skill the house way, or refactor a fat skill into a lean SKILL.md + references/. Use when you want to "create a skill", "write a new skill", … or invoke /skills-create.

正文则遵循另外两条规则:祈使句、动词开头,目标 1,500–2,000 词;大块细节推到 references/,正文只留一行指针。最后加一个 Resources 部分列全你打包的每个文件——不接线(wiring)的文件,Agent 就不知道它的存在。

第五步 — 验证:上线前的 7 道关卡

写完后,按 references/validation.md 逐关过一遍:

关卡 检查什么
Gate 1 结构 SKILL.md 存在、frontmatter 合法、没有死指针
Gate 2 Description 第三人称、有字面触发短语、说清 WHAT + WHEN
Gate 3 正文 全程祈使句、篇幅达标
Gate 4 渐进披露 大块细节不在正文、正文与资源零重复
Gate 6 独立评审 让另一个 Agent 做 fresh-eyes 检查
Gate 7 触发测试 最关键:用触发短语描述真实任务,确认技能自动加载,然后端到端真跑一次

⚠️ 不要止步于"它加载了"——真实任务一跑,才会暴露加载检查永远发现不了的 bug。

进阶:把臃肿的 SKILL.md 做瘦身重构

技能写多了,迟早会遇到 SKILL.md 越长越肥的问题。skills-create 的第二个模式 refactor 就是干这个的(详见 references/refactoring-skills.md):

  1. 把每块内容分类为 spine(保留) 或 extractable(移出)
  2. 原样搬移到 references/ 或 templates/——影响行为的内容一个字都不要改写
  3. 用指针替换:永远需要的内容配 mandatory-read 语句,偶尔才用的内容用懒指针
  4. 行为保持检查:重构前后的流程与输出必须一致,丢了什么、重复了什么都不行

重构的头号风险,是把"永远需要的输出格式"搬进了懒加载,导致输出悄悄变化——记得始终配上 mandatory-read 语句来对冲。

Skill 在整个 AI Layer 中的位置

技能是 AI Layer 的程序性一半,仓库里的 hooks/ 是另一半:在生命周期事件上确定性触发的代码。两者的差别一句话就能说清——规则是"请求"Agent 守规矩,hook 是"保证"它守规矩。想加防护的话,hooks/README.md 里有 6 个即拷即用的 hook。

Cole's AI Skills 的 AI Layer 与 SKILL.md 技能体系架构图:从规格到无人值守交付的自动化编码系统

上图出自 build-dark-factory 技能:一个由技能体系支撑、从需求规格到合并交付全程无人值守的"暗工厂"——这正是把技能用出上限后,你的项目可以到达的方向。

小结:记住 3 件事就够了

  1. 一个技能 = 一个能力:一个文件夹 + 一个 SKILL.md,目录名即命令名
  2. description 是触发器:第三人称 + 字面触发短语,写得好才能被"找到"
  3. 渐进披露:正文只放决策主干,细节进 references/,写完用触发测试验证

下次当你第 4 次敲同一句 prompt 时,打开终端运行 /skills-create create <名字>,你的第一个技能就只差验证这一关了。

登录后查看全文
skills