长 system prompt 可以告诉模型怎样工作，但所有规则每轮都要进入上下文，脚本、模板和参考材料也只能另找地方存放。skills/ 与仓库根目录的 .claude/ 展示了另一种组织方式：模型先看一份能力目录，确认任务相关后再读取说明和文件；项目则用 command、agent 和 hook 决定这份能力从哪里进入工作流。

这套设计的意义不在于把 prompt 拆成更多 Markdown，而在于给工作方法安排加载时机、执行形式和作用范围。

Skill 的入口是描述，不是正文

Skills 使用三级加载：模型平时只看到 name 和 description；判断相关后读取 SKILL.md 与同目录的 Markdown；执行时再使用脚本、模板和其他资源。

始终可见：name + description
命中任务：SKILL.md、REFERENCE.md
执行需要：脚本、模板、数据文件

因此 description 并非普通简介。它承担路由：写得过宽，无关任务也会加载；写得过窄，模型根本不会发现这项能力。SKILL.md 再详细，也补救不了入口没有召回它。

这与 Tool Search 的思路接近，区别是检索单位更大。Tool Search 按需暴露一个工具的 schema；Skill 按需暴露一套工作方法，其中可以包含说明、程序和素材。前者回答“可以调用哪个函数”，后者回答“这类任务应按什么方法完成”。

渐进加载节省的是未使用能力的上下文，不是让已使用的 Skill 免费。notebook 也明确指出，一旦命中，完整说明仍会进入上下文。把大量互不相关的内容塞进同一个 Skill，会同时破坏路由精度和加载成本；按任务边界拆分比做一个“万能 Skill”更合理。

脚本决定 Skill 是知识还是能力

三个 custom skill 样例把不同内容装进相同目录结构：

• 财报分析 Skill 描述指标口径，脚本负责计算比率；
• 品牌规范 Skill保存颜色、字体和文案要求，脚本负责应用与检查；
• 财务建模 Skill描述 DCF、敏感性分析和情景规划，脚本执行数值计算。

如果只有说明而没有附带脚本，模型仍需临时写公式、解析文件并实现检查。附带脚本后，模型可以选择输入和解释结果，把重复计算交给确定性程序。Skill 把两类工作放到一起：语言负责判断任务和组织流程，代码负责可重复的计算与验证。

但“附带脚本”不等于“结果可靠”。样例本身就暴露了边界。财务比率脚本遇到除数为零时返回 0，这会把“无法计算”伪装成真实数值；品牌检查脚本在文本里搜索颜色和字体字符串，不能证明一个 PPT 或 Excel 的实际渲染符合规范；财务建模说明声称支持 Monte Carlo 和多类模型，目录中的实现却主要覆盖 DCF 与敏感性分析。Skill 的说明、代码和真实能力可能漂移。

因此，Skill 的验收对象不应只是 SKILL.md 是否写清楚，还包括：入口描述能否正确召回、脚本是否处理异常、声明的能力是否有实现、产物是否经过独立验证。Skill 打包的是能力，也会把错误一起打包并反复复用。

.claude/ 把能力接入项目工作流

仓库根目录的 .claude/ 比 Skills 教程更接近实际工程。它同时包含：

commands/   用户主动触发的工作流入口（ 相当于 user-invoked skills，有认知负载，没有模型的context负载）
agents/     可委派角色及其工具范围
skills/     按任务加载的规则、脚本和参考资料

三者分工不同。以 notebook 审查为例：command 限定只检查用户指定的文件，并规定最后如何汇报；cookbook-audit Skill 提供审查步骤、评分维度和风格规范；code-reviewer Agent 拥有自己的角色说明与工具集，可以承接具体审查任务。

command：这次从哪里开始、允许做什么
skill：这类工作按什么标准完成
agent：由哪个独立上下文和工具集合来做

这比把所有内容写进一个 prompt 更容易维护。模型审查 notebook 时不必同时加载链接检查、模型版本检查和 PR 发布流程；用户调用对应 command 后，项目再加载需要的能力。

仓库中的 command 还承担权限收缩。model-check 只允许若干 GitHub 命令，notebook-review 额外允许 Read、Glob、Grep 和 WebFetch；review-pr 可以调用 code-reviewer，但发布 review 前要求询问用户。工作流说明和允许调用的工具放在同一个入口，避免模型仅凭文字承诺“我不会做其他操作”。

确定性检查和模型审查需要同时存在

cookbook-audit Skill 没有让模型直接通读 notebook 后打分。它先运行 validate_notebook.py，检查密钥、模型名、安装输出、开头结尾和代码单元排列，再把 notebook 转成不含输出的 Markdown，最后由模型按 style guide 做人工式审查。

这套顺序值得保留：

脚本检查可判定问题
→ 转换成适合阅读的材料
→ 模型判断叙事、技术解释和教学质量

密钥格式、过期模型名和文件结构可以用代码稳定检查；叙事是否清楚、示例是否合适不能靠几个正则决定。全交给模型会让硬错误的判断不稳定，全交给脚本又只能得到表面合规。

不过这些规则也会老化。模型允许列表直接写在验证脚本中，command、Skill 和 Agent 又各自重复部分规范；三处更新不同步时，同一个仓库可能同时给出冲突建议。把方法做成工程配置之后，维护对象从一份 prompt 变成一组会演化的依赖，版本和测试也随之成为必要条件。

Skill 适合封装已经稳定的方法

Skill 最适合反复出现、输入输出相对明确、已有脚本或模板可复用的任务。尚未稳定的方法若过早打包，会把临时判断固化成默认流程；用户看到一个专业名称，也容易高估内部实现。

一个可维护的 Skill 至少需要四层证据：description 能把正确任务引进来，说明与代码一致，脚本有独立测试，最终产物有外部验证。.claude/ 再把它放入具体 command、agent 和权限边界中。这样，工作方法无需常驻 prompt，也不再只是模型“记得遵守”的一段文字。