我一直把“Skill”当成小型产品来运营，有定位、有交付、有版本控制。

直到我第一次照着 anthropics/skills 的官方流程做包，打包脚本当场把我“教育”了一遍：描述不达标直接拒绝、脚本没权限照样过不了、冗长的主体让上下文膨胀到不可维护。

这不是给模型加插件，而是用三层架构把“触发、执行、扩展”做成一个可治理的产品。

Skill不是一个文件，而是一个可运营的产品

anthropics/skills 里最值得琢磨的是 Progressive Disclosure（渐进式展示）。

这不是一个术语的堆砌，而是一个资源治理策略：不要一次把所有信息塞进上下文，而是分三层按需加载。

• Metadata（元数据）：name + description，常驻上下文的有限信号，类似“产品定位 + 使用承诺”。只有约100词，却决定是否触发。
• SKILL.md（技能主体）：被触发后加载的工作流程和指令，建议小于5000词，最好控制在500行以内。像产品的主流程和操作手册。
• Bundled resources（捆绑资源）：scripts、references、assets，运行时按需引用。把确定性动作、冗长文档、输出模板放到这里，避免上下文膨胀。

换个产品语言来讲：元数据是“获客与路由”，主体是“核心体验”，资源是“能力与资产”。这一层层拆分的目的很朴素——上下文窗口是公共资源，谁浪费，谁拖累全局效率。

为什么description是生死线：它是路由信号，不是文案

触发失败的体验很像“用户明明点了按钮，却没进入流程”。描述写不清，技能就不会被选中。官方没有把门槛写得很重，但实际打包验证非常严格：字数太少会被拒、触发条件含糊会被误路由。

我用产品方法论做了一个更稳的写法：

• 给功能、场景、触发条件做“意图分类”。例如：PDF编辑、格式转换、文本提取三类，并分别写出用户常见表达。
• 用编号列场景，加入负向边界（不做什么），降低误触发的概率。像是在PRD里明确 Out of Scope。
• 控制在50-200词，中间用动词+场景短语，不要讲故事。描述不是广告语，它是模型的路由规则。

我会做一个“触发准确度”小测：准备30条真实用户话术，计算正确触发率和误触发率；一旦准确度低于90%，回到描述改意图词汇和边界说明。这个方法朴素，但比拍脑袋强太多。

主体写得越短越好，但必须有决策结构

把SKILL.md当操作型SOP写，目的不是把知识塞满，而是让模型能按步骤做事。最实用的结构是“总览 + 决策树 + 指令集”。

• 总览：一句话说明能力范围，指向关键章节。
• 决策树：用条件分支组织选择路径（例如“有表单-走填充；有OCR-走识别；需要批处理-走脚本”）。
• 指令集：用命令式动词给出动作（Rotate, Extract, Convert），避免长篇解释。

超过这个密度的说明，移到 references；需要高确定性的步骤，做成 scripts；输出需要样式和模板，放 assets。你会发现：一旦把决策结构搭好，主体自然会短下来，且更稳定。

资源三件套：脚本要可执行、参考要可检索、素材要可复用

我把资源的治理拆成三件事：

• scripts：确定性、可测试。给文件加执行权限，在两个操作系统上跑一遍边界用例（空文件、大文件、异常格式）。为关键脚本维护一个兼容性矩阵，降低“环境变化”导致的故障率。
• references：只放必要文档，超过100行拆分主题，超过1万词在主体里写明 grep 搜索模式，减少无意义扫描。避免与SKILL.md重复；两处都有的内容，必定会造成上下文浪费。
• assets：让模型用文件，而不是把文件读进上下文。例如logo、PPT模板、前端样板，都应该在输出阶段引用。

这里还有一个安全提醒：不要把用户文档、开发者安装说明、变更日志塞到技能包里。它们对模型没用，只会制造噪音。

六步落地法：把研发流程搬进技能制作

我把官方的六步改造成可执行的团队流程，附上时间预算，供你规划排期。

1. 理解技能（30-60分钟）：明确三到五个核心场景，写出典型用户话术，划清边界。像做PRD的“问题与范围”。
2. 规划内容（30-60分钟）：列出需要的脚本、参考、素材，写明输入输出、体量与测试方式。把“想放的”变成“必须放的”。
3. 初始化（5分钟）：用 init_skill.py 生成目录结构，减少手工错误。
4. 编辑与验证（2-4小时）：写 description、搭主体决策树、补资源并测试。删除示例残留文件。做一次“触发准确度”与“脚本边界”双测试。
5. 打包与门禁（5-10分钟）：用 package_skill.py 打包，校验frontmatter、命名、结构、权限、引用一致性。打不过门禁就不要发布，严一点是负责。
6. 迭代与度量（持续）：收集使用反馈，记录误触发与低效片段，更新描述与资源。给版本号（SemVer），做灰度发布与回滚预案。

这套流程适合团队共享的专业技能、会长期使用的生产力工具、需要高Token效率的复杂场景。临时项目就别那么重，轻量做原型更划算。

常见坑与“产品化”补救

• 描述太模糊：打包失败或触发不稳。补救：按意图分类重写，加入负向边界，做离线触发准确度测。
• 脚本未测试：上线才爆雷。补救：基本测试、输出验证、边界测试一个都别少；必要时抓异常并打印可诊断的错误信息。
• 参考过长：上下文膨胀、性能下滑。补救：拆分主题、加检索模式、只在需要时加载。
• 权限与环境：打包成功、执行失败。补救：跨平台验证权限位、依赖与路径，建立最小运行环境说明（不进包，但放在仓库 README）。
• 版本与漂移：技能随时间飘。补救：语义化版本、变更记录、灰度渠道、回滚策略；把“触发词库”当能力资产去维护。

Token优化：把上下文当公共预算来管理

Claude的上下文窗口不是你一个技能独占，system prompt、对话历史、其他技能元数据、用户请求都要分预算。优化的要义在于三点：

• 只提供模型没有的东西。看到一段解释，问自己：这句值得它的token成本吗？
• 匹配自由度：脆弱操作用低自由度（具体脚本），稳定操作用中自由度（伪代码+参数），创意任务用高自由度（文本指令）。
• 示例胜过长文：短小、可执行、能被复用的模式，比冗长概念更值钱。

官方文档与现实差距：把隐性规则显性化

我确实遇到过一些“写得云淡风轻，用起来坑不少”的地方：描述字数阈值、脚本权限、主体长度上限的真实影响。这其实是典型的文档债——规范散落在代码门禁里，而非文字说明。我的做法是拉一张“预检清单”，每次发布都跑一遍：

• Frontmatter：name小写连字符、description覆盖功能与场景，50-200词。
• 结构与引用：SKILL.md在根目录、资源目录命名正确、所有引用存在且可读。
• 权限与执行：scripts可执行、关键脚本跨平台测试通过。
• 冗余治理：无README等面向人的文件在包内，references无重复。
• 主体密度：不超过5000词，决策结构清晰，命令式动词为主。

关于“5000词限制”的理解：约束是为了稳定的可读性

作为产品经理，我更关注整体系统的可信度与维护成本。限制主体长度并不是为了“节省一点点token”，而是强制创作者做层次化结构：核心工作流程留在中心，细节分散到可检索资源。长文容易把模型拖进“无意义的解释”，短文逼迫我们把决策和指令提纯。我个人偏好把主体控制在800-1200词，复杂技能用决策树+引用导航来扩展。

两段模板，拿去即用

Metadata写法

name: pdf-editor
description: 面向PDF的编辑、格式转换与文本提取技能。当需要处理以下场景时触发：
(1) 旋转或合并页面；(2) 将PDF转为Word/图片；(3) 提取文本并按段落/表格导出。
不处理加密解除与版权规避请求。

打包前预检清单

• 描述覆盖功能+场景+边界，长度合规；主体命令式、结构清晰；无重复信息。
• 脚本跨平台执行、权限正确、边界样例通过；引用文件存在且体量合适。
• assets目录独立，输出路径明确；无面向人的额外文档。
• package脚本通过门禁；版本号与变更记录已更新（在仓库，不进包）。

结尾：把技能当产品，才会越做越稳

我更愿意用一个简单公式来收尾：高质量Skill = 精准的description路由 + 紧凑的主体决策 + 可执行的脚本 + 可检索的参考 × 持续迭代。把这件事当产品来做，流程和度量就会自然长出来：门禁、触发准确度、脚本可靠性、上下文成本……这些“看起来啰嗦”的规矩，恰恰是让团队共享与长期维护变得可靠的基础。

如果你准备把技能用在生产环境或团队场景，值得投入那4-8小时，把骨架搭好、测试补齐、度量上线。约束不是为了束缚，而是为了让能力稳定地生长。你也可以分享你对“5000词上限”的看法——你习惯控制在多少词？哪种结构最稳？我很想看到不同团队的实践，用真实数据把这套方法打磨得更好。