---
title: "用 Skills 辅助开发"
description: "全面介绍Agent Skill的渐进式加载机制，讲解固化团队开发经验为标准化工作流的方法"
---

## Skill 是什么

**Skill(Agent Skill)** 是一份打包好的"操作手册":一个目录,核心是 `SKILL.md`,可附带脚本、模板、参考资料。它告诉 Agent 在某类任务上应该怎么做——团队的发布流程、代码评审清单、特定框架的最佳实践、内部系统的操作步骤。

```text
.claude/skills/
└── deploy-checklist/
    ├── SKILL.md          # 必需:说明 + 步骤
    ├── scripts/
    │   └── preflight.sh  # 可选:可执行脚本
    └── references/
        └── rollback.md   # 可选:深入文档,按需再读
```

`SKILL.md` 的格式:

```markdown
---
name: deploy-checklist
description: 部署生产环境前的检查与发布流程。当用户要求部署、发版、上线时使用。
---

# 部署流程

1. 运行 `scripts/preflight.sh`,全部通过才继续;
2. 确认 CHANGELOG 已更新;
3. `git tag` 按 `vX.Y.Z` 规范打标;
4. 回滚预案见 references/rollback.md。
```

## 为什么 Skills 是"上下文友好"的

Skills 的关键设计是**渐进式披露(progressive disclosure)**,这让它和"把所有规范都塞进 CLAUDE.md"有本质区别:

| 层级 | 何时进入上下文 | 大小 |
| --- | --- | --- |
| 1. name + description | 会话开始就常驻 | 每个 Skill 仅几十 token |
| 2. SKILL.md 正文 | Agent 判断任务相关时才加载 | 几百~几千 token |
| 3. 附带文件/脚本 | 正文引用、确实需要时才读取/执行 | 不设限 |

也就是说,你可以沉淀 50 个 Skill,常驻成本只有 50 条一句话的目录索引;而 CLAUDE.md 里的每个字都是**每轮全量常驻**的。经验法则:

- **CLAUDE.md**:少而精,只放"永远适用"的项目事实(构建命令、目录结构、硬性约定);
- **Skills**:放"特定场景才需要"的流程和知识(部署、迁移、性能排查、PDF 处理……)。

脚本是 Skills 的另一半威力:确定性的步骤写成脚本让 Agent 直接执行,比让模型每次"现场发挥"更可靠、更省 token。

## 在 Claude Code 中使用

- **存放位置**:项目级 `.claude/skills/<name>/SKILL.md`(随仓库共享给团队)、用户级 `~/.claude/skills/`(个人通用),也可通过插件(plugin)分发;
- **触发方式**:两种——Agent 根据 `description` **自动判断调用**;或用户显式输入 `/<skill-name>` 手动触发(即斜杠命令,自定义 slash command 与 skill 已是同一套机制);
- **编写要点**:`description` 是唯一的"检索线索",要写清**做什么 + 什么时候用**("当用户要求部署、发版时使用"),否则 Agent 不知道何时该用它;
- **调试**:如果 Skill 没被触发,先检查 description 是否含用户会说的关键词;`claude skills list` 可查看已加载的 Skills。

Codex 及其他 Agent 生态中对应的做法是 `AGENTS.md` + 可执行脚本/prompts 目录,思路一致:把流程性知识放在文件系统里按需取用,而不是常驻提示词。

## 适合做成 Skill 的场景

1. **重复的多步流程**:发版、数据库迁移、生成周报——写一次,团队每个人的 Agent 都会做;
2. **有既定规范的产出**:提交信息格式、PR 描述模板、组件脚手架;
3. **领域知识包**:公司内部 API 的调用惯例、特定文件格式的处理(官方就内置了 pdf、docx、xlsx、pptx 等文档处理 Skills);
4. **带工具的工作流**:SKILL.md 说明 + 配套脚本,例如"性能排查"Skill 附带火焰图采集脚本。

## 反模式

- ❌ 把整本风格指南贴进 SKILL.md 正文 → 应拆到 `references/` 按需读;
- ❌ description 写得太笼统("辅助开发") → Agent 永远不会想起它;
- ❌ 一个 Skill 干十件事 → 拆小,一个 Skill 一个明确场景;
- ❌ 用 Skill 存放每轮都需要的硬约定 → 那是 CLAUDE.md 的职责。

## 下一步

不想从零写?看看社区验证过的第三方 Skill:[Skills 推荐](/guide/skills-picks)——治过度工程的 Ponytail、治"AI 味"前端的 ui-ux-pro-max 与 Impeccable。