Agent Skill Management：把 AI 助手从聪明变成稳定

为什么需要 Skill

用 coding agent 一段时间后，我发现真正影响效率的不是“模型今天够不够聪明”，而是它能不能稳定地复用经验。

比如同一个仓库里，测试命令是什么、哪些文件不能随便改、生成图片应该放在哪个目录、发布前要跑什么检查、遇到 bug 应该先定位根因还是先补丁。人可以靠记忆和习惯处理这些隐性流程，但 agent 每次启动时并不天然知道这些约定。把所有规则都塞进一份巨大的 AGENTS.md 也不是好办法：上下文会膨胀，触发边界会模糊，最后变成“什么都写了，但关键时刻不一定用”。

skill 的价值就在这里：它把一类任务的工作流打包成一个可复用、可触发、可演化的小模块。好的 skill 不只是 prompt 模板，而是带边界的操作手册：什么时候用、什么时候不用、需要读哪些资料、可以运行哪些脚本、完成前如何验证。

这篇文章讨论的不是某个单独 skill 怎么写，而是 agent skill management：如何增加 skill、删除或禁用 skill、用工具管理 skill、推荐先装哪些元 skill，以及 skill 如何在真实使用中进化。

Skill 的最小模型

在 Codex 的语境里，一个 skill 本质上是一个目录，里面至少有一个 SKILL.md。这个文件通常包含两层信息：

• metadata：name 和 description，用来告诉 agent 这个 skill 是什么、什么时候应该触发；
• instructions：真正的工作流说明，告诉 agent 触发后应该怎么做。

目录里还可以放辅助材料：

• scripts/：确定性脚本，比如格式转换、校验、生成文件；
• references/：长文档、规范、示例，避免把所有内容都塞进主说明；
• assets/：模板、图片、配置片段、脚手架资源。

最重要的机制是 progressive disclosure。agent 启动时不应该一次性读完所有 skill 的全部内容，而是先看到 skill 的名称、描述和路径；只有当任务匹配某个 skill 时，才加载完整的 SKILL.md。这和程序里的 lazy loading 很像：常驻的是索引，按需加载的是实现。

flowchart TD
    user["用户请求<br/>例如：帮我写一篇博客"]
    index["Skill 索引<br/>name + description + path"]
    match{"是否匹配<br/>某个 skill？"}
    load["加载 SKILL.md<br/>读取完整流程"]
    resources["按需读取<br/>scripts / references / assets"]
    act["执行任务<br/>编辑文件 / 调工具 / 验证结果"]
    done["输出结果<br/>说明改动与验证"]

    user --> index --> match
    match -- "否" --> act
    match -- "是" --> load --> resources --> act --> done

这个模型决定了 skill 管理的第一条原则：description 是入口，不是简介。它不是给人看的营销文案，而是给 agent 做触发判断的路由规则。description 写得太宽，会导致误触发；写得太窄，agent 又想不起来用。

一个好的 description 应该回答三个问题：

• 这个 skill 解决哪类任务？
• 用户通常会怎么表达这类任务？
• 哪些相邻任务不应该触发它？

比如“写博客”类 skill 的描述应该明确触发词包括 write a post、create a blog entry、draft an article，同时说明它适用于某个具体 Hugo 博客结构，而不是所有 Markdown 写作。

Skill 的生命周期

skill 管理不是一次性的安装动作，而是一套生命周期：从可信来源添加，放到合适作用域，持续更新，最后在不再有用时禁用或删除。

更好的类比是依赖管理：谨慎安装，按作用域隔离，更新前 review，定期清理。

谨慎增加 Skill

增加 skill 有三种常见路径：从已有生态安装、从仓库挑选、自己创建。

从官方或社区安装

如果只是想给本地环境增加一个常用能力，优先用安装工具，而不是手动复制文件。我的默认建议是：日常用 skills CLI 管理，Codex-only 的官方 curated skill 再用 $skill-installer。

vercel-labs/skills 这种 CLI 更像“包管理器”。它支持 GitHub shorthand、完整 URL、GitLab、任意 git URL、本地路径，也能指定安装到哪个 agent。对于同时使用 Codex、Claude Code、Cursor、Gemini CLI 等多个 agent 的人来说，用它统一安装、列表、更新、删除，会比在每个 agent 里各管一套更清楚：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

# 列出仓库里的 skill
npx skills add vercel-labs/agent-skills --list

# 只安装指定 skill
npx skills add vercel-labs/agent-skills \
  --skill frontend-design \
  --skill skill-creator

# 安装到特定 agent
npx skills add vercel-labs/agent-skills \
  --agent codex \
  --agent claude-code

Codex 的 $skill-installer 更适合当作原生兜底入口：当官方文档或 Codex UI 直接告诉你安装某个 curated skill，或者你只想在当前 Codex 会话里临时试一个 Codex-only skill，可以直接用它：

1

$skill-installer linear

所以两者不是互斥关系：skills CLI 负责日常 inventory 和跨 agent 管理，$skill-installer 负责 Codex 原生 curated 入口。长期分发时，plugin 通常又比散落的 skill 文件更可控，因为 plugin 可以把多个 skill、MCP 配置、app integration 和展示元数据打包在一起。

这里需要注意一个现实问题：skill 生态还很新，仓库质量差异很大。不要看到 “1000+ skills” 就全装。skill 不是 VS Code extension，装多了会增加触发噪声，也会挤占初始 skill 列表预算。更好的做法是：先列出候选，再按任务频率和来源可信度安装。

从网上找 Skill

找 skill 可以从几个入口开始：

• 官方 catalog：例如 openai/skills；
• 跨 agent 工具仓库：例如 vercel-labs/skills；
• curated list：例如 awesome-agent-skills；
• 成体系的方法论仓库：例如 obra/superpowers。

挑选时我会看五个信号：

find-skills 这类元 skill 的价值就在于帮你做第一轮发现，但最终仍然要人工判断质量。我的经验是：先安装少量“流程型”和“元管理型” skill，再按项目需求补专业 skill。

自己创建 Skill

当你发现自己第三次向 agent 解释同一套流程时，就该考虑写 skill 了。

可以用 $skill-creator 交互式创建。它通常会问：

• 这个 skill 做什么？
• 什么时候触发？
• 是 instruction-only，还是需要脚本？
• 是否需要示例、模板、参考文件？

最小版本可以手写：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

---
name: my-blog-writer
description: Write Hugo posts for this repository when the user asks to draft, edit, or publish a blog post.
---

# My Blog Writer

Use this skill when writing posts for this Hugo blog.

Workflow:

1. Inspect existing post structure.
2. Create a post bundle under `content/zh/posts/<slug>/`.
3. Use TOML front matter.
4. Prefer Mermaid for diagrams.
5. Run `hugo --minify` before claiming completion.

这已经是一个可用 skill。但真正让它稳定的是后续迭代：增加反例、写清楚不要触发的场景、把可确定的步骤搬进脚本、补充验证命令。

Skill 放在哪里

Codex 会从多个位置读取 skill。粗略可以分成四类：

我的建议是：

• 和仓库强绑定的流程放 repo 里，比如 .agents/skills/；
• 个人偏好和跨 repo 工作流放用户目录；
• 要共享给多人、还要带 MCP/app 配置时，做成 plugin；
• 不要把所有个人 skill 都塞进某个项目仓库，否则团队成员会被你的私人习惯影响。

如何删除、禁用、更新 Skill

skill 管理里最容易被忽略的是删除。很多人只会安装，不会清理，最后 agent 每次启动都面对一堆过时规则。

我建议把清理分成三档：禁用、删除、归档。

先禁用，不急着删

如果一个 skill 偶尔误触发，或者你怀疑它和另一个 skill 冲突，优先禁用。Codex 可以在 ~/.codex/config.toml 里用 [[skills.config]] 禁用指定 skill：

1
2
3

[[skills.config]]
path = "/path/to/skill/SKILL.md"
enabled = false

禁用的好处是可逆。你可以观察一段时间：没有它之后，agent 是否更稳定？是否少了误触发？如果只是 description 太宽，就改 description；如果工作流本身已经过时，再删除。

确认不用后再删除

删除方式取决于来源：

删除前最好先回答两个问题：

• 有没有其他 skill 引用它作为 required background 或 sub-skill？
• 有没有脚本、模板、MCP 配置依赖它？

skill 之间如果有依赖关系，删除一个“基础流程 skill”可能会让上层 skill 变得含糊。比如删除 verification-before-completion 之后，很多“完成前验证”的指令会失去共同语义。

更新要看来源

更新也不能一概而论：

• plugin skill：优先用 plugin manager 更新；
• git repo skill：拉取上游后 review diff；
• copied skill：手动对比上游，避免覆盖本地定制；
• 自己写的 skill：像代码一样走 review 和验证。

对重要 skill，我不建议自动无脑更新。skill 是 agent 的行为规则，更新一次等于改变工作方式。尤其是会运行命令、改文件、调用外部服务的 skill，更新后至少要用几个真实 prompt 做回归测试。

管理工具

skill 管理大致有三类工具。

第一类是 安装器 / 包管理器。日常主力可以是 vercel-labs/skills 的 npx skills add/list/update/remove：它解决“从哪里来、装到哪里去、装给哪个 agent、以后怎么更新或删除”的问题。Codex 的 $skill-installer 则更像 Codex 原生入口，适合官方 curated skill、Codex-only 临时试用，或者 skills CLI 不知道具体来源路径时兜底。

第二类是 发现器。例如 find-skills。它们解决“有没有现成 skill”的问题。但发现器不能替你判断质量，只能缩小搜索范围。

第三类是 作者工具。例如 skill-creator、Superpowers 里的 writing-skills。它们解决“如何把经验变成可复用 skill”的问题。

flowchart LR
    discover["发现<br/>find-skills<br/>awesome lists<br/>catalogs"]
    install["安装/更新/删除<br/>npx skills<br/>skill-installer<br/>plugin manager"]
    author["创建<br/>skill-creator<br/>writing-skills"]
    operate["运行<br/>implicit / explicit invocation"]
    observe["观察<br/>误触发 / 漏触发 / 失败案例"]
    evolve["演化<br/>description<br/>scripts<br/>tests<br/>references"]

    discover --> install --> operate --> observe --> evolve
    author --> operate
    evolve --> operate

如果只推荐一个起步组合，我会选：

• skills CLI：负责日常安装、列表、更新、删除；
• skill-installer：负责 Codex curated / Codex-only 兜底；
• find-skills：负责发现；
• skill-creator：负责创建；
• verification-before-completion：负责完成前证据；
• systematic-debugging：负责 bug 调查；
• requesting-code-review：负责变更审查。

这几个 skill 的共同点是：它们不是某个技术栈的技巧，而是改善 agent 工作方式的元能力。

运行策略

真正的问题不是“最多能装多少 skill”，而是“哪一小组 skill 能让 agent 在真实工作里更可预测”。

我的建议是：先装元 skill，再装工程流程 skill，最后按实际项目边界补领域 skill。

推荐安装哪些 Skill

下面是我会优先考虑的 skill 类型。

第一批：元 Skill

这些 skill 不直接写业务代码，而是管理 agent 的工作方法。

第二批：工程流程 Skill

这些 skill 对大多数代码仓库都有价值。

obra/superpowers 值得单独看，因为它不是一个单点 skill，而是一套组合式方法论。它把 brainstorming、plan、TDD、debugging、review、verification、finishing branch 串成完整开发流程。即使你不完全照它的强约束执行，也可以从里面学习“流程 skill 应该怎样互相连接”。

第三批：领域 Skill

领域 skill 要按你的工作内容安装。比如：

• 前端：design system、Figma、可访问性、Playwright 检查；
• 文档：Hugo、Docusaurus、Markdown lint、diagram；
• 后端：框架约定、数据库 migration、API contract；
• 运维：Docker Compose、Kubernetes、Terraform；
• 研究：论文阅读、实验记录、benchmark 分析。

领域 skill 的判断标准不是“看起来很强”，而是“它是否知道你的项目边界”。一个通用 frontend skill 可能帮你做漂亮界面，但如果它不知道当前项目的组件库、色彩规范、路由结构，就容易创造额外风格。repo-scoped skill 往往比泛用 skill 更值钱。

Skill 如何进化

skill 不是一次写完的文档，而是一个会被真实使用校准的系统。每次 agent 用错 skill，都是一次训练数据。

我会用下面这个循环维护 skill：

flowchart TD
    fail["观察失败<br/>误触发 / 漏触发 / 步骤不稳"]
    classify{"失败类型"}
    trigger["改 description<br/>收紧或放宽触发词"]
    workflow["改流程<br/>增加检查点或停止条件"]
    script["加脚本<br/>把确定性步骤自动化"]
    reference["拆 references<br/>减少主说明长度"]
    test["用真实 prompt 回归测试"]
    release["提交 / 发布 / 更新 plugin"]

    fail --> classify
    classify -- "触发问题" --> trigger
    classify -- "流程问题" --> workflow
    classify -- "执行不稳定" --> script
    classify -- "上下文太长" --> reference
    trigger --> test
    workflow --> test
    script --> test
    reference --> test
    test --> release

几个经验很关键。

第一，先修 description。很多 skill 问题不是正文写得不够多，而是入口写错了。description 应该像路由表，不像介绍页。

第二，给 skill 写“不要做什么”。agent 特别容易把相邻任务合并。比如写博客 skill 应该说明它不负责发布、部署、生成营销图，除非用户明确要求。

第三，把确定性操作放进脚本。凡是“每次都一样”的步骤，最好不要让 agent 重新解释。比如解析文件、生成图表、格式化输出、校验 front matter，都适合脚本化。

第四，保留失败案例。不要只写 happy path。一个成熟 skill 应该包含常见误区、停止条件、需要向用户确认的边界。

第五，控制 skill 数量。装太多 skill 会让初始索引变吵，也会增加隐式触发的不确定性。skill 管理不是收藏，而是修剪。

一个实用的 Skill 管理策略

如果从零开始，我会按这个顺序做：

1. 用 skills CLI 作为日常管理入口，先保证自己能 list、安装指定 skill、更新和删除。
2. 先装元 skill：find-skills、skill-creator，并保留 $skill-installer 作为 Codex curated 兜底入口。
3. 再装工程流程 skill：debugging、verification、code review、TDD。
4. 观察一周真实任务，把重复解释超过三次的流程写成 repo skill。
5. 对每个新增 skill 写清楚触发词和反触发场景。
6. 每月清理一次：禁用误触发 skill，删除不用的 skill，更新关键 skill。
7. 对重要 skill 建立回归 prompt：至少覆盖应该触发、不能触发、边界任务三类。

最后形成的结构大概是：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

~/.agents/skills/
  skill-creator/
  find-skills/
  star-resume/
  diagram-tools/

repo/.agents/skills/
  project-build/
  project-release/
  project-blog-writer/
  project-code-review/

个人目录放长期习惯，repo 目录放项目事实。两者分开，skill 才不会互相污染。

结语

skill management 的核心不是安装更多能力，而是让 agent 的行为更可预测。

一个好 skill 应该像一个小而清楚的接口：输入是什么、什么时候调用、内部怎么做、失败时如何停、完成时如何验证。安装 skill 是开始，删除和禁用 skill 是治理，持续演化 skill 才是长期收益。

如果把 agent 看作一个会使用工具的协作者，那么 skill 就是团队流程的可执行版本。它把“我通常会怎么做”变成“agent 下次也能稳定这么做”。这一步做好之后，AI 助手不只是更聪明，而是更可靠。

Further Reading

• Agent Skills - Codex
• openai/skills
• vercel-labs/skills
• obra/superpowers
• VoltAgent/awesome-agent-skills
• Agent Skills Specification