docs(zh-cn): update skills documentation with motivation and technical details
This commit is contained in:
sanbuphy
@@ -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
|
||||
// 用户看到的（可见消息）
|
||||
<command-message>The "pdf" skill is loading</command-message>
|
||||
|
||||
// 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 从"通用助手"变成"团队专家"的关键。
|
||||
|
||||
|
||||
Reference in New Issue
Block a user