# 拆agent-skills：六万星的八道闸 ## 概述 本期继续本栏的定期深拆系列。对象不是本周新星，而是货架上被引用最多、却始终没被逐文件拆过的常青件——`addyosmani/agent-skills`。它由 Google Chrome 团队的 Addy Osmani 维护，6 月创下单周涨超 1.1 万星的纪录，6 月底星数约 6.1 万，是 Skills 生态里体量最大的工程方法论库。本期拆三层：它的双形态户型（8 个斜杠命令 + 一批自动触发技能）、两枚代表件的设计精读，以及从中提炼的五个可直接照抄的 SKILL.md 写法。文末附五维评测、安装命令与分场景排名。 ## 一、门牌：被引用最多、却从没被拆过的那件 先对门牌。`github.com/addyosmani.com/agent-skills` 之外的正主是 `addyosmani/agent-skills`，MIT 协议，作者 Addy Osmani——Chrome 团队的工程负责人，写过《Learning JavaScript Design Patterns》的那位。技能类仓库里，作者身份直接决定内容的成色：这件的卖点从头到尾就一句话，**把一个资深工程师的工作纪律，编码成 Agent 可执行的指令**。 它的星标史分两段。5 月的「八大发行商」盘点里，它还是梯队里的一行：19 个生产级 Skills、综合 4.6 分的头部件；6 月 9 日到 17 日那一周突然放量，单周涨超 1.1 万星，是当周技能类仓库里跑得最快的一件；到 6 月底，本站记到约 6.1 万星。之后它就从所有公开榜上消失了——不是凉了，是量具装不下：新星榜只收 7 天内新建的仓库，小而美榜上限 2000 星，热榜要求近 3 天活跃且门槛远高于这个体量。6 万星的老件属于本栏 9 月对账文说过的「死于量程」。所以本文星数口径停在 6 月底，10 月的实时数公开渠道查不到，不做推测。 顺带一个生态脚注：官方插件市场的保留名清单里，「agent-skills」这个名字已被列为禁用词。一个仓库名通用化到平台要把它设为保留词，这本身就是它生态位的注脚——它不再是某件商品，已经成了品类名词。 而对照本周货架：新上榜的全是单点工具——做模型路由的、做游戏改机的、做语义找码的，单件锐利但各管一段。全流程编制型的工程方法论库，今天的货架上反而没有同位竞品。这是它值得重拆的第二个理由。 ## 二、户型图：命令层与知识层的双形态 大多数 Skill 只有一层：一份 SKILL.md，把 description 写好，等模型在对话里撞上触发词。agent-skills 的特别之处是两层结构： | 层 | 形态 | 成员 | 调用方式 | 管什么 | |---|---|---|---|---| | 命令层 | 8 个斜杠命令 | /spec /plan /build /test /review /webperf /code-simplify /ship | 人显式敲出 | 流程走到哪了 | | 知识层 | 自动触发 Skills | performance-optimization、documentation-and-adrs 等（5 月底口径 19 件） | 模型按 description 自行匹配 | 这一步该懂什么 | 8 个命令对应一条「定义→规划→构建→验证→审查→上线」的六阶段流水线：/spec、/plan、/build、/test、/review、/ship 是六道主闸，/webperf 和 /code-simplify 是两道支线闸，分别挂在验证和审查阶段： ```mermaid flowchart TD A["/spec 定义"] --> B["/plan 规划"] B --> C["/build 构建"] C --> D["/test 验证"] D --> E["/review 审查"] E --> F["/ship 上线"] G["/webperf 支线"] --> D H["/code-simplify 支线"] --> E ``` 这个结构的教学价值在于：**把一条长流程拆成可独立调用的闸门，而不是一条几千字的巨型提示词**。每道闸是独立的交付物，你可以只用 /spec 和 /review 两端，把中间步骤留给团队自己的习惯；也可以整条跑，让 Agent 按质量门禁推进。反例是很多新手写的 Skill——把「写码规范+测试要求+上线清单」全塞进一份 SKILL.md，结果模型在不需要规范的场景也背着全副装备，触发率和执行质量一起塌。 ## 三、精读一：performance-optimization，先讲为什么再讲怎么做 知识层的代表作，5 月底口径 3.8K 安装。它把 Google 的 Web 性能优化哲学——Core Web Vitals、渲染管线优化、资源加载策略——系统化为 Agent 可执行的工程指令。本栏 5 月的实测记录里，有三个设计细节值得逐条看： **第一，每个优化建议前都附带性能影响分析和权衡说明。** 这是对抗「为优化而优化」的提示词设计。模型最常见的失败模式是拿着锤子找钉子：学了缓存就到处加缓存，学了 memoization 就全量 memo。让模型在给方案前先写清「这条建议的代价是什么、什么场景下不该用」，等于把 code review 的第一问内置进了生成流程——建议的质量不靠模型品味，靠格式强制。 **第二，建议必须映射到具体指标。** 它对 Core Web Vitals 的集成能做到把优化目标自动映射到 LCP/FID/CLS 的改善。这等于给每条建议配了验收标准：没有指标锚定的优化建议只是抒情，有指标的才是工单。 **第三，知识层触发，不占命令位。** 它不要求你记得敲命令，写码过程中模型按 description 自行匹配触发。流程纪律归命令层，专业判断归知识层，两层不打架——这是它和大量「一个文件管所有」的技能包最本质的差别。 ## 四、精读二：documentation-and-adrs，把决策记成资产 第二枚代表件，5 月底口径 3.9K 安装，安装量甚至压过 performance-optimization 一头——「文档」比「性能」跑得好，这个排序本身就值得琢磨：团队对「让 AI 边干活边留档」的需求，比「让 AI 优化性能」更普适。 它做的事是把架构决策记录（ADR）实践融进文档生成流程：动架构时，同步产出「背景—选项—决定—后果」式的记录。大多数团队的 ADR 制度不是不知道好，是死在「没人写」；把它挂进 Agent 的生成流程，写决策记录就从额外工序变成写码的副产品。这是本栏反复见过的一个模式的又一例证：**把团队纪律编码成工具的默认行为，比写在 wiki 里等人执行有效得多。** ## 五、可抄的五个设计模式 给想自己写 Skill 的读者，从这件里能直接搬走的写法： **1. 双形态分离：流程做成命令，知识做成触发件。** 你的 SKILL.md 如果既能拆出「用户会主动要的步骤」，又能拆出「模型该随时懂的知识」，就写成两个文件——命令层用 name 挂流程节点，知识层把 description 写足触发场景。判据很简单：这件事是人记得要，还是模型该想到？ **2. why-before-how：建议前强制权衡说明。** 在你的指令里显式要求「每条建议先写代价与不适用场景，再写做法」。一句话的格式约束，换来建议质量的系统提升，是所有写法里性价比最高的一条。 **3. 指标锚定：每条建议配验收口径。** 性能件映射 Core Web Vitals，你的件也应该找到自己的「LCP」——测试覆盖率、包体积、错误率，什么都行，但没有验收指标的建议是抒情。 **4. 阶段闸门化：拆闸不拆链。** 长流程拆成可独立调用的多份 SKILL.md，每份聚焦一个阶段，同时保持阶段间的产出物衔接（/spec 的产出是 /plan 的输入）。用户可以整链跑，也可以单闸用。 **5. 一稿多引擎。** 这件从 6 月起就支持 Claude Code 之外的 Cursor、Gemini CLI、Windsurf、Antigravity——一份 SKILL.md 多处分发。本栏今日盘点刚记过另一件一天涨 177 星、门牌直接写明服务三家引擎的 Logo 件：跨平台兼容正在从个人写法变成品类共识，新写 Skill 值得第一天就把引擎方言的兼容性考虑进去。 ## 六、短板：它管不了什么 7 月本栏的对比判词今天仍然成立：覆盖更广，但方法论耦合度低。对照 superpowers 那类「审讯前置」的强流程件——后者会在开工前逼你和 Agent 对齐需求、答完问题才放行——agent-skills 的闸门更像检查站而非审讯室：你可以在任何一道闸直接说「跳过」。这对熟手是自由，对新队伍是漏洞：流程件没有强制力时，它退化为一份写得很好的建议书。 第二条：它是方法论库，不是监控器。性能建议给出后有没有被验证，要靠你自己跑基准测试闭环，反馈回路不在件内。想要「改完自动对比性能曲线」的，得另外配工具。 第三条：知识层吃使用者的工程判断力。权衡说明写在那里，没有性能工程背景的团队未必判得动——这件是给「已经知道该问什么问题」的人做放大器的，不是扫盲教材。 ## 七、安装与使用 三条路线，按需取用： ```bash # 路线一：Claude Code 插件市场，整套安装 /plugin install agent-skills@addy-agent-skills # 路线二：Skills CLI，按件取用 npx skills add addyosmani/agent-skills@performance-optimization npx skills add addyosmani/agent-skills@documentation-and-adrs # 路线三：Cursor / Gemini CLI / Windsurf / Antigravity # 按各引擎的技能目录约定导入同一仓库 ``` 建议的上手次序：先单独装 documentation-and-adrs 跑一周（低风险、正反馈快），再上 /spec 和 /review 两端闸，最后决定要不要整链编制。 ## 八、评测对比与排名 本栏口径初评（依据仓库自述与本站实测记录；实战效果一列为社区信号佐证而非逐项复测；上手难度分数越高越省事）。权重：功能 25%、设计 25%、实战 20%、上手 15%、社区 15%。 | 件 | 功能完整度 | 设计质量 | 实战效果 | 上手难度 | 社区活跃度 | 综合 | |---|---|---|---|---|---|---| | anthropics/skills（官方货架） | ★★★★ | ★★★★ | ★★★★★ | ★★★★★ | ★★★★★ | 4.50 | | addyosmani/agent-skills | ★★★★★ | ★★★★ | ★★★★ | ★★★★ | ★★★★★ | 4.40 | | obra/superpowers | ★★★★ | ★★★★★ | ★★★★ | ★★★ | ★★★★★ | 4.25 | 分场景排名： - **想学 SKILL.md 写法**：agent-skills 第一——双形态结构与 why-before-how 是全货架可抄性最强的两课； - **想给团队立流程规矩**：superpowers 第一——审讯前置的强制力是它独有的； - **零基础先跑通**：官方货架第一——开箱即用，无需工程判断力前置； - **一份稿件喂多家引擎**：agent-skills 与新一代跨平台件并列——前者验证了模式，新件在补足单点深度。 ## 参考来源 1. [addyosmani/agent-skills](https://github.com/addyosmani/agent-skills) — 主仓库：双形态结构、8 命令清单、安装命令与跨平台支持口径 2. [anthropics/skills](https://github.com/anthropics/skills) — 官方货架仓库，对照口径 3. [obra/superpowers](https://github.com/obra/superpowers) — 强流程件对照 4. [Skill authoring best practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices) — 官方写作口径：描述第三人称、渐进披露 5. [Agent Skills 开放标准](https://agentskills.io) — 跨工具复用规范，一稿多引擎的标准层背景 > [!tip] 51学通信知识星球 > **星主：爱卫生**（微信：gprshome201101）——公众号「51学通信」创办者，19 年通信行业运维与讲师经验，著有《GPRS网络信令实例详解》《EPC原理与实践》《5G核心网原理与实践》三本纸质书（各大电商平台有售）。 > **星球定位**：深耕 5G 核心网、IMS、NFV/AI、云原生等 ICT 领域，主打运维岗位与信令分析。 > **当前规模**：5200 篇主题 / 990 个回答，198 元/年。 > **加入福利**：加入星球后请加爱卫生微信，拉您进知识星球年度陪伴与答疑群——不限量回复您的各种问题，另有群内分享。 > **AI 加持**：51学通信知识星球已作为 skill 接入 WorkBuddy，使用 deepseek-4-flash 在海量星球帖子中精准找贴、找视频、找 FAQ 和案例，做总结、找文档和 PPT 等场景全覆盖。