结论先行:Skill 和插件是能力分发的两种形态,选择标准看能力的本质——程序性知识用 Skill(怎么做事的流程与经验,本质是 markdown),代码与配置资产用插件(命令、Agent 定义、hook、MCP server 的打包分发)。两者共享一套渐进加载思想:上下文里只放索引和描述,正文按需加载,把 token 成本压到最低。

Skill:会自我描述的操作手册

一个 Skill 的主体就是一份带元数据的 markdown:

---
name: incident-troubleshoot
description: 线上告警排查流程。当用户提到线上报警、服务超时、错误率上涨时使用。
---

# 排查流程

1. 先看告警对应服务的错误日志,关注最近 10 分钟
2. 确认是否有发版:查发布记录,时间点对齐告警起点
3. 根因假设按"发布 > 依赖抖动 > 容量"顺序排除
4. 输出格式:根因一句话 + 证据(日志行)+ 建议动作

description 是 skill 的"检索入口",要写成触发条件(什么场景用),而不是功能介绍。对比错误写法与正确写法:

<!-- 错误写法:功能介绍式,模型难以判断何时触发 -->
---
name: alarm-tool
description: 一个功能强大的告警分析与日志查询工具集。
---

<!-- 正确写法:触发条件式,术语与团队日常用词一致 -->
---
name: incident-troubleshoot
description: 当用户提到线上报警、服务超时、错误率上涨、发版后异常时使用;
             按发布 > 依赖抖动 > 容量的顺序排查,输出根因+证据+建议动作。
---

错误写法的问题在于"功能强大"这类自夸对模型毫无检索价值——模型做匹配时找的是"当前任务和哪段描述语义重合",描述里出现的是用户会说的话(报警、超时、发版),命中率才高。

渐进加载:为什么百个 Skill 不撑爆上下文

关键机制是渐进加载(progressive disclosure):harness 平时只在上下文里放每个 skill 的 name 和 description(几十 token),模型判断当前任务匹配某个 skill 的 description 时才加载全文。一套几十上百个 skill 的索引开销不过几千 token,正文只有被命中的那一两份进入上下文:

# harness 维护的 skill 索引(示意):常驻上下文的只有这些
skills:
  - name: incident-troubleshoot
    description: 线上告警排查。当提到线上报警、超时、错误率上涨时使用。
    body_path: skills/incident-troubleshoot/SKILL.md   # 命中后才加载
  - name: release-check
    description: 当用户要发版、上线、走发布流程时使用。
    body_path: skills/release-check/SKILL.md
  - name: api-doc-lookup
    description: 当需要查内部接口文档、字段口径时使用。
    body_path: skills/api-doc-lookup/SKILL.md

这套设计让团队可以沉淀几十上百个 skill 而不撑爆上下文——索引常驻,正文招之即来。它和 AGENTS.md 的常驻策略正好互补:每轮都要用的项目约定常驻,偶发场景的流程知识按需加载,两种加载策略配合把 token 预算花在刀刃上。

渐进加载也带来一个新的测试需求:skill 写完了,怎么知道它会被命中?最直接的办法是拿真实的任务话术去试——把团队里同事实际会说的三五种问法喂给 Agent,看对应 skill 是否被加载、加载的是不是预期的那条。命中失败多数是 description 的词不对路:同事说"单号查不到",描述里写的是"订单检索异常",就永远对不上。改名补词的成本是一分钟,但这个测试步骤经常被跳过,结果团队积累的 skill 实际命中率远低于预期,还误以为"skill 没用"。另外注意正文的体积纪律:单条 skill 正文控制在一屏到两屏,超过的内容说明它其实是多件事,拆成几条比堆长文好——加载是整份加载的,长文命中一次的 token 成本就是全份。

插件:能力的安装包

插件是更高一级的分发单元,一个插件可以打包多种资产:

my-plugin/
├── plugin.json            # 元数据与声明
├── commands/               # 自定义命令(slash command)
│   └── deploy.md
├── agents/                 # 子 Agent 定义
│   └── db-auditor.md
├── skills/                 # 内嵌 skill
│   └── release-check/SKILL.md
├── hooks/hooks.json        # 生命周期钩子
└── .mcp.json               # MCP server 配置

它的价值在于把散落的定制点(命令、Agent、hook、MCP)收进一个可版本化、可安装、可分发的包。团队平台的公共能力——部署流程、DB 审计、发布检查——做成插件,新成员一条安装命令就能获得全套团队实践,而不是对着 wiki 手动配一遍。插件还有一层治理含义:资产有明确的版本和边界,升级、回滚、审计都针对包进行,而不是追着散落各处的配置文件跑。

怎么选

判断依据是能力的载体:

场景形态理由
排查流程、代码规范、领域口径Skill纯知识,markdown 足够,改起来零成本
需要确定性拦截的规则插件(hooks)要执行代码,不是模型能"记住"的事
连接外部系统插件(MCP)需要独立进程和协议
团队标准化工具集插件(整体打包)一次分发多个资产
个人偏好与常用口径Skill(全局层)不进仓库,随人走
需要版本化与审计的资产插件(仓库管理)升级回滚以包为单位

一个常见的演进路径:团队先写 skill 沉淀流程知识(快、门槛低),某条 skill 里反复出现"还要人工跑某个脚本、还要记住某个禁改清单"的部分,就是它该升级成插件(挂 hook、配 MCP)的信号。知识先于工具,验证过的知识才值得固化为代码。

一个要避开的反方向:往 skill 里塞代码。有人把几十行 shell 脚本直接贴进 SKILL.md 让模型"照着执行",这是形态误用——脚本该跑得准,靠模型逐行复述脚本总有走样的概率,正确去处是包成 MCP 工具或自定义命令,让代码以确定性方式执行,skill 里只留"什么时候用这个工具"的说明。判断口诀还是那句:知识(怎么说)进 skill,行为(怎么跑)进插件。

推广中的两个细节

一是命名与发现:skill 名和 description 里用团队真实术语(单号、渠道、对账),模型的触发匹配靠的就是这些词,写得太抽象就永远不会被命中。二是沉淀节奏:别追求一次写全,谁排查完一次线上问题、谁理清一个业务口径,就当场补一条 skill,碎片化的积累比集中编写更贴近真实用法,过时得也更慢。

最后一个提醒:无论 skill 还是插件,维护责任要落到人。没有 owner 的 skill 会和代码库脱节,过时的操作手册比没有更糟——模型会忠实地执行过时流程。

实战场景

一个运维团队的沉淀过程很有代表性:某次线上事故复盘后,当事人把排查步骤写成第一条 skill(四十行 markdown),description 里老老实实写上了团队口头语"某某服务超时"“错误率抬升”。此后一个月里,每次有人对 Agent 说"线上又超时了",这条 skill 都能被正确加载,排查输出逐渐稳定成"根因+证据+建议"三段式,值班同学省掉了每次口头交代流程的功夫。随后他们注意到 skill 里反复出现两件事:每次都要人肉跑一遍同一个日志归集脚本、每次都要提醒"不要动 发布锁文件"。这两处就是升级信号——脚本包成 MCP 工具,禁改清单挂上 PreToolUse hook,连同原本的 skill 一起打包成插件发到团队仓库。新来的同事装一个插件,就等于继承了半年的值班经验(以上为过程描述,非量化评测)。半年后清点:十几条 skill、两个插件,每条都有 owner 和最近一次被命中的日期,过时的直接删除而不是留着当"资料"。

检查清单

  • description 写触发条件,用团队真实术语,不写"功能强大"式自夸
  • 索引常驻、正文按需加载,确认 skill 数量增长不推高常驻 token
  • 纯知识用 skill,确定性拦截与外部系统用插件,不混用
  • skill 里反复出现的"人肉步骤"和"人工提醒"标记为插件升级信号
  • 团队公共能力打包成插件,走仓库版本化,可安装可回滚
  • 每条 skill 有 owner,定期清理过时条目
  • 沉淀节奏跟随真实使用,事后当场补条,不搞集中编写的"大而全"