diff --git a/docs/zh-cn/stage-3/core-skills/skills/index.md b/docs/zh-cn/stage-3/core-skills/skills/index.md index f74e933..08135e5 100644 --- a/docs/zh-cn/stage-3/core-skills/skills/index.md +++ b/docs/zh-cn/stage-3/core-skills/skills/index.md @@ -19,8 +19,22 @@ Skills 解决了这些问题，让 Claude 变成一个"有经验的团队成员" --- +## 为什么现在要学 Skills？ + +**Skills 正在成为 AI 工程师的必备技能**： + +- **社区热度高**：GitHub 上相关仓库星标快速增长，例如 OpenSkills 项目已收获 7.2k stars，Obsidian Skills 9 天暴涨 6.6k stars +- **官方支持**：Anthropic 官方维护 Skills 仓库，Vercel 推出 Agent Skills 和 find-skills 工具 +- **实用性强**：从代码审查、Git 操作到视频制作、PPT 生成，覆盖多种场景。skills.sh 平台已有 60K+ 订阅量的热门技能 +- **效率提升**：一次配置，反复使用，让 Claude 真正成为你的"数字员工" +- **开发者认可**：多个技术社区推荐，被广泛认为是提升 AI 编程效率的关键工具 + +--- + ## 快速开始 +理解了 Skills 的价值后，让我们马上动手体验！本节会带你安装第一个 Skill，并完成几个有趣的实战任务，快速建立起直观认识。 + ### 第一步：安装 find-skills（强烈推荐必装） 在开始使用 Skills 之前，强烈推荐先安装 `find-skills` —— 这是 AI Agent 领域的"技能搜索神器"，目前已有 60K+ 订阅量。 @@ -70,109 +84,7 @@ Claude 会通过 find-skills 搜索，然后告诉你找到了哪些相关技能 - [Skills 官网](https://skills.sh/) - 浏览所有可用技能 - [find-skills 仓库](https://github.com/vercel-labs/agent-skills) - 官方源码 ---- - -### 5 分钟上手 Skills（使用官方有趣 Skills 测试） - -让我们通过官方提供的 Skills 来快速体验 Skills 的强大功能。 - -#### 测试 1：skill-creator（创建技能的技能） - -**安装官方 Skills 仓库**： - -```bash -/plugin marketplace add anthropics/skills -``` - -或者直接克隆： - -```bash -git clone https://github.com/anthropics/skills.git ~/.claude/skills/official -``` - -**体验 skill-creator**： - -在 Claude Code 中输入： - -``` -/skill-creator - -我想创建一个技能，功能是自动格式化 JavaScript 代码。 -``` - -Claude 会引导你： -1. 明确技能用途和场景 -2. 生成 SKILL.md 草稿 -3. 创建测试用例 -4. 运行评估并优化 - -**预期效果**：你不需要手动写任何文件，Claude 会帮你完成整个创建流程。 - -#### 测试 2：slack-gif-creator（创建 Slack GIF） - -**体验创作技能**： - -``` -/slack-gif-creator - -帮我创建一个 128x128 的 GIF： -- 蓝色背景渐变 -- 一个白色星星从左飞到右边 -- 同时带一点旋转效果 -``` - -Claude 会： -1. 分析需求 -2. 生成 Python 代码（使用 PIL） -3. 创建动画 -4. 优化文件大小 - -**预期效果**：一个可用的 GIF 文件，符合 Slack 规范。 - -#### 测试 3：mcp-builder（构建 MCP 服务器） - -**体验 MCP 开发技能**： - -``` -/mcp-builder - -我想创建一个 MCP 服务器来连接我的 Notion workspace。 -``` - -Claude 会： -1. 引导你完成需求分析 -2. 生成 MCP 服务器代码（Python 或 TypeScript） -3. 配置工具和资源 -4. 提供测试方法 - -**预期效果**：一个可运行的 MCP 服务器代码。 - -#### 查看所有可用 Skills - -``` -/skills -``` - -或 - -``` -你有哪些技能？ -``` - -### 理解 Skills 的价值 - -通过这三个测试，你可以看到 Skills 的核心价值： - -1. **技能组合**：不同技能解决不同问题，可以灵活组合 -2. **AI 协作**：让 Claude 引导你完成复杂任务 -3. **可复用性**：创建一次，反复使用 -4. **可共享**：团队成员都可以使用相同的 Skills - -接下来，我们会深入探讨 Skills 的各个方面。 - ---- - -### 实战：用 find-skills 安装并体验第一个 Skill +### 安装并体验第一个 Skill 安装 find-skills 后，让我们用它来搜索并安装第一个好玩 的 Skill —— Remotion 视频制作工具。 @@ -1101,13 +1013,286 @@ description: 审查 Pull Request 的代码。当用户提到 PR、review、代 - [Vibe Coding - CLAUDE.md、Skills、Subagents 全链路实战](https://blog.csdn.net/yangshangwei/article/details/158319117) - [手把手教你自定义 Claude Code Skills](https://m.blog.csdn.net/u010028049/article/details/157979705) -### 深入阅读 +## 深入阅读：Claude Skills 的内部机制 -- [Claude Skills 内部核心机制](/easy-vibe/zh-cn/appendix/8-artificial-intelligence/skills-internal-mechanism) - 深入理解 Skills 的工作原理、三层加载架构、双上下文注入机制 +接下来我们将深入理解 Claude Skills 的工作原理，让你不仅会用，更懂得为什么这样设计。 + +### 第一性原理：基于提示词的动态上下文注入 + +首先，要理解一个关键事实：**Skills 不是可执行代码**。 + +Skills 本质上是高级指令（Prompt），在需要时被"植入"到 Claude 的上下文中。这种设计被称为"**Prompt-based Dynamic Context Injection & Meta-Tool Architecture**"（基于提示词的动态上下文注入与元工具架构）。 + +``` +┌─────────────┐ ┌─────────────┐ ┌──────────────┐ +│ 用户请求 │ ───> │ LLM 匹配 │ ───> │ 触发 Skill │ +└─────────────┘ │ Skill 描述 │ └──────────────┘ + └─────────────┘ │ + ▼ + ┌──────────────┐ + │ 注入完整 │ + │ 指令内容 │ + └──────────────┘ + │ + ▼ + ┌──────────────┐ + │ 执行任务 │ + └──────────────┘ +``` + +### 三层渐进式加载架构（Token 优化） + +为了处理大量 Skills 而不消耗过多 Token，Claude 采用了一种聪明的三层加载机制： + +| 层级 | 内容 | 加载时机 | Token 消耗 | +|------|------|----------|-----------| +| **Layer 1: 元数据** | YAML frontmatter（name + description） | Claude 启动时 | ~30-50 tokens/skill | +| **Layer 2: 指令** | 完整 SKILL.md 内容 | Skill 被触发时 | ~5,000 tokens | +| **Layer 3: 资源** | 脚本、模板、参考文档 | 按需通过文件系统访问 | 不占上下文 | + +**这个设计的优势**： + +- 假设你有 100 个 Skills，启动时只消耗约 3,000-5,000 tokens（元数据） +- 只有被触发的 Skill 才会加载完整内容 +- 参考文档等资源文件永远不会被完整加载到上下文 + +**对比无 Skills 的情况**： + +``` +无 Skills：每次对话需要 50,000+ tokens 来描述所有能力 +有 Skills：启动 ~100 tokens/skill + 5,000 tokens 按需加载 +节省：平均每轮对话节省 40,000+ tokens +``` + +### 双上下文注入机制 + +当 Skill 被激活时，系统会同时进行两次修改： + +**1. 对话上下文注入** + +```javascript +// 用户看到的（可见消息） +The "pdf" skill is loading + +// AI 实际收到的（隐藏元消息） +{ + isMeta: true, // 标记为元消息，用户界面不显示 + content: ` + # PDF 分析专家指令 + + 你是一位专业的 PDF 分析专家。工作流程： + 1. 使用 pdftotext 提取文本 + 2. 分析文档结构 + 3. 生成摘要报告 + ... + ` // 完整的 SKILL.md 内容，可能数千字 +} +``` + +**2. 执行上下文修改** + +除了注入指令，Skill 还能动态修改 Claude 的环境： + +| 修改类型 | 示例 | 说明 | +|---------|------|------| +| **工具权限** | `allowed-tools: "Bash(pdftotext:*)"` | 临时授予特定工具访问权限 | +| **模型切换** | 从 Sonnet 切换到 Opus | 某些复杂任务需要更强推理能力 | +| **上下文隔离** | 创建子会话空间 | 避免污染主对话上下文 | + +### 纯 LLM 推理的路由机制 + +这是一个非常重要的设计决策：**Claude Skills 没有硬编码路由**。 + +| 传统方法 | Claude Skills | +|---------|--------------| +| ❌ 嵌入向量匹配 | ✅ 纯 LLM 推理 | +| ❌ 分类器 | ✅ Transformer 前向传播 | +| ❌ 正则/关键词匹配 | ✅ 自然语言理解 | +| ❌ 单独的路由算法 | ✅ 统一的模型决策 | + +**工作流程**： + +``` +1. 所有 Skill 的 name 和 description 被格式化到 Skill 工具的描述中 + +2. Claude 收到： + - 用户消息 + - 可用工具列表（包括 Skill meta-tool） + - Skill 列表（name + description） + +3. Claude 的自然语言理解能力将用户意图匹配到 Skill description + +4. 匹配成功时调用：command: "skill-name" +``` + +**为什么这样设计？** + +**硬编码路由需要**： +- 额外的维护成本 +- 无法理解复杂的语义关系 +- 难以处理多语言 +- 不支持模糊匹配 + +**纯 LLM 推理**： +- 利用 Claude 本身的语言理解能力 +- 自动处理多语言、同义词、模糊描述 +- 无需额外维护 +- 路由决策更智能 + +### 文件解析机制 + +**SKILL.md 文件结构**： + +```bash +my-custom-skill/ +├── SKILL.md # 必需：核心定义文件 +├── config.json # 可选：元数据配置 +├── README.md # 推荐：使用文档 +├── scripts/ # 可选：可执行脚本 +├── templates/ # 可选：模板文件夹 +└── references/ # 可选：参考文档 +``` + +**解析流程**： + +``` +┌─────────────────────────────────────────────────────────────┐ +│ Claude Code 启动 │ +└─────────────────────────────────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────────────────┐ +│ 扫描 ~/.claude/skills/ 和 .claude/skills/ 目录 │ +└─────────────────────────────────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────────────────┐ +│ 使用 gray-matter 库解析每个 SKILL.md 的 YAML frontmatter │ +└─────────────────────────────────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────────────────┐ +│ 验证必需字段（name 和 description） │ +│ - name: 最大 64 字符，只能用小写字母、数字、连字符 │ +│ - description: 用于 LLM 自动匹配 │ +└─────────────────────────────────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────────────────┐ +│ 提取元数据，构建 Skill 列表 │ +│ （只加载 name + description，不加载正文） │ +└─────────────────────────────────────────────────────────────┘ +``` + +### 完整执行流程示例 + +让我们通过一个具体的例子来看整个流程： + +``` +用户："帮我分析这个 PDF 文件" + +═══════════════════════════════════════════════════════════════ + +Step 1: LLM 决策 +──────────────── +Claude 在 Skill 列表中找到 "pdf" skill 的描述： + description: "分析 PDF 文档内容、提取文本、生成摘要" + +═══════════════════════════════════════════════════════════════ + +Step 2: 系统介入 +──────────────── +Claude Code 执行： + 1. 读取 ~/.claude/skills/pdf/SKILL.md + 2. 生成可见消息："The pdf skill is loading" + 3. 生成隐藏元消息：完整的 SKILL.md 内容 + 4. 修改会话权限：allowed-tools = ["Bash(pdftotext:*)"] + +═══════════════════════════════════════════════════════════════ + +Step 3: LLM 执行 +──────────────── +现在 Claude 的上下文包含： + - 原始用户请求 + - PDF 专家的工作流程指令 + - pdftotext 工具的访问权限 + +Claude 执行： + 1. 使用 pdftotext 提取 PDF 文本 + 2. 分析内容结构 + 3. 生成摘要报告 + 4. 向用户展示结果 + +═══════════════════════════════════════════════════════════════ + +Step 4: 用完即弃 +──────────────── +任务完成后，Skill 的完整内容从上下文中移除 +（只保留对话历史，不保留完整的 Skill 指令） +``` + +### 核心设计创新 + +| 创新点 | 传统方法 | Skills 方法 | 优势 | +|--------|---------|------------|------| +| **能力来源** | 固化在模型权重中 | 动态加载的提示词 | 可扩展、可更新 | +| **Token 效率** | 所有能力常驻内存 | 按需加载 | 节省 80%+ tokens | +| **知识管理** | 分散在对话历史中 | 模块化的文件系统 | 可版本控制、可共享 | +| **生命周期** | 持续占用 | 用完即弃 | 上下文更清爽 | + +### 学术基础 + +Claude Skills 的设计理念源于以下研究： + +| 研究领域 | 代表工作 | 应用体现 | +|---------|---------|---------| +| **强化学习** | Voyager (2023) | 积累技能库的概念 | +| **认知架构** | ACT-R、Soar | 程序性记忆与陈述性记忆分离 | +| **分层策略** | Options Framework | 三层渐进式加载 | + +**核心思想转变**： + +``` +传统：AI 需要记住一切 + ↓ +Skills：AI 知道"去哪里找专业知识" + ↓ +结果：更像人类专家的思维方式 +``` + +### 与 Agent Skills 标准的关系 + +Claude Skills 遵循 [Agent Skills 开放标准](https://agentskills.io/)，这意味着： + +- ✅ 跨平台兼容：Cursor、Windsurf、Aider 等工具都支持 +- ✅ 统一的文件格式：SKILL.md 结构标准 +- ✅ 可互操作：不同工具间可以共享 Skills + +``` +Agent Skills 标准定义： +├── 必需：SKILL.md 文件（metadata + instructions） +├── 可选：scripts/（可执行代码） +├── 可选：references/（知识库文档） +└── 可选：assets/（模板和资源） +``` + +### 总结：为什么这个设计是天才的？ + +1. **解耦能力与模型**：专业知识不再依赖模型训练，可以通过 Markdown 文件随时更新 + +2. **极致的 Token 效率**：三层加载机制确保只加载需要的内容 + +3. **利用 LLM 自身能力**：路由匹配完全依靠 Claude 的语言理解，无需额外算法 + +4. **开发者友好**：创建 Skill 只需要写 Markdown，不需要编程 + +5. **可组合性**：Skills 可以互相引用、组合，形成复杂的工作流 + +6. **用完即弃**：任务完成后自动清理，保持上下文清爽 --- -## 总结 +### 总结 Skills 是让 Claude Code 从"通用助手"变成"团队专家"的关键。