写在最前面实际上绝大部分的skill创作都可以通过安装skill-creator后再和Agent对话跑完整个流程直接要求Agent将整个流程处理成skill。文章目录1. Skill 是什么2. Skill 的物理结构3. 渐进披露 - Skill 的核心设计哲学4. YAML Frontmatter 规范4.1 必填字段4.2 可选字段4.3 description —— 唯一的触发信号4.4 关于 name 的约束5. SKILL.md 正文的常见骨架5.1 顶部 Quick Reference / 决策表5.2 Overview / When to use5.3 Workflow / Process阶段化流程5.4 Common Pitfalls / Anti-patterns5.5 QA / 自检 checklist5.6 Reference Files 索引6. 六种常见 Skill 形态模式库6.1 Router 型超轻量路由器6.2 Reference 型长期查阅手册6.3 Workflow 型多阶段流程6.4 Creative / Philosophy 型创作类6.5 Human-in-the-loop 型需要用户参与6.6 Toolkit / Script-first 型脚本包7. 写作风格与 prompt 语言技巧7.1 祈使句 说明为什么7.2 ❌/✅ 对照示例7.3 Read this file when X 指针7.4 STEP 0 强前置7.5 环境分支7.6 反过度积极7.7 Tone 元指令7.8 版本 pinning7.9 关键词尾巴8. 脚本、模板与资源目录的约定8.1 scripts/ 的黄金规则8.2 references/ 的黄金规则8.3 assets/ 的黄金规则8.4 templates/ 的黄金规则9. Skill 的评估与迭代闭环9.1 触发description测试9.2 输出内容评估9.3 断言assertions设计9.4 Benchmark 聚合与查看9.5 迭代规则9.6 打包发布10. 新手 30 分钟上手流程Quick Start步骤 13 分钟确定 skill 形态步骤 25 分钟新建目录 复制模板步骤 310 分钟写 SKILL.md步骤 45 分钟写 2–3 条测试 prompt步骤 55 分钟跑一次 with_skill vs without_skill步骤 62 分钟写下改进方向11. 常见反模式Anti-Patterns12. 参考内容1. Skill 是什么一个 skill 是一个文件夹里面至少有一个SKILL.md。这个SKILL.md就是给模型Claude / 其他 agent看的说明书告诉它什么时候应该调用这个 skill触发条件怎么做这项专门的任务步骤、模板、脚本、检查清单不该做什么反模式、边界。Skill 与 prompt 的差别在于prompt 是一次性输入skill 是可复用、可版本化、可迭代评估的能力单元。它可以被打包为.skill文件、发布到 marketplace、被多个 agent 共享。Skill 与 tool工具的差别在于tool 是模型可以直接调用的动作接口skill 是指导模型如何组合 tools 完成一类工作的知识包。一个 skill 里通常会自带若干脚本作为 “sub-tools”但真正的价值在文档本身。简言之Skill 一个装着 SKILL.md 的文件夹用来把某项专门知识装配到模型上下文里。2. Skill 的物理结构官方推荐的最小与完整目录结构skill-name/ # 目录名建议 kebab-case ├── SKILL.md # 必需YAML frontmatter Markdown 正文 ├── LICENSE.txt # 强烈建议非必需用于公开发布时的免责与产权的声明 ├── scripts/ # 可选可执行的确定性脚本Python/Node/Bash │ ├── main_tool.py │ └── utils.py ├── references/ # 可选按需加载的深度文档 │ ├── advanced.md │ └── schemas.md ├── assets/ # 可选产物中直接使用的静态资源 │ ├── template.html │ └── fonts/ ├── examples/ # 可选范例、样例输入输出 │ └── sample-input.md ├── templates/ # 可选起始模板如 HTML/JS 骨架 ├── agents/ # 可选子 agent 的 system prompt 片段 │ └── grader.md └── requirements.txt # 可选Python 依赖清单命名习惯与上面目录树严格对应目录 / 文件用途何时使用SKILL.mdSkill 主入口含 YAML frontmatter Markdown 正文必需LICENSE.txt完整 license 文本供 frontmatter 中的license字段指向非必需公开发布时推荐随 skill 一起分发scripts/确定性代码模型直接调用而不必读源码有重复性/可自动化的步骤时references/长参考文档模型「按需」读取单个 SKILL.md 装不下、或按主题拆分时assets/出现在最终产物里的资源字体、图标、模板需要打包到输出中examples/样例集正/反例、模板问答类目繁多SKILL.md 只做路由templates/起始骨架HTML/JS/JSON schema 等输出遵循固定模板agents/子 agent 的 system prompt 片段skill 会 spawn subagent 时requirements.txtPython 依赖清单Node 项目对应package.jsonscripts/ 里存在需外部依赖的脚本时约定 1文件夹名、namefrontmatter 字段、marketplace 中注册的 skill 名三者严格一致如pdf、docx、skill-creator。约定 2把 skill 视为「一个可移植的最小单元」——不要在 SKILL.md 里引用文件夹外的路径。3. 渐进披露 - Skill 的核心设计哲学Skill 的加载分三级写作时必须按这三级来切分内容层级加载时机大小预算承担内容L1 元数据namedescription永远在上下文中~100 词触发决策所需的最小信息L2 SKILL.md 正文skill 被触发后立刻加载建议 500 行核心工作流、决策树、路由到附属文件的指针L3 附属文件模型按需Read无限深度参考、模板、示例、可执行脚本核心原则L2 是路由不是百科全书。当 SKILL.md 快要超过 500 行、或某一节篇幅过大时就要把细节剥离到references/或examples/SKILL.md 里只留一句「如果要做 X请阅读references/x.md」。4. YAML Frontmatter 规范SKILL.md顶部必须以---分隔的 YAML 块开始。规范字段如下4.1 必填字段---name:my-skill-name# 唯一标识kebab-case与目录名一致description:一句/一段说明「这个 skill 做什么 什么时候应该被触发」。 这是 skill 唯一的触发信号务必写好。---4.2 可选字段version:语义化版本号# 建议字段当前各客户端尚未统一支持但有助于团队内版本管理license:Complete terms in LICENSE.txt# 或 Proprietarycompatibility:...# 依赖工具/环境较少使用4.3description—— 唯一的触发信号模型是否加载这个 skill几乎完全由description决定。因此这一字段既是电梯陈述也是路由规则。优质 description 的六个特征主动推销——skill 天然容易 undertrigger模型不主动使用。写法上略带push“Make sure to use this skill whenever the user mentions dashboards, data visualization, or wants to display any kind of company data — even if they don’t explicitly ask for a ‘dashboard.’”列出触发词/触发场景——把用户可能说的短语列出来例如PRD / RFC / design doc / write a docdoc-coauthoring。列出应当跳过的场景——用Do NOT trigger when …显式地划边界xlsx、docx。包含 TRIGGER / SKIP 路由头——参考claude-apiTRIGGER — read BEFORE opening the target file … SKIP only when another provider is being worked on …这把 description 从元数据升级为路由器。对创作型 skill加版权提醒——algorithmic-art / canvas-design / brand-guidelines都在 description 里加“Create original … rather than copying existing artists’ work to avoid copyright violations.”保持完整语境——不要写 “Format PDF”而写 “Fill out interactive PDF forms, extract text/tables from PDFs, redact content, or convert to images. Trigger whenever a.pdffile is mentioned.”4.4 关于 name 的约束全小写用连字符分隔单词kebab-case。不与其他 skill 冲突建议先用 marketplace 检索。与目录名严格一致重命名时同步.claude-plugin/marketplace.json。5. SKILL.md 正文的常见骨架正文没有强制结构但仓库中反复出现的高价值骨架有以下几种模块可按需拼装5.1 顶部 Quick Reference / 决策表在正文开头放一张任务 → 使用哪个方法/文件的表格。docx、pptx、claude-api等 skill 都用了这套。## Quick Reference | 任务 | 用什么 | | --- | --- | | 填写可交互 PDF 表单 | 阅读 forms.md | | 从 PDF 中提取文本 | 使用 pdfplumber | | 生成新 PDF | 使用 reportlab |价值模型进入 skill 后第一眼就能路由到正确的子路径而不必读完整个文档。5.2 Overview / When to use一段 3–5 行的自我介绍这个 skill 干什么、适用什么场景、不适用什么场景。放在 Quick Reference 之下、正式流程之上。5.3 Workflow / Process阶段化流程复杂的 skill 用编号阶段拆分mcp-builder用 4 个 PhaseDeep Research → Design → Implement → Evaluatedoc-coauthoring用 3 个 StageContext Gathering → Refinement → Reader Testingalgorithmic-art用 5 个大写阶段ALGORITHMIC PHILOSOPHY CREATION → DEDUCING THE CONCEPTUAL SEED → …。每个阶段下要写清目的、动作、检查点、进入下一阶段的准入条件。5.4 Common Pitfalls / Anti-patterns在 skill 末尾或阶段内显式列出过去失败过的写法。这一节的价值极高docx14 条 “Critical Rules for docx-js”pptxNEVER use accent lines under titlesweb-artifacts-builder反 “AI slop”避免居中布局、紫渐变、Inter 字体webapp-testingDO NOT read the source until you try running the script first。5.5 QA / 自检 checklist给出模型可对照打勾的 markdown checklistxlsx的 “Formula Verification Checklist”。让 QA 变成可执行动作而不是抽象要求。5.6 Reference Files 索引在末尾列出所有 L3 附属文件与何时读取## Reference Files - references/schemas.md — JSON 结构参考 - agents/grader.md — 判分子 agent 的 prompt6. 六种常见 Skill 形态模式库6.1 Router 型超轻量路由器代表internal-comms32 行适用一个大主题下有多个并列子领域每个子领域独立成文。结构When to use → How to use3 步识别 → 加载 examples/xxx.md → 执行→ Keywords。优点SKILL.md 极小永远不会撑爆 L2 上下文。6.2 Reference 型长期查阅手册代表claude-api578 行、brand-guidelines适用知识密集模型会反复回来查阅。结构Quick Reference 表 → 分主题参考 → Common Pitfalls。关键技巧description 中带TRIGGER/SKIP路由头支持子命令如/claude-api migrate显式 pin 版本“ALWAYS useclaude-opus-4-8— non-negotiable”包含 API drift 表stale vs current。6.3 Workflow 型多阶段流程代表skill-creator、mcp-builder、doc-coauthoring、webapp-testing适用任务需要多步骤、有明确产出物。结构分 Phase / Stage 编号每阶段有目标、动作、退出条件。关键技巧用 ASCII 决策树webapp-testing表达路径选择用环境分支处理有/无 subagent 场景doc-coauthoring、pptx用红队框架“Assume there are problems. Your job is to find them.”pptx。6.4 Creative / Philosophy 型创作类代表algorithmic-art、canvas-design、frontend-design适用输出是艺术/设计需要模型有诠释空间。结构先写创作理念4–6 段风格宣言再写执行细节。关键技巧Philosophy Execution 两步法先让模型写一份小型艺术运动宣言再基于宣言生成产物明确 FIXED vs VARIABLE 部分“模板结构不动只替换算法/参数”反 AI slop显式列出模型的默认平庸倾向并禁用frontend-design的三种默认外观、web-artifacts-builder的紫渐变Inter。6.5 Human-in-the-loop 型需要用户参与代表theme-factory适用产出前必须由用户挑选/确认。结构4 步——向用户展示 showcase → 请用户选择 → 等待选择 → 应用选择。关键技巧把等待用户作为流程的合法节点而不是打断。6.6 Toolkit / Script-first 型脚本包代表slack-gif-creator、docx、pdf、pptx、xlsx适用任务本质是数据处理/文件生成脚本比 prompt 更可靠。结构SKILL.md 说明何时调哪个脚本具体逻辑在scripts/。关键技巧让脚本--help自解释明确要求不要读脚本源码webapp-testing以省 token提供字段/颜色/格式的固化规范xlsx的财务模型颜色约定蓝输入、黑公式、绿跨表、红外部、黄关键假设。7. 写作风格与 prompt 语言技巧Skill 的正文本质是给模型看的 prompt。7.1 祈使句 说明为什么避免堆砌全大写MUST/NEVER而是解释这么做的原因。模型有 theory of mind理解原理后能举一反三纯命令则只在原例上生效。反例NEVER use requests library.正例Prefer httpx over requests because we need async support and requests is not maintained upstream.只有在真的踩过多次坑、必须硬性阻止时才使用NEVER/ALWAYS全大写形式。7.2 ❌/✅ 对照示例给出错误写法与正确写法并列docx、xlsx、web-artifacts-builder广泛使用❌ WRONG: ws.cell(row10, column2).value 15234.5 ✅ CORRECT: ws.cell(row10, column2).value SUM(B2:B9)对照示例比抽象规则的 signal 强 5 倍。7.3 “Read this file when X” 指针L2 到 L3 的路由必须具体、条件化If you need to fill out a PDF form, read forms.md and follow its instructions.避免“see references for more info”模糊、模型不会真的去读。7.4 STEP 0 强前置对于容易被跳过的关键前提读模板、跑 --help显式立成 “STEP 0”### ⚠️ STEP 0: READ THE TEMPLATE FIRST ⚠️ Do not start coding until you have read templates/base.html in full.7.5 环境分支skill 可能运行在 Claude Code、Claude.ai、Cowork、其他 agent 环境中用If access to sub-agents is available:/If not:显式分叉避免模型走错路径。7.6 反过度积极有时需要叫模型别做web-artifacts-builder“avoid testing the artifact upfront as it adds latency”docx“Do not write Python scripts — use the Edit tool directly”webapp-testing“DO NOT read the source until you try running the script first”模型默认过度积极显式的少做指令能省大量 token。7.7 Tone 元指令想控制模型对用户说话的语气就写一节Tips for Effective Guidancedoc-coauthoring“Be direct and procedural. Don’t try to ‘sell’ the approach — just execute it.”7.8 版本 pinning对易漂移的字段模型 ID、SDK 版本明确 pin 值并说明non-negotiable。参考claude-api。7.9 关键词尾巴在文末列一个Keywords:短列表internal-comms、brand-guidelines补充 description 中未覆盖的同义词/触发词。8. 脚本、模板与资源目录的约定8.1 scripts/ 的黄金规则每个脚本都有--help——模型第一步永远是python scripts/foo.py --help。默认黑箱调用不读源码——脚本可能几百上千行读进上下文会拖慢模型。SKILL.md 应显式说 “call as black-box; do not ingest source unless customization is required”。脚本命名保持稳定——重命名等于破坏 skill 使用者的记忆。在 SKILL.md 里给出可复制粘贴的完整命令python scripts/aggregate_benchmark.pyworkspace/iteration-N --skill-namename依赖用requirements.txtPython或package.jsonNode声明。8.2 references/ 的黄金规则单文件超过 300 行时必须在文首放 TOC每个文件的开头写一句什么时候读这个文件交叉引用其他 references 时使用相对路径references/xxx.md。8.3 assets/ 的黄金规则仅存放最终产物中直接使用的资源模板、字体、图标大二进制字体、PDF用 LFS 或子仓库。8.4 templates/ 的黄金规则明确 FIXED不可改与 VARIABLE可替换区域在 SKILL.md 中把这一区分写死。9. Skill 的评估与迭代闭环skill-creator沉淀了一套完整的「写 → 测 → 评 → 改」的闭环值得作为标准工作流引入你自己的 skill 项目9.1 触发description测试从用户是否会说这句话时期望被触发角度构造 20 条 query一半 should-trigger、一半 should-not-triggernear-miss 越多越有信息量。用run_loop.py迭代优化 description。关键点should_not_trigger必须是貌似相关但其实不该触发而不是显然无关的问题——否则测试没有 signal。9.2 输出内容评估对每个测试 prompt同时跑with-skill加载 skill 的版本baseline不加载 skill新 skill或加载旧版改进 skill。结果按iteration-N/eval-K/{with_skill,without_skill}/outputs/组织。9.3 断言assertions设计每条测试 prompt 配套若干断言grading.json中的expectations命名要读得懂——输出包含 SUM(B2:B9) 公式好过assertion_3可编程校验的断言优先——写脚本判分而不是眼球判分主观类断言不要硬凑——设计/写作类交给人类打分。9.4 Benchmark 聚合与查看benchmark.json的 schema详见skill-creator/references/schemas.md字段名严格configuration必须是with_skill或without_skillpass_rate/time_seconds/tokens必须嵌套在result下。用eval-viewer/generate_review.py生成的 HTML 视图给人类看让他填feedback.json做定性反馈。9.5 迭代规则从反馈里泛化——不要只修 3 个测试例要理解背后共通的失败模式保持 prompt 精简——如果一段话没贡献信号删掉解释为什么——见 §7.1横向发现重复劳动——如果 3 次运行都独立写了同一个脚本把它内置到scripts/。9.6 打包发布python scripts/package_skill.pypath/to/skill-folder产出.skill文件本质是 zip。marketplace 通过.claude-plugin/marketplace.json注册。10. 新手 30 分钟上手流程Quick Start如果你是第一次写 skill按下面顺序做30 分钟内可跑通闭环步骤 13 分钟确定 skill 形态对照 §6问自己三个问题有多少子领域多 → Router 型少 → Workflow 型。是流程还是查阅流程 → Workflow查阅 → Reference。是创作还是确定性创作 → Philosophy确定性 → Toolkit。步骤 25 分钟新建目录 复制模板mkdir-pmy-skillcptemplate/SKILL.md my-skill/SKILL.mdcpLICENSE.txt my-skill/LICENSE.txt# 如需步骤 310 分钟写 SKILL.md按下面骨架填空--- name: my-skill description: 【一句话说做什么】。Trigger whenever 【触发条件A】、【触发条件B】、 or 【触发条件C】. Do NOT trigger when 【排除条件】. license: Complete terms in LICENSE.txt --- # My Skill ## Overview 【3–5 行自我介绍】 ## Quick Reference | 任务 | 使用 | | --- | --- | | ... | ... | ## Workflow ### Step 1: 【动作】 ### Step 2: 【动作】 ## Common Pitfalls - ❌ ... - ✅ ... ## Reference Files - references/xxx.md — 何时读它步骤 45 分钟写 2–3 条测试 prompt{skill_name:my-skill,evals:[{id:1,prompt:真实用户会说的话1,expected_output:…},{id:2,prompt:真实用户会说的话2,expected_output:…}]}步骤 55 分钟跑一次 with_skill vs without_skill用skill-creator提供的脚本或手动 spawn 两个子任务。看两组输出的差别决定如果 with_skill 明显更好 → 进入迭代如果几乎一样 → skill 没提供信号回炉重写如果 with_skill 更差 → skill 在误导模型找出误导点。步骤 62 分钟写下改进方向在 skill 目录旁开一个NOTES.md记录本轮观察 下一版打算改哪里。进入下一轮迭代。11. 常见反模式Anti-Patterns反模式症状修法Description 过短或抽象Skill 从不被触发加触发词、场景、“push” 语气参考 §4.3一切写在 SKILL.md文件超过 800 行模型加载后仍找不到重点拆到references/SKILL.md 只留路由MUST/NEVER 泛滥模型死板、无法泛化到新场景改为因为 X所以 Y参考 §7.1抽象指令“Format properly”、“Handle appropriately”换成具体步骤 ❌/✅ 例子没有 Common Pitfalls常见坑反复被踩补一节反模式清单触发关键词太宽过度触发、抢占其他 skill加Do NOT trigger when …脚本不带 --help模型强行读源码浪费 context加 argparse 明确文档在 skill 之间硬编码路径打包/移植失败只使用 skill 内相对路径12. 参考内容Anthropic public claude skillsSpecification for Agent Skills