4 个提升 AI Agent 工作质量的 Skills：搜索、创建、设计与调试

AI（人工智能）Agent（智能体）想要稳定完成复杂任务，不能只靠一段临时提示词。更可靠的做法是把常用能力沉淀成 Skill：里面写清楚什么时候使用、怎么做、需要哪些脚本、参考哪些资料，以及哪些步骤不能跳过。

一个 Skill 可以理解成“给 Agent 用的能力包”。它不是普通文档，也不是给人看的 README，而是让模型在合适的任务里自动加载、按规则行动的一组指令和资源。

常见 Skill 大致解决四类问题：

这四类能力可以组成一条比较完整的 Agent 工作链路：

flowchart LR
    A[发现任务需求] --> B{已有合适 Skill?}
    B -- 有 --> C[用 find-skills 搜索并安装]
    B -- 没有 --> D[用 skill-creator 创建 Skill]
    C --> E[进入任务执行]
    D --> E
    E --> F{需要开发功能?}
    F -- 是 --> G[Brainstorming 先做设计]
    G --> H[获得确认后实现]
    F -- 否 --> I[直接执行对应流程]
    H --> J{出现问题?}
    I --> J
    J -- 是 --> K[Systematic Debugging 定位根因]
    J -- 否 --> L[完成任务]
    K --> H

用 Vercel find-skills 搜索和安装 Skill

Skill 多起来以后，最大的问题不是“怎么写”，而是“怎么找”。Vercel 提供的 find-skills 更像一个 Skill 包管理器，可以通过 npx skills 命令搜索、安装和更新 Skill。

npx 是 Node.js 生态里的包执行工具，适合临时运行命令行程序，不一定需要提前全局安装。

常用命令如下：

# 按关键词搜索 Skill
npx skills find react performance

# 安装某个 Skill
npx skills add <package-name>

# 检查本地已安装 Skill 是否有更新
npx skills check

# 更新所有已安装 Skill
npx skills update

如果要找 React 性能优化相关能力，可以直接运行：

npx skills find react performance

命令会返回匹配的 Skill，并提供安装命令、说明和相关文档入口。相比在不同仓库之间手动翻找，这种方式更适合把 Skill 当成可管理的依赖来使用。

Vercel 还提供了在线搜索站点：

https://skills.sh

对应仓库地址：

https://github.com/vercel-labs/skills/blob/main/skills/find-skills/SKILL.md

适合使用 find-skills 的场景：

用 Anthropic skill-creator 编写自己的 Skill

如果没有现成 Skill，或者任务规则和业务上下文强绑定，就需要自己写。Anthropic 的 skill-creator 给出了比较标准的组织方式。

一个典型 Skill 目录可以长这样：

my-skill/
├── SKILL.md
├── scripts/
│   └── validate.py
├── references/
│   └── api-rules.md
└── assets/
    └── template.json

各目录职责要分清楚：

YAML（YAML Ain't Markup Language，一种配置序列化格式）元数据用于让 Agent 判断这个 Skill 适合什么任务。Markdown 则用来写具体操作规则。

一个简化版 SKILL.md 可以这样写：

---
name: api-contract-review
description: Review API contract changes and check naming, compatibility, error format, and pagination rules.
---

# API Contract Review Skill

Use this skill when reviewing API contract changes.

## Workflow

1. Read the changed API files.
2. Compare endpoint naming with `references/api-rules.md`.
3. Check whether response fields remain backward compatible.
4. Run `scripts/validate.py` if an OpenAPI file is available.
5. Report issues by severity: blocker, warning, suggestion.

## Rules

- Do not rewrite the whole contract unless asked.
- Prefer backward-compatible changes.
- If a rule is unclear, ask one focused question instead of guessing.

这里有几个关键设计原则。

渐进式加载：不要一次塞满上下文

Skill 不应该把所有资料一次性塞给模型。更合理的方式是分层加载：

flowchart TD
    A[任务触发] --> B[读取 Skill 元数据]
    B --> C{元数据是否匹配任务?}
    C -- 否 --> D[不加载 Skill 主体]
    C -- 是 --> E[加载 SKILL.md 主体指令]
    E --> F{需要更多背景?}
    F -- 否 --> G[按主体指令执行]
    F -- 是 --> H[按需读取 references 或 assets]
    H --> G

这样做的目的很直接：节省上下文窗口。Agent 只需要先知道“这个 Skill 是干什么的”，匹配后再读取主体，必要时再打开更长的参考资料。

自由度要和任务风险匹配

任务越容易出错，指令越要具体。比如数据库迁移、账单计算、权限改动这类任务，Skill 应该明确检查项、禁止项和验证步骤。

任务越开放，指令可以越宽。比如头脑风暴、命名建议、方案草稿，过细的限制反而会让 Agent 产出变窄。

可以按这个原则设计指令粒度：

不要把 Skill 写成项目说明书

Skill 的目标是让 Agent 完成任务，所以不需要堆太多给人看的材料。比如 README.md、安装指南、更新日志、项目愿景说明，通常不是 Skill 的必要内容。

更应该保留的是：

• Agent 什么时候使用这个 Skill；
• 执行任务必须遵守哪些步骤；
• 哪些操作禁止做；
• 需要调用哪些脚本；
• 出错时怎么处理；
• 需要参考哪些规则文件。

对应仓库地址：

https://github.com/anthropics/skills/blob/main/skills/skill-creator/SKILL.md

用 Brainstorming Skill 强制先设计再实现

很多 Agent 出问题，不是因为不会写代码，而是太快开始写代码。需求还没问清，边界还没确认，项目结构还没看，就直接创建文件、改接口、写实现，后面很容易返工。

Brainstorming Skill 的核心约束是：任何项目开始实现前，都必须先经过设计讨论，并且获得确认后才能写代码。

它的流程可以拆成几段：

flowchart TD
    A[接到开发任务] --> B[了解上下文]
    B --> C[查看现有文件、文档、最近提交]
    C --> D[逐个问题澄清需求]
    D --> E[明确目标、约束、成功标准]
    E --> F[提出 2 到 3 个方案]
    F --> G[说明每个方案的取舍]
    G --> H[给出推荐方案]
    H --> I[按模块展示设计]
    I --> J{设计是否被确认?}
    J -- 否 --> D
    J -- 是 --> K[保存设计文档到 docs/plans/]
    K --> L[允许调用实现类 Skill]

这个 Skill 最重要的是“门禁规则”：

设计文档保存到 docs/plans/，可以让后续实现有明确依据。这样 Agent 不只是“记得刚才聊了什么”，而是有一个可回看、可修改、可追踪的计划文件。

一个简化的设计文档可以包含这些部分：

# Plan: Add Repository Search API

## Goal

Add an endpoint for searching repositories by keyword, language, and star range.

## Constraints

- Must not break existing repository list API.
- Query must be paginated.
- Empty keyword should return validation error.

## Options

### Option A: Extend existing list endpoint

Pros:
- Less routing code.
- Reuses existing response format.

Cons:
- Existing endpoint may become too complex.

### Option B: Add a dedicated search endpoint

Pros:
- Clear responsibility.
- Easier to tune search logic later.

Cons:
- Adds a new API surface.

## Decision

Use Option B.

## Modules

- Route: `GET /repositories/search`
- Service: `RepositorySearchService`
- Validation: keyword, language, stars, page, pageSize
- Tests: validation, pagination, sorting

对应仓库地址：

https://github.com/obra/superpowers/blob/main/skills/brainstorming/SKILL.md

这种 Skill 特别适合中等以上复杂度的任务：

用 Systematic Debugging Skill 避免随机修 Bug

调试时最危险的做法是“感觉哪里有问题就改哪里”。这种方式可能偶尔奏效，但更常见的结果是：一个 Bug 没解决，又引入两个新问题。

Systematic Debugging Skill 的原则很硬：没有找到根本原因之前，不允许尝试修复。

完整流程分成四个阶段：

flowchart TD
    A[发现 Bug] --> B[阶段一：根因调查]
    B --> B1[阅读错误信息]
    B --> B2[稳定复现问题]
    B --> B3[检查最近改动]
    B --> B4[在组件边界加诊断日志]

    B1 --> C[阶段二：模式分析]
    B2 --> C
    B3 --> C
    B4 --> C

    C --> C1[寻找类似的正常代码]
    C --> C2[对比差异]
    C --> C3[理解依赖关系]

    C1 --> D[阶段三：假设和测试]
    C2 --> D
    C3 --> D

    D --> D1[提出单一假设]
    D1 --> D2[用最小改动验证]
    D2 --> D3{假设成立?}

    D3 -- 否 --> B
    D3 -- 是 --> E[阶段四：实现修复]
    E --> E1[先写失败测试]
    E1 --> E2[修复根因]
    E2 --> E3[验证测试通过]
    E3 --> F{连续 3 次修复失败?}
    F -- 是 --> G[暂停，重新审视架构设计]
    F -- 否 --> H[完成修复]

四个阶段对应不同目标。

在多组件系统里，诊断日志尤其重要。比如前端、网关、服务端、数据库都参与一次请求时，不能只看最终报错，而要确认数据在哪个边界开始异常。

sequenceDiagram
    participant U as 用户界面
    participant G as 网关
    participant S as 服务端
    participant D as 数据库

    U->>G: 发送请求
    G->>S: 转发请求
    S->>D: 查询数据
    D-->>S: 返回结果
    S-->>G: 返回响应
    G-->>U: 展示结果

    Note over U,G: 检查请求参数是否正确
    Note over G,S: 检查鉴权和路由是否正确
    Note over S,D: 检查查询条件是否正确
    Note over S,G: 检查响应结构是否符合预期

一次只验证一个假设，是这个调试方法的重点。比如怀疑缓存导致脏数据，就只临时绕过缓存验证；怀疑序列化字段丢失，就只打印序列化前后的对象。不要同时改缓存、改字段名、改查询条件，因为那样即使问题消失，也不知道真正原因是什么。

对应仓库地址：

https://github.com/obra/superpowers/blob/main/skills/systematic-debugging/SKILL.md

经验上，15 到 30 分钟的系统化定位，通常比 2 到 3 小时的随机试错更可控。它慢在开头，但能避免反复回滚和二次破坏。

四个 Skill 如何组合使用

单独看，每个 Skill 解决一个点；组合起来，Agent 的工作方式会更接近工程团队里的标准流程。

一个实际工作流可以是：

# 1. 搜索是否已有相关能力
npx skills find debugging

# 2. 安装合适的 Skill
npx skills add <debugging-skill-package>

# 3. 定期检查更新
npx skills check

# 4. 批量更新
npx skills update

如果没有合适的能力，再创建自己的 Skill，并尽量遵守几个规则：

• 一个 Skill 只解决一类明确问题，不要写成万能助手；
• description 要准确，因为它会影响 Agent 是否触发该 Skill；
• 长资料放进 references/，不要全部塞进 SKILL.md；
• 重复、机械、可验证的动作放到 scripts/；
• 高风险任务必须写清禁止事项和验证步骤；
• Skill 变多后要定期检查更新，避免本地规则过期。

什么时候应该写 Skill，什么时候不用

不是所有提示词都值得升级成 Skill。判断标准可以简单一点：只要某个任务会重复出现、规则容易忘、出错代价较高，就适合沉淀成 Skill。

Skill 的价值不只是“让 Agent 多会一点”，更重要的是把工作方式固定下来。搜索 Skill 解决发现问题，创建 Skill 解决沉淀问题，Brainstorming 解决过早实现问题，Systematic Debugging 解决乱猜乱改问题。把这些能力串起来，Agent 才更像一个按流程工作的工程助手，而不是每次从零开始发挥。