摘要

Agent Skills正在成为AI编程的核心扩展机制。本文从Skill的概念出发，详解SKILL.md文件规范、目录结构中每个文件夹的作用、渐进式加载原理，并分享5个实战编写技巧——从description编写到Gotchas防坑，附完整代码示例，帮助开发者写出高质量、可复用的Skill。

关键词：Agent Skills、SKILL.md、编写技巧、目录结构、渐进式加载、Cursor、Claude Code、CodeBuddy

---

一、Skill是什么？

1.1 一句话定义

Skill是写给AI Agent看的操作手册。

它不是给人看的README。你把"遇到某类问题该怎么处理"写成一个标准化的SKILL.md文件，AI就能按照你的规矩来执行特定任务。

1.2 Skill vs Prompt vs MCP

维度	Prompt	Skill	MCP
本质	单次对话指令	持久化能力单元	标准化工具接入协议
生命周期	用完就丢	写一次永久复用	编写一次全平台通用
触发方式	手动输入	AI自动识别调用	AI调用函数
可带资源	❌ 纯文字	✅ 脚本+文档+资源	✅ 工具定义
团队共享	❌ 难	✅ Git管理	✅ 注册表
形象类比	说一句话	给一本操作手册	装一个USB接口

💡 核心区别：Skill解决"怎么干"（知识+流程），MCP解决"能不能连"（工具+接口），Prompt解决"当下这一句"（即时指令）。

1.3 支持Skill的平台

Cursor ✅
Claude Code ✅
CodeBuddy ✅
GitHub Copilot ✅
Windsurf ✅

---

二、目录结构详解

2.1 标准目录

my-skill/
├── SKILL.md           ← 核心：操作手册（必须有）
├── scripts/           ← 可选：自动化脚本
│   ├── deploy.sh
│   └── validate.py
├── references/        ← 可选：参考文档
│   ├── api-guide.md
│   └── tone-guide.md
└── assets/            ← 可选：资源文件
    └── config-template.json

2.2 每个目录的作用

SKILL.md — 核心操作手册

唯一必须有的文件。包含两部分：

# Part 1: YAML Frontmatter（元数据）
---
name: code-review
description: 按团队标准审查代码。当用户要求review、审查、检查代码质量时使用。
allowed-tools: Read, Bash(grep:*)
---

# Part 2: Markdown Body（正文指令）
## 审查步骤
1. 架构维度
2. 异常处理
3. 日志规范
4. 安全风险

YAML Frontmatter字段说明：

字段	必需	说明	约束
name	✅	Skill唯一标识	小写+连字符，1-64字符
description	✅	告诉AI何时使用	< 1024字符
allowed-tools	可选	允许使用的工具白名单	如 Read, Write, Bash
context	可选	fork=隔离子代理	fork/默认
agent	可选	指定子代理类型	仅context:fork时有效
license	可选	许可证	MIT, Apache-2.0等

scripts/ — 确定性执行的脚本

# scripts/check-deps.sh
#!/bin/bash
# 检查项目依赖是否存在安全漏洞
echo "正在检查依赖安全..."
npm audit --production 2>&1
exit_code=$?
if [ $exit_code -ne 0 ]; then
    echo "⚠️ 发现安全漏洞，请查看上方详情"
else
    echo "✅ 未发现安全漏洞"
fi

为什么要用scripts而不是让AI直接写？

AI直接执行：每次可能写出不同的检查逻辑（不确定性）
Scripts执行：每次都跑同一个脚本（确定性）

需要精确执行的操作 → 写脚本
需要灵活判断的操作 → 写指令

references/ — 详细参考文档

# references/coding-standards.md

## 命名规范
- 变量：camelCase
- 常量：UPPER_SNAKE_CASE
- 函数：camelCase，动词开头

## 错误处理
- 统一使用自定义AppError
- 必须包含错误码和消息
- 禁止吞掉异常

太长不适合放在SKILL.md正文里的内容放这儿。AI按需读取——需要的时候再去看，不会一股脑全塞进上下文。

assets/ — 配置模板和资源

// assets/config-template.json
{
  "project": "{{PROJECT_NAME}}",
  "version": "1.0.0",
  "database": {
    "host": "localhost",
    "port": 5432,
    "name": "{{DB_NAME}}"
  }
}

AI在生成代码时可以直接引用这些模板，保证输出符合团队规范。

2.3 渐进式加载原理

┌─────────────────────────────────────────┐
│  L1: Metadata (name + description)       │ ← 常驻上下文 (~100 tokens)
│  AI看这个决定是否调用                      │
├─────────────────────────────────────────┤
│  L2: SKILL.md Body                       │ ← 触发时加载 (<500行, <5K tokens)
│  AI读这个了解怎么干                        │
├─────────────────────────────────────────┤
│  L3: references/ scripts/ assets/        │ ← 按需读取 (<5K tokens/文件)
│  AI需要细节时才去看                        │
└─────────────────────────────────────────┘

为什么这样设计？ 上下文窗口是公共资源，需要跟系统Prompt、对话历史、代码文件共享。如果10个Skill的全部内容都常驻上下文，Token直接炸了。

---

三、5个实战编写技巧

3.1 技巧1：description是灵魂

AI靠description决定什么时候调用你的Skill。写差了等于白写。

推荐模板：

Use when [触发条件/关键词] to [目标行动] by [核心操作] while [重要限制]

对比示例：

等级	description	问题
❌ 差	“处理PDF”	太笼统，AI不知道什么时候用
⚠️ 一般	“PDF文件处理工具”	缺少触发条件和能力边界
✅ 好	“从PDF文件中提取文本和表格，填写PDF表单，合并多个PDF。在用户提到PDF文档处理时使用。”	触发条件+能力范围清晰

进阶：加负面案例

description: >
  生成PPT演示文稿。Use when users mention PowerPoint, slides, 
  or presentation. Do NOT use when user only needs a quick text summary.

告诉AI"什么时候不该用"，同样重要。

3.2 技巧2：先调研再写

❌ 错误流程：凭经验直接写 → 质量一般
✅ 正确流程：让AI调研最佳实践 → 基于调研结果写 → 质量翻倍

操作方法：

你：我想创建一个Go代码审查的Skill。
    请先搜索Go代码审查的最佳实践、常见问题和社区推荐的检查维度，
    然后帮我设计一个完整的Skill结构。

AI会自动完成调研→总结→结构设计。出来的Skill比你凭空想的专业10倍。

3.3 技巧3：每个Skill只干一件事

❌ 全能型Skill（1000+行）：
   code-review + security-audit + performance-check + test-writing
   → AI蒙圈，选择性忽略，甚至幻觉

✅ 单一职责Skill（各100-300行）：
   code-review/SKILL.md
   security-audit/SKILL.md
   performance-check/SKILL.md
   test-writer/SKILL.md
   → 各司其职，精准触发

判断标准：SKILL.md超过500行→该拆了。

3.4 技巧4：用代码代替文字

# ❌ 用文字描述
检查代码中是否有硬编码的密钥。具体来说，需要搜索源代码文件
中包含password、secret、api_key等关键词的行，判断它们是否
直接赋值为字符串常量...

# ✅ 用代码+命令
## 检查硬编码密钥
运行以下命令：
```bash
grep -rn "password\|secret\|api_key\|token" src/ \
  --include="*.go" --include="*.py" --include="*.js" \
  | grep -v "test" | grep -v "mock"

如果有匹配结果，标记为 [✗] 安全风险。

AI读代码的准确度比读自然语言高得多。

### 3.5 技巧5：加Gotchas部分

**这是ROI最高的改进。** 专门写一段"AI容易犯的错误和陷阱"。

```markdown
## ⚠️ Gotchas

- **不要用 rm -rf 删除任何目录** — 使用 trash 命令代替
- **数据库操作前必须先备份** — 执行 scripts/backup.sh
- **不要修改代码，只做审查** — 这是review不是fix
- **大文件(>1000行)分段审查** — 一次性全读会超出上下文
- **遇到二进制文件直接跳过** — 不要尝试解析 .png/.pdf

一个Gotcha能救你一条命。AI特别容易在边缘情况上翻车，提前告诉它哪些坑不能踩。

---

四、完整Skill示例

4.1 代码审查Skill

.codebuddy/skills/code-review/
├── SKILL.md
├── scripts/
│   └── check-deps.sh
└── references/
    └── coding-standards.md

# SKILL.md
---
name: code-review
description: >
  按团队标准审查代码质量。Use when users ask to review, audit, 
  or check code quality. Covers architecture, error handling, 
  logging, and security dimensions.
allowed-tools: Read, Bash(grep:*), Bash(find:*)
---

# 代码审查 Skill

## 审查流程

### Step 1: 架构检查
- 模块拆分是否合理，职责是否单一
- 执行 `scripts/check-deps.sh` 检查依赖安全

### Step 2: 异常处理
- 外部调用是否有try-catch
- 是否使用自定义AppError（见 references/coding-standards.md）

### Step 3: 日志规范
- 关键操作是否有structlog日志
- 是否包含trace_id

### Step 4: 安全检查
```bash
grep -rn "password\|secret\|api_key" src/ --include="*.go" | grep -v test

输出格式

=== 代码审查报告 ===
[✓/✗] [类别] 问题描述及修复建议
=== 总结 ===
通过: X/4  风险等级: 高/中/低

⚠️ Gotchas

• 不要修改代码，只做审查
• 大文件(>1000行)分段审查
• 遇到生成代码(.gen.go)跳过

---

## 五、质量检查清单

写完Skill后，对照这份清单自查：

- [ ] description是否明确了触发条件和能力边界？
- [ ] SKILL.md是否少于500行？
- [ ] 是否每个Skill只解决一个问题？
- [ ] 是否有代码示例或命令模板（而非纯文字）？
- [ ] 是否有Gotchas部分预防常见错误？
- [ ] 详细文档是否移到了references/？
- [ ] 需要确定性执行的操作是否写成了scripts？
- [ ] 是否在至少3个真实场景测试过（正常/边缘/不适用）？
- [ ] 是否假设了工具已安装？（应明确写安装命令）
- [ ] name是否全小写+连字符？

---

## 六、总结

**Skill的本质是把"人的经验"变成"AI的能力"。**

写好一个Skill的核心：

| 原则 | 一句话 |
|------|--------|
| description是灵魂 | 写差了等于白写 |
| 先调研再写 | 质量差10倍 |
| 单一职责 | 超过500行就该拆 |
| 代码优于文字 | AI读代码更准确 |
| Gotchas预防翻车 | ROI最高的一段 |

花半天写5个Skill，之后每天省2小时。这笔账算得过来。

---

## 参考资料

1. [Agent Skills | Cursor Docs](https://cursor.com/docs/skills)
2. [编写SKILL.md | Open Agent Skills](https://openagentskills.dev/zh/docs/writing-skill-md)
3. [如何写好AI Agent Skill | zayfEn'Closure](https://www.zayfen.com/posts/how-to-write-agent-skills/)
4. [最佳实践 | Agent Skills学习及案例](https://www.claudeskills.org/zh/docs/agent-skills/best-practices)
5. [Best Practices for Creating Agent Skills | GitHub](https://github.com/mgechev/skills-best-practices)
6. [CodeBuddy Skills系统文档](https://www.codebuddy.cn/docs/cli/skills)

---

## 互动交流

你写过哪些好用的Skill？踩过什么坑？有什么独家心得？

欢迎在评论区分享你的实战经验！

- 🌟 **收藏**本文
- 👍 **点赞**支持
- 💬 **转发**给同事
- 📌 **关注**我的CSDN