子项索引

子项	一句话
description-format leaf	skill 的 description 字段必须是两句结构 — 第一句讲是什么，第二句以"Use when"开头列具体触发场景
body-length-budget leaf	skill 正文（H1 之后到文末）必须 ≤100 行，超出部分拆到同目录 reference.md / examples.md
progressive-disclosure leaf	skill 内容分主入口 + 二级引用文件 — 主入口给规则与自检，二级文件给详细 API / 代码示例 / 反模式集
trigger-phrasing leaf	triggers.keywords 写法 — 中英双语 + 同义词 + 名词短语，与 description 的 Use when 职责分离
naming-and-retrieval leaf	skill 文件/文件夹命名规范 + 检索友好规则 — 路径每段都是检索 keyword，命名直接决定召回

子项

一句话

description-format leaf

skill 的 description 字段必须是两句结构 — 第一句讲是什么，第二句以"Use when"开头列具体触发场景

body-length-budget leaf

skill 正文（H1 之后到文末）必须 ≤100 行，超出部分拆到同目录 reference.md / examples.md

progressive-disclosure leaf

skill 内容分主入口 + 二级引用文件 — 主入口给规则与自检，二级文件给详细 API / 代码示例 / 反模式集

trigger-phrasing leaf

triggers.keywords 写法 — 中英双语 + 同义词 + 名词短语，与 description 的 Use when 职责分离

naming-and-retrieval leaf

skill 文件/文件夹命名规范 + 检索友好规则 — 路径每段都是检索 keyword，命名直接决定召回

Skill Authoring · 写 skill 的规约

灵感来自 Matt Pocock 的 skills repo，结合本仓 MCP 检索语义化做的本地化。

核心理念

skill 是给 agent 看的，不是给人看的。所有规约都围绕一个问题：

agent 看到这条 skill 时，能否 (1) 立刻判断要不要加载它，(2) 加载后知道该做什么？

📐 本层是 HOW（操作规约）。背后的 WHY（harness 思想纲领：4 条核心信条 + 业界锚点）在 /.claude/skills-philosophy.md —— 写 skill 前先读那篇理解「为什么」，再回这里取「怎么做」。

名称	类型	一句话
description-format	叶子	description 字段两句结构：是什么 + Use when
body-length-budget	叶子	正文 ≤100 行硬边界，超出拆引用
progressive-disclosure	叶子	渐进披露 — SKILL.md 主入口 + 外链深内容
trigger-phrasing	叶子	triggers.keywords 必须含中英双语 + 用户原话
naming-and-retrieval	叶子	文件/文件夹命名规范；路径每段即检索词，命名决定召回