Agent Skills 完全指南：从原理到实战
一、概述
1. 简介
A. 是什么
Agent Skills 是一种为 AI Agent 提供结构化能力描述的开放标准，于 2025 年 12 月 18 日由 Anthropic 正式发布。它通过渐进式披露提示词的机制，大幅降低 token 消耗与提示词复杂度。
B. 为什么学
- 解决传统提示词臃肿、上下文占用过高的问题
- 实现跨平台能力复用，一次编写处处可用
- 已获得 Claude Code、Cursor、OpenCode 等主流 AI 编程工具支持
C. 学完能做什么
- 为 Claude Code 等 Agent 工具编写自定义 Skills
- 理解 Skills 与 MCP 的协作模式
- 优化 AI 工作流，降低 token 成本
2. 前置知识
A. 必备技能
- 基本命令行操作
- Markdown 语法基础
- 了解 AI Agent 基本概念
B. 推荐知识
- 了解 MCP（Model Context Protocol）
- 使用过 Claude Code 或类似工具
二、核心概念
1. Skills 的本质
Agent Skills 是一种带目录的说明书机制，采用渐进式披露提示词的设计模式。其核心思想是将提示词分为三层，按需加载。
2. 三层结构
A. 元数据层
- 加载方式：必定加载到 AI 上下文
- 内容：技能名称、描述、调用时机
- 类比：书籍的目录
B. 指令层
- 加载方式：按需加载（AI 选择使用该 Skill 时）
- 内容：详细的操作指令、格式要求
- 类比：书籍的正文
C. 资源层
- 加载方式：按需加载（AI 根据指令需要时）
- 内容：可执行脚本、参考文档、图片等
- 类比：书籍的附录
3. 工作原理
graph TB
User[用户提问] --> Agent[Agent 工具]
Agent --> Scan[扫描所有 skill.md]
Scan --> Extract[提取元数据]
Extract --> List[可用技能列表]
List --> LLM[AI 大模型]
LLM -->|判断| Decision{需要 Skill?}
Decision -->|否| Direct[直接回答]
Decision -->|是| Select[选择 Skill]
Select --> Load[加载指令层]
Load --> Check{需要资源?}
Check -->|是| Resource[加载资源层]
Check -->|否| Generate
Resource --> Generate[生成回答]
Direct --> Response[返回用户]
Generate --> Response
核心优势：元数据层通常只有几十个 token，而完整的提示词可能上千 token。只有 AI 确认需要时才加载完整内容，从而大幅降低上下文消耗。
三、Claude Code 快速入门
1. 安装 Claude Code
A. 使用官方安装命令
npm install -g @anthropic-ai/claude-codeB. 配置自定义模型（可选）
如果不想使用官方账号，可以接入其他模型。
创建配置文件 settings.json：
{
"apiUrl": "https://open.bigmodel.cn/api/paas/v4/",
"apiKey": "your_api_key_here",
"model": "glm-4-flash"
}macOS 配置路径：
~/Library/Application Support/Claude/settings.jsonWindows/Linux 配置路径：
~/.claude/settings.json添加跳过登录配置：
{
"skipLogin": true
}2. Skills 文件结构
A. 项目级 Skills
在项目目录下创建：
项目根目录/
└── .claude/
└── skills/
├── 字幕转md/
│ └── skill.md
└── 来点选题/
└── skill.mdB. 全局 Skills
在用户配置目录创建：
~/.claude/
└── skills/
└── [共享技能包]3. 编写第一个 Skill
A. 创建目录和文件
mkdir -p skill-project/.claude/skills/字幕转mdB. 编写 skill.md
---
name: 字幕转md
description: 当用户提供 SRT 字幕文件需要转换时使用
---
你是一个专业的字幕文本处理助手，任务是将 SRT 字幕转换为 MD 笔记。
**重要规则**：
- 禁止任何删减、总结或省略
- 必须保留所有文字
- 在关键位置插入截图占位符C. 验证 Skill
cd skill-project
claude在 Claude Code 中输入 /skills 可以看到所有已定义的 Skills。
4. 实战测试
将 SRT 字幕文件拖入 Claude Code，系统会提示是否使用"字幕转md" Skill。
加载过程：
- 初始上下文只包含元数据（name、description）
- 用户确认使用后，才加载指令层详细内容
- 根据需要决定是否读取资源层文件
四、进阶用法
1. 推荐目录结构
Anthropic 官方推荐的 Skill 目录组织：
skill-name/
├── skill.md # 必需：元数据和指令
├── scripts/ # 可选：可执行脚本
│ └── process.py
├── references/ # 可选：参考文档
│ └── example.md
└── assets/ # 可选：图片等资源
└── screenshot.png2. 资源层实战
A. 可执行脚本示例
在 scripts/ 目录下放置 Python 脚本，用于视频自动截图：
# scripts/capture_screenshot.py
import sys
from moviepy.editor import VideoFileClip
def capture_frames(video_path, timestamps):
clip = VideoFileClip(video_path)
for i, ts in enumerate(timestamps):
frame = clip.get_frame(ts)
# 保存截图并替换 MD 文件中的占位符
# ...B. 在 Skill 中调用脚本
在 skill.md 的指令层添加：
**后续处理**：
Markdown 生成完毕后，调用 `scripts/capture_screenshot.py` 对视频进行截图。重要：脚本代码不会作为上下文传给 AI，只是被执行，从而最大程度降低上下文使用量。
3. 参考文档资源
A. 场景描述
当 Skill 需要学习特定写作风格或技术规范时，可以使用 references/ 目录。
B. 实例：写作助手 Skill
帮我写作/
├── skill.md
└── references/
└── 写作风格范文.md在 skill.md 中：
如果材料涉及 AI 或计算机相关内容：
1. 读取 `references/写作风格范文.md`
2. 学习其中的写作风格
3. 按照相同风格生成内容调用流程：
- AI 判断材料是否为技术相关
- 如果是，调用 Read 工具读取参考文档
- 学习文风后生成内容
五、跨平台迁移
1. Claude Code → Cursor
迁移过程非常简单：
# 只需修改目录名称
.claude/skills/ → .cursor/skills/Cursor 使用相同的 Skill 格式和文件结构。
2. Claude Code → OpenCode
OpenCode 目前将 Skills 作为实验性功能，需要先在配置中启用：
// ~/.openrc/config.json
{
"features": {
"skills": true
}
}3. 使用社区 Skills
GitHub 上有大量社区贡献的 Skills，如 cloud-skills 项目（14000+ star）。
使用方法：
# 1. 克隆仓库
git clone https://github.com/anthropics/cloud-skills.git
# 2. 复制需要的 Skill
cp -r cloud-skills/域名头脑风暴 ~/.claude/skills/
# 3. 重启 Claude Code六、Skills 与 MCP 对比
1. 核心区别
| 维度 | Skills | MCP |
|---|---|---|
| 重点 | 提示词管理 | 工具调用 |
| 机制 | 渐进式披露 | 一次性加载 |
| 类比 | 带目录的说明书 | 标准化工具箱 |
| Token 消耗 | 较低 | 较高 |
| 主体 | Markdown 文本 | Node.js/Python 软件包 |
| 编写难度 | 简单（一个 MD 文件） | 较高（需搭建开发环境） |
| 执行成功率 | 依赖本地环境 | 较高（独立进程） |
2. 协作模式
Skills 与 MCP 可以互补配合：
- Skills：负责提示词的渐进式披露
- MCP：负责具体的工具调用（如 API 请求、文件操作）
A. 实战案例：自动发布到 GitHub
Skill 部分（提示词管理）：
---
name: 帮我写作并发布
description: 根据材料写作并发布到 GitHub
---
**后续处理**：
1. 检查是否存在名为 `ai-docs` 的 GitHub 仓库
2. 如果不存在，使用 `create_repository` MCP 工具创建
3. 使用 `create_update_file` MCP 工具上传文件到仓库MCP 部分（工具调用）：
- GitHub MCP Server 提供实际的 Git 操作
- 执行仓库创建、文件上传等具体任务
B. 协作流程
sequenceDiagram
participant U as 用户
participant CC as Claude Code
participant AI as AI 模型
participant S as Skill
participant M as MCP Server
participant G as GitHub
U->>CC: 提供写作材料
CC->>AI: 元数据 + 用户问题
AI->>S: 选择使用 Skill
S->>AI: 返回指令层
AI->>AI: 生成文案
AI->>M: 调用 create_repository
M->>G: 创建仓库
G-->>M: 返回仓库信息
M-->>AI: 创建成功
AI->>M: 调用 create_update_file
M->>G: 上传文件
G-->>M: 上传成功
M-->>AI: 返回文件 URL
AI-->>CC: 任务完成
CC-->>U: 返回 GitHub 链接
七、最佳实践
1. 元数据编写技巧
A. 描述部分要明确调用时机
---
name: 字幕转md
description: 当用户提供 SRT 字幕文件需要转换为 Markdown 笔记时使用
---好的描述：明确场景（SRT 文件）、动作（转换）、目标（Markdown 笔记）
不好的描述："转换字幕"（过于模糊）
B. 使用触发词模式
在描述中包含关键词，帮助 AI 快速识别：
- "当用户需要...时"
- "如果涉及..."
- "适用于...场景"
2. 指令层编写技巧
A. 结构化输出
**输出格式**：
1. 使用 Markdown 标题层级
2. 代码块使用语言标识
3. 关键信息用加粗标记B. 明确禁止事项
**禁止**：
- 删减原始内容
- 使用英文标点
- 添加表情符号3. 资源层组织建议
A. scripts 目录
- 保持脚本独立性（不依赖外部库）
- 添加清晰的注释
- 提供错误处理
B. references 目录
- 使用清晰的文件命名
- 提供简短说明文档
- 控制文件大小（避免影响加载速度）
八、常见问题
1. Skill 没有被识别
A. 检查文件名
必须是 skill.md（大小写敏感）
B. 检查目录结构
.claude/skills/your-skill/skill.mdC. 重启 Agent 工具
修改 Skill 后需要重启才能生效
2. 脚本执行失败
A. Python 环境问题
每台电脑的 Python 环境不同，脚本执行失败率较高。
解决方案：
- 使用标准库（减少依赖）
- 添加版本检查
- 提供详细的错误提示
B. 路径问题
使用相对路径而非绝对路径：
# 好的做法
script_dir = Path(__file__).parent
config_file = script_dir / "config.json"
# 不好的做法
config_file = "/home/user/.claude/config.json"3. Token 消耗依然很高
A. 检查资源加载
确认参考文档是否过大，考虑拆分或精简。
B. 优化指令层
删除冗余描述，保留核心指令。
九、未来展望
1. MCP 2.0 可能的方向
如果 MCP 能吸收 Skills 的优势：
- 渐进式披露提示词机制
- 简单的 Markdown 编写方式
将可能成为更完美的解决方案。
2. 生态发展趋势
- 更多 Agent 工具原生支持 Skills
- 社区贡献更多高质量 Skills
- 与 MCP 形成互补协作关系