Loading... # 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. 工作原理 ```mermaid 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. 使用官方安装命令 ```bash npm install -g @anthropic-ai/claude-code ``` ### B. 配置自定义模型（可选） 如果不想使用官方账号，可以接入其他模型。 创建配置文件 `settings.json`： ```json { "apiUrl": "https://open.bigmodel.cn/api/paas/v4/", "apiKey": "your_api_key_here", "model": "glm-4-flash" } ``` **macOS 配置路径**： ``` ~/Library/Application Support/Claude/settings.json ``` **Windows/Linux 配置路径**： ``` ~/.claude/settings.json ``` 添加跳过登录配置： ```json { "skipLogin": true } ``` ## 2. Skills 文件结构 ### A. 项目级 Skills 在项目目录下创建： ``` 项目根目录/ └── .claude/ └── skills/ ├── 字幕转md/ │ └── skill.md └── 来点选题/ └── skill.md ``` ### B. 全局 Skills 在用户配置目录创建： ``` ~/.claude/ └── skills/ └── [共享技能包] ``` ## 3. 编写第一个 Skill ### A. 创建目录和文件 ```bash mkdir -p skill-project/.claude/skills/字幕转md ``` ### B. 编写 skill.md ```markdown --- name: 字幕转md description: 当用户提供 SRT 字幕文件需要转换时使用 --- 你是一个专业的字幕文本处理助手，任务是将 SRT 字幕转换为 MD 笔记。 **重要规则**： - 禁止任何删减、总结或省略 - 必须保留所有文字 - 在关键位置插入截图占位符 ``` ### C. 验证 Skill ```bash cd skill-project claude ``` 在 Claude Code 中输入 `/skills` 可以看到所有已定义的 Skills。 ## 4. 实战测试 将 SRT 字幕文件拖入 Claude Code，系统会提示是否使用"字幕转md" Skill。 **加载过程**： 1. 初始上下文只包含元数据（name、description） 2. 用户确认使用后，才加载指令层详细内容 3. 根据需要决定是否读取资源层文件 # 四、进阶用法 ## 1. 推荐目录结构 Anthropic 官方推荐的 Skill 目录组织： ``` skill-name/ ├── skill.md # 必需：元数据和指令 ├── scripts/ # 可选：可执行脚本 │ └── process.py ├── references/ # 可选：参考文档 │ └── example.md └── assets/ # 可选：图片等资源 └── screenshot.png ``` ## 2. 资源层实战 ### A. 可执行脚本示例 在 `scripts/` 目录下放置 Python 脚本，用于视频自动截图： ```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 **后续处理**： Markdown 生成完毕后，调用 `scripts/capture_screenshot.py` 对视频进行截图。 ``` **重要**：脚本代码不会作为上下文传给 AI，只是被执行，从而最大程度降低上下文使用量。 ## 3. 参考文档资源 ### A. 场景描述 当 Skill 需要学习特定写作风格或技术规范时，可以使用 `references/` 目录。 ### B. 实例：写作助手 Skill ``` 帮我写作/ ├── skill.md └── references/ └── 写作风格范文.md ``` 在 `skill.md` 中： ```markdown 如果材料涉及 AI 或计算机相关内容： 1. 读取 `references/写作风格范文.md` 2. 学习其中的写作风格 3. 按照相同风格生成内容 ``` **调用流程**： 1. AI 判断材料是否为技术相关 2. 如果是，调用 Read 工具读取参考文档 3. 学习文风后生成内容 # 五、跨平台迁移 ## 1. Claude Code → Cursor 迁移过程非常简单： ```bash # 只需修改目录名称 .claude/skills/ → .cursor/skills/ ``` Cursor 使用相同的 Skill 格式和文件结构。 ## 2. Claude Code → OpenCode OpenCode 目前将 Skills 作为实验性功能，需要先在配置中启用： ```json // ~/.openrc/config.json { "features": { "skills": true } } ``` ## 3. 使用社区 Skills GitHub 上有大量社区贡献的 Skills，如 [cloud-skills](https://github.com/anthropics/cloud-skills) 项目（14000+ star）。 使用方法： ```bash # 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 部分**（提示词管理）： ```markdown --- name: 帮我写作并发布 description: 根据材料写作并发布到 GitHub --- **后续处理**： 1. 检查是否存在名为 `ai-docs` 的 GitHub 仓库 2. 如果不存在，使用 `create_repository` MCP 工具创建 3. 使用 `create_update_file` MCP 工具上传文件到仓库 ``` **MCP 部分**（工具调用）： - GitHub MCP Server 提供实际的 Git 操作 - 执行仓库创建、文件上传等具体任务 ### B. 协作流程 ```mermaid 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. 描述部分要明确调用时机 ```markdown --- name: 字幕转md description: 当用户提供 SRT 字幕文件需要转换为 Markdown 笔记时使用 --- ``` **好的描述**：明确场景（SRT 文件）、动作（转换）、目标（Markdown 笔记） **不好的描述**："转换字幕"（过于模糊） ### B. 使用触发词模式 在描述中包含关键词，帮助 AI 快速识别： - "当用户需要...时" - "如果涉及..." - "适用于...场景" ## 2. 指令层编写技巧 ### A. 结构化输出 ```markdown **输出格式**： 1. 使用 Markdown 标题层级 2. 代码块使用语言标识 3. 关键信息用加粗标记 ``` ### B. 明确禁止事项 ```markdown **禁止**： - 删减原始内容 - 使用英文标点 - 添加表情符号 ``` ## 3. 资源层组织建议 ### A. scripts 目录 - 保持脚本独立性（不依赖外部库） - 添加清晰的注释 - 提供错误处理 ### B. references 目录 - 使用清晰的文件命名 - 提供简短说明文档 - 控制文件大小（避免影响加载速度） # 八、常见问题 ## 1. Skill 没有被识别 ### A. 检查文件名 必须是 `skill.md`（大小写敏感） ### B. 检查目录结构 ``` .claude/skills/your-skill/skill.md ``` ### C. 重启 Agent 工具 修改 Skill 后需要重启才能生效 ## 2. 脚本执行失败 ### A. Python 环境问题 每台电脑的 Python 环境不同，脚本执行失败率较高。 **解决方案**： - 使用标准库（减少依赖） - 添加版本检查 - 提供详细的错误提示 ### B. 路径问题 使用相对路径而非绝对路径： ```python # 好的做法 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 形成互补协作关系 *** ## 参考资料 1. [Anthropic Agent Skills 官方文档](https://docs.anthropic.com/claude/docs/skills) 2. [cloud-skills GitHub 仓库](https://github.com/anthropics/cloud-skills) 3. [Claude Code 官方文档](https://docs.anthropic.com/claude-code) 最后修改：2026 年 01 月 18 日 © 允许规范转载 赞 如果觉得我的文章对你有用，请随意赞赏