Agent Skill 完全指南：从 SKILL.md 到实战开发，打造属于你的 AI 能力插件

Agent Skill 完全指南：从 SKILL.md 到实战开发，打造属于你的 AI 能力插件

引言

最近一段时间，随着 Claude Code、Cursor、CodeBuddy、GitHub Copilot 等 AI 编程工具的普及，一个新的概念开始频繁出现在开发者视野中：

Skill（技能）

很多人第一次看到 Skill 时会觉得：

这不就是 Prompt 吗？

但实际上，Skill 远不止一个 Prompt。

它更像是给 AI Agent 编写的一本操作手册，让 AI 在遇到特定任务时能够自动调用、自动执行，并按照预设流程完成工作。

例如：

• 代码审查 Skill
• 文档总结 Skill
• 技术博客生成 Skill
• RAG 问答 Skill
• MCP 服务开发 Skill

都属于 Skill 的典型应用场景。

本文将从 Skill 的核心概念开始，带大家系统了解：

• 什么是 Skill
• Skill 与 Prompt、MCP 的区别
• SKILL.md 文件规范
• Skill 目录结构设计
• 渐进式加载原理
• 5 个实战编写技巧

看完之后，你就能自己编写高质量的 Agent Skill。

---

目录

• [一、什么是 Skill](#一、什么是 Skill)
• [二、Skill 与 Prompt、MCP 的区别](#二、Skill 与 Prompt、MCP 的区别)
• [三、哪些平台支持 Skill](#三、哪些平台支持 Skill)
• [四、Skill 标准目录结构](#四、Skill 标准目录结构)
• [五、SKILL.md 文件详解](#五、SKILL.md 文件详解)
• [六、Skill 的渐进式加载机制](#六、Skill 的渐进式加载机制)
• [七、5 个 Skill 编写技巧](#七、5 个 Skill 编写技巧)
• [八、一个完整 Skill 示例](#八、一个完整 Skill 示例)
• 九、总结

---

一、什么是 Skill

1.1 一句话理解

Skill 本质上是：

写给 AI Agent 的操作手册。

传统 Prompt 是：

帮我审查代码

而 Skill 是：

当用户要求代码审查时：

1. 检查代码规范
2. 检查异常处理
3. 检查安全风险
4. 输出审查报告

Prompt 更像一次性指令。

Skill 更像长期保存、可重复使用的工作流程。

---

1.2 为什么需要 Skill

随着 Agent 越来越复杂，仅靠 Prompt 已经无法满足需求。

例如：

代码审查

可能需要：

• 读取代码
• 检查架构
• 检查异常处理
• 检查日志
• 检查安全漏洞
• 输出报告

如果每次都手动输入 Prompt：

帮我检查架构
帮我检查异常
帮我检查安全

显然效率很低。

而 Skill 可以将这些步骤固化下来，实现自动执行。

---

二、Skill 与 Prompt、MCP 的区别

很多开发者容易把三者混为一谈。

实际上它们解决的是完全不同的问题。

维度	Prompt	Skill	MCP
本质	单次指令	能力模块	工具协议
生命周期	一次性	长期复用	长期复用
触发方式	用户输入	Agent 自动调用	Agent 调用工具
是否包含流程	❌	✅	❌
是否包含资源	❌	✅	❌
是否包含工具能力	❌	部分支持	✅

可以简单理解为：

Prompt
↓
告诉AI现在做什么

Skill
↓
告诉AI怎么做

MCP
↓
告诉AI能调用什么

---

三、哪些平台支持 Skill

目前主流 Agent 平台已经开始支持 Skill。

包括：

• Claude Code
• Cursor
• GitHub Copilot
• CodeBuddy
• Windsurf

其中 Claude Code 对 Skill 的支持最完善。

也是目前 Skill 生态发展最快的平台。

---

四、Skill 标准目录结构

一个典型 Skill 通常长这样：

my-skill/
├── SKILL.md
├── scripts/
│   ├── deploy.sh
│   └── validate.py
├── references/
│   ├── api-guide.md
│   └── coding-guide.md
└── assets/
    └── config-template.json

其中只有一个文件是必须的：

SKILL.md

其余目录按需添加。

---

4.1 SKILL.md

这是 Skill 的核心。

相当于 Agent 的操作手册。

例如：

---
name: code-review

description: 
按团队规范进行代码审查。
当用户提到review、审查代码、
检查代码质量时使用。

allowed-tools:
  - Read
  - Bash
---

# 审查流程

1. 检查代码规范
2. 检查异常处理
3. 检查日志
4. 检查安全风险

---

4.2 scripts

用于存放自动化脚本。

例如：

scripts/
├── check-security.sh
├── deploy.sh
└── backup.sh

适用于：

• 部署
• 测试
• 依赖检查
• 安全扫描

---

4.3 references

用于存放参考文档。

例如：

references/
├── coding-standard.md
├── api-spec.md
└── database-guide.md

Skill 在需要时会读取这些文档。

而不是一开始全部加载进上下文。

---

4.4 assets

用于存放资源文件。

例如：

assets/
├── config.json
├── template.yaml
└── prompt.txt

用于生成标准配置或代码模板。

---

五、SKILL.md 文件详解

YAML 元数据

SKILL.md 开头通常包含 YAML 配置。

---
name: code-review

description: >
  Review code based on team standards.
  Use when users ask for code review.

allowed-tools:
  - Read
  - Bash
---

---

常见字段

字段	是否必需	作用
name	✅	Skill名称
description	✅	触发条件说明
allowed-tools	❌	工具白名单
context	❌	上下文策略
agent	❌	子代理类型
license	❌	许可证

---

六、Skill 的渐进式加载机制

很多人担心：

Skill 越写越多，会不会把上下文撑爆？

答案是不会。

因为 Skill 采用了渐进式加载机制。

---

第一层：Metadata

name
description

始终存在。

大约只占几十 Token。

用于判断：

这个Skill该不该调用

---

第二层：SKILL.md

当 Skill 被触发时。

系统加载：

SKILL.md

了解执行流程。

---

第三层：资源文件

只有需要时才会加载：

references/
scripts/
assets/

这样可以节省大量上下文窗口。

---

七、5 个 Skill 编写技巧

技巧一：Description 决定一切

Skill 能否被正确触发。

核心看：

description

推荐格式：

Use when ...
to ...
by ...
while ...

例如：

description: >
  Generate technical blog posts from
  provided materials.
  Use when users ask for CSDN blog writing.

---

技巧二：先调研再编写

不要直接凭经验写 Skill。

推荐流程：

需求
↓
让AI调研最佳实践
↓
整理流程
↓
编写Skill

例如：

帮我调研Go代码审查规范
并设计一个Skill

效果通常更好。

---

技巧三：一个 Skill 只做一件事

错误示例：

code-review
+
security-audit
+
performance-check
+
test-writer

全部写进一个 Skill。

---

正确做法：

code-review

security-audit

performance-check

test-writer

分别拆开。

单一职责原则同样适用于 Skill。

---

技巧四：代码优先于文字

例如：

不推荐

检查是否存在硬编码密码

推荐

grep -rn "password\|secret\|token" src/

代码表达更精确。

AI 理解也更稳定。

---

技巧五：增加 Gotchas

这是很多人忽略的部分。

建议单独增加：

## Gotchas

- 不允许执行 rm -rf
- 不允许修改生产配置
- 不允许直接删除数据库
- 审查时不要修改代码

这些规则能显著减少 AI 误操作。

---

八、一个完整 Skill 示例

下面是一个博客生成 Skill。

---
name: write-csdn-blog

description:
根据技术素材生成CSDN博客。
用户提到博客、教程、Markdown时使用。

allowed-tools:
  - Read
---

# Workflow

1. 提取知识点
2. 构建目录
3. 生成正文
4. 输出Markdown

# Output

标准Markdown格式

这种 Skill 特别适合：

• 技术写作
• 文档生成
• 教程编写

---

九、总结

随着 Agent 技术的发展，Skill 正逐渐成为 AI 编程的重要组成部分。

简单来说：

• Prompt 解决"现在做什么"
• Skill 解决"应该怎么做"
• MCP 解决"能调用什么工具"

对于开发者来说，掌握 Skill 编写能力，相当于掌握了定制 Agent 能力的钥匙。

最后送大家一句经验总结：

Skill 不要追求大而全，一个 Skill 只解决一个问题，往往比万能 Skill 更稳定、更容易维护。

如果你正在使用 Claude Code、Cursor 或 OpenClaw，你最想封装成 Skill 的能力是什么？欢迎在评论区交流讨论。