如何深度写 Skill · 通用方法论 + 建 Skill SOP 体系

这份是「以后建任何 skill 都照着做」的总纲。比基础版深在三处：① 把「建 skill」从写文档升级成测试驱动的循环；② 补全选型(建之前)和运维(建之后)两端；③ 五来源交叉印证、给原文引用和实测数字。 配套可操作产物：一个元 skill skill-smith（建 skill 时自动触发，给作业流程+模板+校验）。本文是「理论+全量」，元 skill 是「执行+速查」。

TL;DR · 一页看懂（10 条铁律）

  1. 建 skill 不是写文档，是测试驱动的循环：先看「不带 skill 会怎么失败」(baseline) → 写最小 skill → 红队找它新漏洞 → 堵 → 重测。没有失败测试就不写 skill（superpowers 钦定，对新建和修改都成立）。
  2. 官方钦定顺序：先建 eval，再写文档（skill-creator 原话 “Create evaluations BEFORE writing extensive documentation”）。
  3. 最小合法 skill = 一个文件夹 + 一个 SKILL.md + 两个 frontmatter 字段(name, description)。其余全 optional。本机 130 个 skill 实证：只有 name+description 是 100% 普适标准。
  4. description 是触发的唯一杠杆：写「是什么 + 何时用(pushy、塞满触发词、even if not explicitly)+ Do NOT 反例」。实测 directive(“ALWAYS invoke”)触发率 100% vs passive(“use when”)37%(odds 20.6×)。但绝不在 description 里概括多步 workflow（agent 会照 description 瞎编、跳过正文）。
  5. 三层渐进披露省上下文：L1 元数据(~100token，常驻) / L2 SKILL.md body(<500行，命中才读) / L3 scripts+references+assets(按需，脚本黑盒跑不进上下文)。
  6. scripts vs references vs assets：要跑的确定性逻辑(尤其跨用例重复写的)→scripts(不进上下文)；要读懂的长知识(按变体拆)→references；要塞进产物的成品料→assets。
  7. 先分类失败，再选 skill 形式(Match Form to Failure)：纪律违规→禁令+借口表+红旗；输出形状错→正面契约/模板(此时禁令反噬)；漏必填→REQUIRED 槽位模板；条件行为→挂可观察谓词。选错形式适得其反。
  8. 验证是 skill 的一等公民：生成→跑校验脚本→失败自动修→重打包(文档类)；或独立 eval harness 量化 with/without 差距(复杂类)。判通过靠客观信号(日志/退出码/schema)不靠肉眼，迭代有硬上限防死循环。
  9. 写作风格：祈使句、解释 why(给原因比 all-caps MUST 更稳，满篇大写是”黄旗”)、❌WRONG/✅CORRECT 成对、面向聪明 LLM 写 harness 而非死规则。
  10. 改 skill 三纪律：泛化别 overfit、保持精简(加规则不涨分就删)、读 transcript 找跨用例重复劳动→固化成脚本。

〇、先想清楚：该不该做成 skill —— 原语选型决策表

建 skill 前先问「这需求是不是 skill 该解决的」。原语不是竞争，是分层组合。

需求本质选哪个原语判据
「每次/从今往后 X 都必须 Y」自动行为、铁律、确定性强制Hook(settings.json)只有 harness 执行的 hook 能 100% 触发；记忆/偏好/skill 做不到「自动」(skill 是模型自愿遵守)
反复粘贴的多步流程/清单/方法论/判断标准Skill”keep pasting the same instructions/checklist/procedure”；或 CLAUDE.md 某节从「事实」长成了「流程」
有副作用、要手控触发时机(部署/提交/发消息)Skill + disable-model-invocation:true= 受控 slash command（slash command 已并入 skill，/x 即 skill）
副任务会刷屏、产一堆用完即弃的中间物、要并行Subagent(.claude/agents)“flood your main conversation with output you won’t reference again”；隔离上下文防污染
连外部系统/DB/第三方 API、把数据搬进对话MCP serverskill 编排「怎么做」，MCP 提供「能做什么」；一个 skill 常内部 call 多个 MCP 工具
始终在场的事实/红线/人设/项目约定CLAUDE.md / memory是「事实」留这；长成「流程」就拆成 skill

三组最易混的边界：

  • Skill vs Hook = 软(可能不触发、会被绕) vs 硬(确定性必发)。能用 regex/退出码卡死的死规矩 → 做 hook，别写成 skill；skill 留给需要 judgment 的活。
  • Skill vs Subagent = 主上下文里走流程 vs 派出去隔离执行。重活/会刷屏/要并行 → subagent（skill 可加 context:fork+agent: 把正文当 prompt 丢给 subagent）。
  • Skill vs MCP = 剧本(怎么做) vs 能力(能做什么)。

一个真实项目实例：生图 SOP = hook(shengtu_sop_guard.py 硬注入提醒) + skill(shengtu-router 软流程) + 子skill(mj-prompt-* 模板库)。三层并举正是这张表的落地。

一、Skill 是什么 + 三层渐进披露（深化版）

1.1 三层加载模型

L1  启动即常驻   ~100 token/skill        name + description (frontmatter)
      ↓ Claude 据 description 判断相关
L2  命中才读     SKILL.md body  <500行/<5k token  (流程/索引/速查)
      ↓ 需要才读
L3  按需才读     references/scripts/assets  无硬上限
                 · references = 读进上下文的长知识
                 · scripts    = 执行但代码不进上下文(黑盒)
                 · assets     = 塞进产物的成品料
  • <500 行 / <5k token / L1≈100token / 引用只一层深——这四个数字在 best-practices、Claude Code doc、agentskills spec、skill-creator 源码四处完全一致，是确定无疑的官方硬指标。
  • L3 是省上下文的关键：脚本执行时代码本身不进上下文(只有输出计数)，所以重逻辑做成黑盒脚本——webapp-testing 明示「当 black box 直接调，先跑 --help，别读源码污染上下文」。
  • 引用只许一层深：所有 references 直接从 SKILL.md 链接，别 SKILL.md→a.md→b.md 嵌套——模型常只 head 预览读第一层，深层读不全。
  • 大 reference 文件(>300 行)开头放目录(TOC)，让模型 grep 定位、按需读片段。

1.2 运行期真相（基础版没讲、极重要的坑）

  • skill 载入后整段跨 turn 常驻、不会重读：所以正文写「常驻指令」别写「一次性步骤」（写「每次发送前校验 X」而非「现在执行第 3 步」）。
  • auto-compaction 后每个 skill 只留前 5000 token，所有重挂 skill 共享 25000 token 预算；大 skill 压缩后会变弱，可能要重新 /调用 一次。
  • description listing 总预算只占 model context 的 ~1%，溢出时最少被用的 skill 的 description 先被砍 → 关键 use case 必须写在 description 最前面。
  • skill 数量多时这是真实约束：别为每个微小变体建独立 skill，能合并就合并、能 router 就 router。

二、SKILL.md 完整规范：frontmatter 三套标准

⚠️ 必须分清三套字段标准，混用会校验失败或跨产品不兼容：

标准字段集用途
开放标准 / API（最严，6 字段）name, description, license, compatibility, metadata, allowed-tools跨产品可移植的 skill 只能用这 6 个；skill-creator/quick_validate.py 硬校验，出现表外字段=失败
Claude Code 超集（~17 字段）上面 6 个 + when_to_use, disable-model-invocation, user-invocable, disallowed-tools, context:fork, agent, paths, model, effort, hooks, shell 等只在 Claude Code 跑的 skill 可用；给别的产品用就别碰这些专有字段
本机 hermes 约定（自定义 metadata）metadata.hermes.{tags, category, related_skills, homepage}项目内部组织用

必填/选填 + 硬限制

字段必填限制说明
name✅kebab-case ^[a-z0-9-]+$，≤64，不能首尾连字符/连续 --，且必须=父目录名命令名来自目录名，frontmatter name 只是显示名
description✅≤1024(开放标准) / Claude Code 截到 1536；不能含尖括号 </>决定触发，注入 system prompt
license❌—官方 skill 都带，自用可省
compatibility❌≤500 字符环境/依赖；「大多数 skill 不需要」
metadata❌键值对author/version/自定义(hermes)
allowed-tools❌空格分隔，标注 Experimental收窄工具面；本机仅 7 个 skill 用(deploy/higgsfield)
  • 没有顶级 version 字段（本机 84 个 skill 把它塞 metadata.version，但开放标准不认；真正的版本管理交给 plugin 层的 plugin.json）。
  • 本机实证：130 个 skill 里只有 name+description 是 100%；metadata 66%、version 65%、platforms 41%、license 22%、allowed-tools 5%。结论：frontmatter 最小集就是 name+description，别堆没用的字段。

三、description 工程 —— 触发的唯一杠杆（全报告最关键一节）

3.1 触发的底层真相（先懂机制再写）

  1. 启动把所有 skill 的 name: description 注入 system prompt。用户提任务 → Claude 据 description 关键词+语义+排他性选 skill → 选中才 bash 读 SKILL.md 整篇。
  2. Claude 只对「自己搞不定的复杂多步任务」才触发 skill；“read this PDF” 这种一步简单查询，即使 description 完美匹配也可能不触发（基础工具能直接干）。→ 写 eval query 别用平凡任务。
  3. Claude 天生倾向 undertrigger(该用 skill 时不用)——所以 description 要写得主动、pushy。

3.2 实测数字（650 次触发率研究，硬证据）

  • directive 变体(“ALWAYS invoke this skill when…”) 触发率 100%；passive(“use when…”) 37%；odds 比 20.6×(p<0.0001)。
  • Hook 悖论：pre-prompt hook 配 passive description 反而把触发率降到 ~90% 的反效果，要配 CLAUDE.md 才救回。→ 想靠 hook 救触发，description 本身也得是 directive。
  • description 超 ~250 字符的关键触发词若排在后面会被弱化/截断 → 触发词前置。
  • git 类 skill 最难触发(69%)——Claude 偏好直接用 Bash，要在 description 里写负向约束(“Do not use Bash git directly”)堵默认绕法。

3.3 ⚠️ 三方张力 + 调和（必须知道，否则会写矛盾）

来源主张
superpowersdescription 只写「何时用」，绝不概括 workflow/process
Anthropic 官方description 写「what + when」
650 实测directive(“ALWAYS invoke”)最强

调和方案（综合三方）：description =

第三人称 + 简短点明能力/领域(what，一句) + 密集触发词/同义词/文件类型(when，写满) + directive 框架(“Use/ALWAYS use this skill when…even if not explicitly…”) + “Do NOT trigger when <near-miss 反例>” + (有红线就内嵌一句)

但绝不写多步流程的顺序/步骤（那是 body 的活）。

为什么不能概括 workflow（Jesse Vincent 原话+实案）：description 写成 “code review between tasks” → agent 只做了一次 review，尽管流程图画了两次。机制：「When Claude thinks it knows what a skill does, it’s more likely to believe it’s using the skill and just wing it, even if it hasn’t read it yet.」概括 workflow = 给 agent 造了条会抄的捷径，正文变成被跳过的文档。

3.4 description 公式 + 官方原文样本（可直接套）

<动名词/名词短语说 what> + Use this skill when <列举触发语境/用户措辞/文件类型，pushy、含"even if not explicitly"> [+ Do NOT trigger when <near-miss 反例界定边界>] [+ <红线/版权约束句>]

官方逐字样本：

  • xlsx（最佳范例，强反触发）：…Trigger especially when the user references a spreadsheet file by name or path — even casually ("the xlsx in my downloads")…. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved.
  • pptx（穷举触发词）：…Trigger whenever the user mentions "deck," "slides," "presentation," or references a .pptx filename, regardless of what they plan to do with the content afterward.
  • algorithmic-art（嵌红线）：…Create original algorithmic art rather than copying existing artists' work to avoid copyright violations.

本机长度甜区：~150–470 字符(中位 212 / p90 471)；超 600 基本是「description 越权干 body 的活」(反例 wechat-group-daily-poster 把 7 段结构/尺寸全塞进触发字段)。多触发词用 YAML | 或 > 块标量写（本机 43 个 skill 这么干）。

四、SKILL.md body 写法

4.1 通用骨架模板（从 17 个官方 skill 收敛）

---
name: kebab-case-name
description: <what> + <when, pushy, 含 Do NOT 反例>
---

# <Skill Title / Guide>

## Overview            ← 1-3 句定位（这 skill 解决什么）
## Quick Reference     ← 表格前置：任务|工具|命令（不读全文也能干常见活）
## <核心 workflow 分节> ← 按步骤/按任务/按变体组织
## Critical Rules / Pitfalls   ← ❌WRONG vs ✅CORRECT 成对示例
## Reference Files     ← 列 references/* 和 scripts/*，**注明"何时去读"**
## Dependencies        ← 需要的库/CLI
  • 复杂执行型 skill 体量 ~230–590 行(docx 590/skill-creator 485)；简单参考/路由型 32–73 行(internal-comms 32/theme-factory 59)。没有一个官方 skill 突破 ~600 行——超了拆 references。
  • 本机实证：SKILL.md body 目标 ~100–170 行(中位 124)，超过就把操作细节/模板/长清单下沉 references(带”加载时机”列)。
  • Reference Files 路由段是灵魂：结尾列 references/scripts，关键带”何时读”指引(pdf:“If you need to fill out a PDF form, follow FORMS.md”；mcp-builder:“Load During Phase 2”)。

4.2 scripts vs references vs assets 真实切分判据

目录装什么载入方式判据/官方实例
scripts/确定性、重复性、跨用例会被重写的逻辑执行而不进上下文(黑盒)skill-creator 第4改进原则点破：「3个测试都各自写了类似 build_chart.py → 写一次放 scripts/」。例 xlsx/recalc.py、docx/office/unpack.py。“当 black box，先跑 —help，别读源码”
references/要读懂的长知识，按变体/语言拆只读相关那份按需 Read 载入mcp-builder 拆 python(718行)/node(969行)，只读用到的语言。>300 行带 TOC
assets/要塞进最终产物的成品料复制/嵌入进产物canvas-design/canvas-fonts(40+真字体)、web-artifacts/shadcn-components.tar.gz、theme-factory/themes

一句话：要跑的→scripts(不进上下文)/要读懂的→references(按需载入)/要进产物的→assets。目录名不是死规矩(slack-gif 用 core/、algorithmic-art 用 templates/)，职能划分才是。

4.3 写作风格（官方反复强调）

  • 祈使句；解释 why——「今天 LLM 很聪明、有 theory of mind，给好 harness 能超越死指令」，写满 all-caps ALWAYS/NEVER 是黄旗，改成「Do X because Y causes Z」。
  • ❌WRONG / ✅CORRECT 成对教学(官方极爱)。
  • 面向「聪明的 LLM」写 harness，而非穷举死规则。
  • 例外：discipline 类(纪律强制)反而要用 Authority 强措辞——见下节 Match Form to Failure。

五、⭐ 测试驱动建 Skill 全流程 SOP（融合 superpowers TDD + skill-creator 五阶段）

这是「建 skill」的核心方法论。两套权威方法本质同构，融合如下：

RED → GREEN → REFACTOR 心智（superpowers，钦定级）

“Writing skills IS Test-Driven Development applied to process documentation.” 铁律：NO SKILL WITHOUT A FAILING TEST FIRST（对新建和修改都成立。先写 skill 再补测 = 删掉重来）。 “If you didn’t watch an agent fail without the skill, you don’t know if the skill teaches the right thing.”

完整五阶段（skill-creator 官方 SOP，逐阶段动作）

阶段 A · 创建（动手前必做）

  1. Capture Intent：从当前对话抽意图(用过的工具、步骤顺序、用户纠正、输入输出格式)。
  2. 问 4 个澄清问题（官方钦定第一步，需求不够具体严禁动手）： ① 这 skill 让 Claude 能做什么？ ② 何时触发(什么用户措辞/语境)？ ③ 期望输出格式？ ④ 要不要设测试用例(可客观验证的→建议设；主观如写作风格/艺术→可不设)？
  3. Interview & Research：问 edge case、示例文件、成功标准、依赖；有 MCP/subagent 就并行调研类似 skill。
  4. 写 SKILL.md 草稿(name/description/body)。
  5. 造 2-3 个真实用户会说的测试 prompt，给用户确认，存 evals/evals.json（此时只写 prompt 不写 assertion）。

阶段 B · RED 跑 baseline + 评测（一气呵成别中途停）

  • 同一回合同时 spawn 两个 subagent：with-skill 一个、baseline 一个(新建=无skill；改进=先 cp -r 快照旧版当 baseline)。必须 fresh/clean context，否则作者残留上下文会假通过。
  • 等跑时并行起草 assertion(客观可验、命名清晰、discriminating——skill 真做对才过)。
  • subagent 完成通知里带 total_tokens/duration_ms → 立刻存 timing.json(唯一时机，过期不可恢复)。
  • 全跑完：grade(spawn grader 子agent 判 assertion，能脚本验就别肉眼看)→ aggregate(mean±stddev+delta)→ analyst(找非区分 assertion/高方差)→ 起 eval-viewer 让人评(别自己手写 HTML)。

阶段 C · GREEN+REFACTOR 改进（循环的心脏）

  • GREEN：只针对你观察到的具体失败写 skill，别为假想加内容(YAGNI)。带 skill 重跑，该遵守了。
  • REFACTOR(堵漏)：agent 还找到新借口? 每个逐字抓下来，加四件套：① 规则显式否定 ② rationalization(借口)表加一行 ③ red flags 加一条 ④ description 加「即将违规」的症状词。重测到 bulletproof。
  • 改进三铁律：
    1. 泛化别 overfit——skill 要被用百万次，别为这几个例子做 fiddly 改动/压迫式 MUST。
    2. 保持精简——读 transcript(不只读最终输出)，发现 skill 让模型瞎忙就删那段；加规则不涨分=过约束，要删。
    3. 解释 why + 找重复劳动固化成脚本——3 个测试都各自写了同一个脚本→放进 scripts/。

阶段 D · description 触发率优化（独立子系统）

  • 造 20 条 trigger query(8-10 should-trigger + 8-10 should-not-trigger，后者用 near-miss：共享关键词但实际要别的工具)。
  • 自动 60%train/40%test 切分(防 overfit) → 每 query 跑 3 次取触发率 → 让 Claude 提改进 → 重评，迭代 ≤5 次 → 按 test 分(非 train 分)选 best_description。

阶段 E · 打包：package_skill.py 打成 .skill(zip)，打包前自动跑 frontmatter 校验，evals/ 不打进包。

轻量替代法（没有 eval 基建时）—— Claude A/B 双实例

用一个实例(A)写/改 skill，另一个干净实例(B)加载 skill 跑真实任务，观察 B 在哪栽 → 带具体观察回 A 改。官方明确：不需要「写 skill 的 skill」或特殊系统提示，直接叫 Claude 写即可。

micro-test 措辞法（全场景测太慢太贵时）

先用小测验：每变体 ≥5 次重复、永远带 no-guidance 对照(对照不犯错就别写这条规则)、手读每个命中、“方差是个指标”(5 次 5 种解读=措辞不够硬)。选错时直接 meta-test：问 agent「这 skill 该怎么改写才能让正确答案成为唯一答案」。

六、⭐ Match Form to Failure —— 先分类失败，再选 skill 形式（极易选错）

选错形式适得其反。先判断 baseline 暴露的是哪类失败，再用对应形式：

失败类型用什么形式⚠️ 别用什么
纪律违规(该做没做、走捷径、找借口)禁令 + rationalization(借口)表 + red flags 清单 + Authority 强措辞(YOU MUST/No exceptions)—
输出形状错(结构/顺序/格式不对)正面配方/契约(直说输出是什么、什么顺序) + REQUIRED 模板❌禁令——塑形问题用禁令会反噬，产出更多坏内容
漏必填元素模板设 REQUIRED 槽位—
条件行为(某情况下才做某事)挂可观察谓词的条件式(“if console shows X then…”)—

配套强约束写法：

  • 不加 nuance 条款(“don’t X unless…” 会重开谈判，把稳定变噪声)；要豁免就重构让规则够不着，别写 exception 子句。
  • 堵每个具体漏洞、点名禁绝(“别留作 reference / 别 adapt / 别看它 / 删就是删”)。
  • 早放根基原则斩断一整类借口：“Violating the letter is violating the spirit.”
  • persuasion 七原则(N=28000 实测，合规 33%→72%)：discipline 用 Authority + Commitment(宣告用 skill/强制选择/建 todo) + Social Proof(“…every time”)；别用 Liking/Reciprocity(制造谄媚)。

七、验证与评测 —— skill 的一等公民

7.1 两种验证范式（官方 skill 实证）

  • A. 生成后即验闭环(文档类 docx/pptx/xlsx)：创建文件→跑校验脚本(39 个 XSD schema 校 OOXML)→失败就 unpack 改 XML 重 pack→修到 ZERO 错误。验证脚本是 skill 标配。
  • B. 独立 eval harness(skill-creator/mcp-builder)：量化 with-skill vs baseline 的 pass_rate(mean±stddev)/token/time/delta。

7.2 验 skill 质量的工程做法（取自腾讯 wxa-skills-validate/eval，建 skill SOP 金矿）

  • 自动造用户 case：基于 skill 声明 + 能力自动生成贴近真实场景的 case，不靠人写测试。
  • pass@k 多次采样：同一 case 跑 K 次独立轨迹，用 pass@k 度量稳定性——不是跑一次过就算过。
  • 失败归因到具体环节：意图理解 / 参数抽取 / 调用链路 / 最终回复，哪一环坏了——直接指导改 skill 哪部分。
  • 判通过靠机读信号：看 console 基线日志 / 退出码 / schema，截图仅辅助。「客观可验证信号 > 主观判断」。
  • 错误分类修复表(T1~T9)：每类给「识别特征 / 修复范围 / 动作」+ 判别口诀。
  • 迭代硬上限防死循环：连续 3 轮相同 finding→升级跨文件；累计 5 轮不过→终止挂起。验收目标不可降级(不得跳过任何一项)。
  • 禁止动作清单：禁臆测改、禁吞异常当修好、禁改目录结构。
  • 产 report.md(每次) + DELIVERY.md(全过才出，且必须把内容贴回对话，不能只说”已生成”)。

7.3 现成工具

  • 官方 skill-creator 插件(/plugin install skill-creator@claude-plugins-official，⚠️用前自行核实可用)：自动跑 isolated subagent per case、grade、出 benchmark(with vs without delta)、自动生成 should-trigger/should-not-trigger 测命中率并提议改 description、版本盲测 A/B。
  • 可直接抄的脚手架：skill-creator/scripts/quick_validate.py(102行，SKILL.md lint)、package_skill.py、utils.py:parse_skill_md、references/schemas.md(430行 eval JSON 全 schema)、agents/grader.md。

八、反模式清单（精选 20 条，每条带规避）

#反模式规避
1description 概括了多步 workflow只写 what+when，流程留 body
2description 太泛/太长(>250 关键触发词被弱化、>600 越权)触发词前置，收敛到 150–470 字符
3passive 措辞(“use when”) 触发率崩用 directive(“Use/ALWAYS use this skill when”)
4description 缺触发词/同义词/文件类型穷举用户可能的原话(中英)
5没写 “Do NOT trigger when” → 跟邻近 skill 抢活/误触发加 near-miss 反例段
6SKILL.md body 超 500 行拆 references，带”何时读”指针
7body 是知识堆/科普(“PDF 是一种文件格式…”)或一次性故事(“某次会话我们…”)写成「现在该做哪步」的可走流程
8没跑 baseline 就写 skill(跳 RED)先看不带 skill 怎么失败
9没测就部署 / 批量造一堆不逐个测逐个 baseline 对比测
10discipline 类用软指引(“prefer/consider”)纪律用 Authority 强措辞
11塑形问题用禁令(反噬产出更多坏内容)输出形状错用正面契约/模板
12references 嵌套深(agent 只 head 预览读不全)引用只一层深，从 SKILL.md 直链
13把整段代码贴进 body逻辑做成 scripts/ 黑盒跑
14@ 强制加载烧 200k 上下文靠 description 触发，别 @ 全量挂
15给太多选项/多语言同例稀释按变体拆 references，只读相关那份
16满篇 all-caps MUST/NEVER(黄旗)解释 why，“Do X because Y”
17nuance 条款(“don’t X unless…”)把稳定变噪声要豁免就重构让规则够不着
18overfit(只对几个样例有效)从反馈泛化
19加规则不涨分还硬留(过约束)读 transcript 删让模型瞎忙的指令
20metadata.category 同义异名无受控词表定受控词表，新建必从中选

（社区方法论另有 30 条完整清单）

九、打包 / 分发 / 版本 / 维护 / 废弃

  • 四层级优先级：Enterprise > Personal(~/.claude/skills/) > Project(.claude/skills/ 可 commit 进仓库) > Plugin(命名空间永不冲突)。先 .claude/ 快迭代，要分享转 plugin。
  • Plugin：.claude-plugin/plugin.json 清单；组件目录必须在 plugin 根、不能塞进 .claude-plugin/；--plugin-dir 本地测、/reload-plugins 热加载、claude plugin validate 校验。
  • Marketplace：仓库根 .claude-plugin/marketplace.json；/plugin marketplace add owner/repo → /plugin install x@marketplace；团队用 settings 的 extraKnownMarketplaces+enabledPlugins 强制。
  • 版本字段坑：plugin.json 设了 version 就钉死，不 bump 用户收不到更新；省略(git 源)则每 commit 算新版；别 plugin.json 和 marketplace 两处都设(前者静默胜出)。
  • 可见性/废弃：disable-model-invocation:true(只手动调)、skillOverrides 四态(不动源文件)、permission Skill(name) deny；冲突靠层级优先级+命名空间自动解。
  • 更新现有 skill：保留原名(别加 -v2)，先 cp 到可写位置(/tmp)再改再打包。

十、Hook + Skill 协同范式（软硬护栏，真实项目样本）

skill 是模型自愿遵守、可能不触发/被绕；hook 是 harness 确定性执行。组合用：

软护栏(注入式)硬护栏(拦截式)
真实样本shengtu_sop_guard.pymalformed_toolcall_guard.py
事件UserPromptSubmitStop
时机/动作动手前 / print 一段提醒注入本轮 context(不阻断)收尾后 / {"decision":"block"} 逼干净重发
治什么该用 skill 没用、跳 SOP、“想到才调”的洞产出本身坏了(malformed 调用)

护栏三铁律（永远带）：

  1. fail-open：异常静默放行，绝不因护栏 bug 卡死大脑。
  2. 防死循环：连续命中上限 N 次后放行。
  3. 只读该读的：别误判工具返回、别重写在用日志。

护栏决策：漏了代价小→光 skill 别加 hook；代价大+意图可判→软护栏；代价大+有客观可检坏产出→硬护栏。hook 也能 scope 进 skill 的 hooks: frontmatter 随 skill 分发、只在其活跃时生效。

十一、本机实证画像 + 落地建议

关键数字（130 个已装 skill 定量调查）

  • SKILL.md 行数：min 38 / 中位 124 / 均值 166 / p90 344 / max 661。短≠差(frontend-design 43 行是官方精品 doctrine)。
  • description 字符：min 18 / 中位 212 / p90 471 / max 1017。甜区 150–470。
  • 38 个有 references/(lark-base 惊人 94 个 ref)、19 个有 scripts/。
  • metadata.hermes：51 个带，33 个打 chengzi-grown tag；category 仅 31 个填且取值不规范(integration vs integrations)。

落地建议

  1. 定一张受控 category 词表(九选一：data-extraction / creative / integrations / productivity / judgment / infra / media-generation / devops / web)，新建 skill 必从中选，治 category 混乱。
  2. hermes tags 惯例沿用：[chengzi-grown, <域>, <形态>]，形态词=router/doctrine/orchestrator/pipeline/loop/daemon。
  3. router 模式(douyin-suite/agent-reach/shengtu-router 已验证)是本机处理「子能力重、可独立调用」的标准范式，新建同类直接套。
  4. doctrine 型 skill(knowledge-precipitation/decision-gauge/frontend-design)证明纯判断标准、零脚本零 ref 也是好 skill——别强加代码。

十二、【建任何 Skill 的 SOP 作业卡】（一页可执行）

配套元 skill 已把这张卡做成自动触发的执行流程。这里是速查。

□ 0. 选型：这需求该做成 skill 吗？(对照第〇节决策表；能 regex 卡死→hook；连外部→MCP；会刷屏→subagent)
□ 1. 澄清 4 问：能做什么 / 何时触发 / 输出格式 / 要不要测试用例
□ 2. RED：写 2-3 个真实测试 prompt，不带 skill 跑 baseline，逐字记它怎么失败
       (没看过失败 = 不知道 skill 该教什么 → 不准往下走)
□ 3. 分类失败：纪律违规? 输出形状错? 漏必填? 条件行为? → 决定 skill 形式(Match Form to Failure)
□ 4. GREEN：从 template/SKILL.md 起手，写最小 skill
       · name=kebab-case=目录名；description=what+when(directive,pushy,Do NOT,触发词前置)
       · body≤170行：Overview/Quick Ref/workflow/Pitfalls(❌vs✅)/Reference Files(带何时读)
       · 要跑的→scripts(黑盒) / 要读懂的长知识→references(按变体拆,>300行带TOC) / 要进产物→assets
       · 写作:祈使句+解释why,少all-caps;纪律类才用强措辞
□ 5. 带 skill 重跑测试 → 该过了
□ 6. REFACTOR：agent 还找新借口? 逐字抓→加(禁令+借口表+红旗+desc症状词)→重测到 bulletproof
□ 7. 改进三纪律：泛化别overfit / 加规则不涨分就删 / 跨用例重复脚本固化进scripts/
□ 8. description 触发率优化：20条query(含near-miss负例)→train/test切分→选best
□ 9. 校验：跑 quick_validate(name/desc/字段白名单/无尖括号);复杂skill建生成后校验闭环
□ 10. 验收靠客观信号(日志/退出码/schema)不靠肉眼;迭代有硬上限;不可降级
□ 11. (要分享)转 plugin 打包,plugin.json 管 version,evals/不打进包

十三、参考资源

  • 官方：docs.claude.com Agent Skills(overview / best-practices) · agentskills.io/specification · github.com/anthropics/skills(17 个生产级 skill + skill-creator 源码 + template/SKILL.md + quick_validate.py)
  • 官方工程博客：《Equipping agents for the real world with Agent Skills》
  • 社区方法论：obra/superpowers(TDD 写 skill + writing-skills 元skill) · blog.fsck.com(Jesse Vincent) · simonwillison.net(skill vs MCP)
  • 实测研究：650-trial 触发率研究(directive vs passive 20.6×) · persuasion 七原则(N=28000)
  • 本机最佳对照：~/.claude/skills/（路由型/框架型/doctrine 型等多种范式的本地样例） · 腾讯 wxa-skills-{generate,validate,eval}(生产线 generate/validate/eval)
  • hook 范例：软护栏（UserPromptSubmit 注入提醒）+ 硬护栏（Stop 拦截坏产出）两类项目内脚本