Skill学习指南🧑‍💻｜AI Agent技能包从零入门到精通

前言推荐：想要流畅调试 Claude Skill、搭建 AI 智能体、实操各类大模型，推荐使用 KoalaAPI。国内API中转推荐的高质量服务商，接口超低延迟、兼容全部 AI 编程工具、模型库齐全，资费性价比极高，不管是新手学习 Skill，还是商用部署智能体，都是最优选择，大幅降低 AI 开发门槛。

一、什么是 Skill？

Skill 是扩展 AI Agent 能力的模块化知识包（一种可复用的能力模块） 。

把它想象成一本专项操作手册——当 AI 需要完成某个特定领域的任务时（比如分析业务日志、转换音频格式、部署到云端），Skill 就会被加载进来，提供专属的工作流程、工具脚本和领域知识。它将知识、流程和工具封装在一起，让你能够快速完成特定领域的任务。

Skill = 专业知识 + 操作流程 + 工具调用

核心价值

把那些通用 AI 不具备，但领域专家天天用的知识固化下来，让 AI 具备领域专家的能力。

和 MCP 及 Prompt 的区别

System Prompt 是一次性指令，MCP 是给 AI 装新手臂，Skill 是给 AI 装行为准则。

维度	System Prompt	MCP	Skill
本质	一次性角色设定	工具/能力扩展协议	可复用行为约束
解决什么问题	临时调整 AI 风格	AI 连不到外部系统	AI 不按规范工作
需要写代码	否	是（Server/Client）	非必须（纯 Markdown就可以，scripts为可选）
持久性	仅当前对话	持久（服务常驻）	持久（文件存储）
面向人群	所有人	开发者	所有人
典型例子	"你是一个翻译助手"	连接数据库、调用 API	强制 TDD、规范 Git 提交

二、Skill 的说明

目录结构

skill-name/
├── SKILL.md          ← 必须有，核心文件
└── （可选资源）
    ├── scripts/      ← 可执行脚本（Python/Bash 等）
    ├── references/   ← 参考文档（按需加载）
    └── assets/       ← 静态资源（模板、图片、字体等）

SKILL.md 的结构

Claude Code Skill 使用 YAML Front Matter + Markdown 正文 的格式：

---
name: skill-unique-name      # 技能的唯一标识符
description: |               # 触发场景描述（AI 据此判断何时使用）
  Use when doing X.
  Use BEFORE doing Y.
  这个 Skill 做什么，什么时候触发它。
---

# 技能正文（Markdown）  # 给 AI 的操作指南

## 核心原则
- 原则一
- 原则二

## 执行流程
1. 第一步
2. 第二步
3. 第三步

## 禁止行为
- 禁止做 A
- 禁止跳过 B

Skill 的五要素

┌─────────────────────────────────────────────┐

│ 1. Metadata（元数据） │

│ name: 唯一标识符 │

│ description: 触发场景描述 │

│ │

│ 2. Context（适用上下文） │

│ 该技能适用的场景和前提条件 │

│ │

│ 3. Process（执行流程） │

│ 步骤化工作流，可包含 checklist │

│ │

│ 4. Constraints（约束规则） │

│ 禁止行为、必须遵守的原则 │

│ │

│ 5. Output Format（输出规范） │

│ 结果应如何呈现、什么格式 │

└─────────────────────────────────────────────┘

Skill 安装方式与目录结构制作

Claude Code 存放目录

• ~/.claude/skills/：全局技能（所有项目可用）
• .claude/skills/：项目级技能（仅当前项目可用）

文件命名示例

• ~/.claude/skills/tdd/SKILL.md
• ~/.claude/skills/code-review/SKILL.md
• ~/.claude/skills/git-commit/SKILL.md

Skill 完整目录结构

一个完整的 Skill 不只是一个 .md 文件，还可以包含辅助资源：

.claude/skills/my-skill/
├── SKILL.md            # Skill 主文件（必须）
├── reference/             # 参考资料目录（可选）
│   ├── api-spec.md        # API 规范文档
│   ├── style-guide.md     # 代码风格指南
│   └── examples/          # 示例文件
│       └── good-example.ts
├── scripts/               # 辅助脚本目录（可选）
│   ├── validate.sh        # 验证脚本
│   └── setup.py           # 环境初始化脚本
└── assets/                # 静态资源目录（可选）
    ├── checklist.md       # 检查清单模板
    └── templates/         # 输出模板
        └── report.md

三、三级加载机制（理解这个很关键）

Skill 采用按需加载的设计，避免浪费上下文窗口，节省 Token 消耗：

级别	内容	何时加载	大小
第一级	name + description	始终在上下文中	~100 词
第二级	SKILL.md 正文	Skill 被触发后	< 5000 词
第三级	scripts/ references/ assets/	AI 判断需要时	无限制

实际效果：AI 随时知道有哪些 Skill，但只有真正需要时才"打开"它，极致节省 Token。

四、三类可选资源详解

scripts/ 确定性脚本

用途

把反复编写的代码固化成可直接执行的脚本。Skill 执行过程中可调用的脚本。

适合场景

• 旋转 PDF：scripts/rotate_pdf.py
• 解密音频：scripts/decrypt_ncm.py
• 分析日志：scripts/parse_log.py

优势

不需要读入上下文就能执行，大幅节省 token。

references/ 参考文档

用途

存储 AI 需要参考但不必一直占用上下文的知识。给 AI 提供背景知识和参考规范。

适合场景

• 数据库表结构：references/schema.md
• API 文档：references/api_docs.md
• 公司政策：references/policies.md

设计原则

按领域拆分成独立文件，用户问销售数据时只加载 sales.md，不加载 finance.md。

assets/ 静态资源

用途

存储输出中会用到的文件，不需要读入上下文。模板、静态文件。

适合场景

• 前端模板：assets/frontend-template/
• PPT 模板：assets/slides.pptx
• 品牌 Logo：assets/logo.png
• checklist 模板：checklist.md

在 Skill 中引用资源的方式

---
name: code-review
description: Use when reviewing code changes before merging.
---

## 参考规范
请在审查前阅读 reference/style-guide.md 中的编码规范。

## 执行流程
1. 运行 scripts/validate.sh 做静态检查
2. 按照 assets/checklist.md 逐项审查
3. 使用 assets/templates/report.md 格式输出结果

五、创建 Skill 的完整流程

第 1 步：明确使用场景

在动手之前，先想清楚具体用例：

• 用户会说什么话来触发这个 Skill？
• 期望 AI 完成什么具体任务？
• 有哪些典型的输入/输出例子？

第 2 步：规划可复用资源

对每个用例问自己：

"完成这个任务，每次都需要重写什么代码/重查什么文档？"

把答案整理成 scripts/、references/、assets/ 的规划清单。

第 3 步：初始化 Skill

python scripts/init_skill.py <skill-name> --path <输出目录>

该命令会自动生成标准目录结构和 SKILL.md 模板。

第 4 步：编写内容

SKILL.md 编写要点

• description：触发机制，写清使用场景、触发话术
• 正文控制在 500 行以内，细节放入 references
• 使用祈使句/动词开头：运行脚本、读取文件

资源文件编写要点

• 脚本写完必须实际运行测试
• 参考文档超过 100 行要加目录
• 删除无用示例文件

第 5 步：打包发布

python scripts/package_skill.py <skill目录路径>

打包前自动校验：YAML格式、必填字段、目录规范，校验通过生成 .skill 压缩包。

第 6 步：迭代优化

在真实任务中使用，观察 AI 表现，持续优化 SKILL.md 和配套资源。

六、核心设计原则

原则 1：精简优先

上下文窗口是公共资源。每加一段文字都问自己：

"这是 AI 不知道的信息吗？删掉会有什么后果？"

• ❌ 不要写：在开始之前，你需要理解这个任务的重要性...
• ✅ 要写：直接给出操作步骤。

原则 2：自由度要匹配任务

任务特性	自由度	写法
步骤固定、易出错	低	具体脚本 + 严格参数
有首选方案、允许变化	中	伪代码 + 可配置参数
多种方案均可、依赖上下文	高	文字指导 + 启发式原则

原则 3：渐进式披露

SKILL.md 只放核心工作流，细节通过引用指向参考文件：

## 高级功能
- **表单填写**：详见 [FORMS.md](references/FORMS.md)
- **API 参考**：详见 [API.md](references/API.md)
## 日志格式
详见 [references/log-format.md](references/log-format.md)

七、一个完整的 Skill 示例

以 pdf-rotator 旋转PDF工具 为例：

目录结构

pdf-rotator/
├── SKILL.md
└── scripts/
    └── rotate_pdf.py

SKILL.md 代码

---
name: pdf-rotator
description: |
  旋转 PDF 文件中的页面。当用户需要旋转 PDF 页面、
  修正扫描件方向时使用。触发词：旋转 PDF、PDF 页面方向
---

# PDF 旋转工具
## 使用方法
运行 `scripts/rotate_pdf.py`：
```bash
python scripts/rotate_pdf.py --input input.pdf --output out.pdf --angle 90
```
## 参数说明
- `--angle`：旋转角度，可选 90、180、270
- `--pages`：指定页码（如 `1,3,5`），不填则旋转所有页

八、常见误区

误区	正确做法
在 SKILL.md 正文写"何时使用"	写入 description 字段（正文触发后才加载）
创建 README.md、CHANGELOG.md	只保留任务必需的文件
把所有细节塞进 SKILL.md	细节放 references/，主文件只留核心流程
跳过脚本测试	脚本必须实际运行验证
深层嵌套引用	所有 references 文件一层直接引用

九、实战示例

实操提示：以上所有 Skill 案例均可直接在 KoalaAPI 搭配 Claude 系列模型调试运行，接口稳定不报错，新手零门槛上手练习，无需高额模型成本。

案例 1：TDD技能（强制测试驱动开发）

问题背景

AI 总是直接写实现代码，跳过测试，导致代码质量难以保证。

Skill 文件路径

~/.claude/skills/test-driven-development/SKILL.md

---
name: test-driven-development
description: |
  Use this skill when the user asks to implement any feature, function, or module.
  Enforces Test-Driven Development (TDD) workflow: write tests FIRST, then implementation.
---

## 核心原则
**红-绿-重构（Red-Green-Refactor）循环：**
1. **红（Red）**：先写一个失败的测试
2. **绿（Green）**：写最少的代码让测试通过
3. **重构（Refactor）**：优化代码，保持测试通过

## 强制工作流程
### 第一步：编写测试（必须先完成）
在写任何实现代码之前，必须：
1. 创建测试文件（如 `test_xxx.py` 或 `xxx.test.ts`）
2. 编写至少一个测试用例
3. 向用户展示测试代码

### 第二步：确认测试
向用户确认：
- "测试已编写完成，是否继续编写实现代码？"

### 第三步：编写实现
只有在用户确认后，才能编写实现代码。

## 禁止行为
- ❌ 禁止先写实现代码再补测试
- ❌ 禁止跳过测试直接给实现
- ❌ 禁止在同一个回复中同时给出测试和实现（除非用户明确要求）
- ❌ 禁止写没有断言的测试

案例 2：规范化 Git 提交技能

---
name: git-commit
description: |
  Use this skill when the user asks to commit code, write commit messages, or mentions git commit.
  Enforces Conventional Commits specification with mandatory scope.
---

## Commit 格式
```
<type>(<scope>): <subject>
[optional body]
[optional footer]
```

Commit Type 类型说明

Type	说明
feat	新功能
fix	Bug 修复
docs	文档变更
style	代码格式（不影响功能）
refactor	重构（不是新功能也不是修复）
perf	性能优化
test	添加或修改测试
chore	构建过程或辅助工具变动

案例 3：代码审查技能、案例4：专利撰写技能

（全文篇幅受限，保留完整规范模板，可直接复制使用，适配企业级代码审查、软件专利撰写）

十、skill-creator 与 IDE 实战

什么是 skill-creator？

Skill-Creator 是 Anthropic 官方推出的技能生成器：一个用来创建技能的母技能（Meta-Skill） 。

• 普通 Skill = 教 AI 做某一件事（如审查代码）
• Skill-Creator = 教 AI 如何创建其他 Skill

简单来说，只用自然语言描述需求，AI 自动生成完整、合规的 Skill 文件。

触发方式

1. 帮我写一个 XXX 的 Skill
2. 创建一个用于 YYY 流程的技能文件
3. 输入指令：/skill-creator

Claude Code / Cursor 使用区别

Claude Code 存放路径

• 全局：~/.claude/skills/
• 项目级：<项目根目录>/.claude/skills/

Cursor 存放路径

• Cursor专属：.cursor/skills/
• 兼容 Claude：自动加载 .claude/skills/ 目录文件

十一、Superpowers：开箱即用的企业级 Skill 套件

概念及理念

Superpowers 是一套开源、为 AI 编程助手设计的结构化工作流技能系统。可以理解为：给 AI 的软件工程培训包。

Superpowers ≠ 系统提示词，而是插件化技能系统，串联完整开发工作流：

需求输入
    │
    ▼
brainstorming（头脑风暴）
    │  └── 通过提问精炼需求，探索替代方案
    ▼
using-git-worktrees（创建隔离工作区）
    │  └── 用 git worktrees 创建独立分支
    ▼
writing-plans（编写实施计划）
    │  └── 将工作分解为 2-5 分钟的原子任务
    ▼
test-driven-development（测试驱动开发）
    │  └── 红→绿→重构循环
    ▼
subagent-driven-development（子代理驱动开发）
    │  └── 派发子代理逐任务执行 + 双阶段审查
    ▼
requesting-code-review（请求代码审查）
    ▼
verification-before-completion（完成前验证）
    ▼
finishing-a-development-branch（完成开发分支）

安装指引（极简命令）

Claude Code

# 1、注册插件市场
/plugin marketplace add obra/superpowers-marketplace
# 2、安装插件
/plugin install superpowers@superpowers-marketplace
# 3、更新插件
/plugin update superpowers

其他IDE

• Cursor：Agent聊天框输入/add-plugin superpowers
• Gemini CLI：gemini extensions install 对应开源地址

十二、发现好用的 Skill

主要 Skill 仓库

1. skills.sh（社区精选） ：https://skills.sh/

   1. 社区高质量精选Skill，按领域分类
   2. 支持评分、一键安装

2. Anthropic 官方仓库：https://github.com/anthropics/skills

   1. 官方权威规范、最新示例
   2. 新手学习最佳参考

十三、总结

Skill 本质上是人类智慧的结晶化——把专家的工作方法、判断标准、执行流程，转化为 AI 可理解和遵守的结构化约束，让 AI 从"听话的工具"升级为"有专业素养的协作者"。

核心一句话： Skill = description（决定何时触发） + SKILL.md（告诉 AI 怎么做） + 可选资源（帮 AI 做得更好）。

掌握 Skill 的本质：

• 抽象 - 从具体任务中提炼通用模式
• 封装 - 将知识流程化、结构化
• 复用 - 一次构建，持续使用

---

文末推荐✨：想要低成本实操 Skill、调试智能体、体验 Claude 全系模型，优先选择 KoalaAPI。接口稳定、兼容 Cursor/Claude Code 所有编程工具、无复杂配置，不管是新手学习 Skill 语法，还是开发者搭建企业级智能体工作流，都是性价比首选，助力轻松玩转 AI 编程！