Claude Code Skill 开发实战：从入门到精通的完整指南

米小虾
3 阅读6分钟

Skill 是 Claude Code 的灵魂。掌握 Skill 开发，就是掌握 AI 编程的终极武器。

一、Skill 是什么？为什么它如此重要？

在 Claude Code 的世界里，Skill 不仅仅是提示词模板，它是Prompt 编译器、领域知识封装器、工作流编排器的三位一体。

1.1 Skill 的本质

Skill 的核心定位是：将复杂任务打包成可直接使用的技能包。

与简单的 Prompt 不同，Skill 具有以下特征：

  • 结构化：使用 YAML frontmatter 定义元数据
  • 可复用：一次编写，多处调用
  • 可组合：多个 Skill 可以协同工作
  • 可进化：支持版本迭代和能力扩展

1.2 Skill vs MCP vs 传统 Prompt

维度SkillMCP传统 Prompt
定位Prompt编译器外部工具连接器单次指令
复用性高中低
上下文管理按需加载实时调用全量携带
适用场景领域知识封装外部能力扩展简单任务

关键洞察：Skill 解决的是"如何把专家知识固化到 AI 工作流中"，而 MCP 解决的是"如何让 AI 调用外部工具"。

二、Skill 的底层架构

2.1 三层系统架构

Claude Code 的 Skill 系统采用三层架构：

声明层（SKILL.md）

---
name: frontend-design
description: 打造高设计质量的前端界面
model: claude-sonnet-4-5
allowed-tools: [read, edit, bash, browser]
---

编译层（getPromptForCommand）

  • 解析 frontmatter
  • 编译正文内容
  • 生成可执行指令

运行时层（Command 闭包）

  • 捕获上下文
  • 按需加载内容
  • 执行并返回结果

2.2 延迟加载机制

Skill 的延迟加载设计是其性能优势的核心：

启动阶段：只解析 frontmatter（name/description/model/allowed-tools）
调用阶段：才编译正文内容

这意味着：

  • 启动时加载 100 个 Skill 和加载 10 个 Skill 的时间几乎相同
  • 只有实际调用的 Skill 才会消耗 token
  • 按需加载避免了上下文爆炸

三、Skill 开发实战

3.1 最小可用 Skill

创建一个 Skill 只需要三步：

Step 1：创建文件

mkdir -p .claude/skills
 touch .claude/skills/my-skill.md

Step 2：编写内容

---
name: code-review
description: 代码审查专家，专注于发现潜在问题
---

你是一位经验丰富的代码审查专家。请对提供的代码进行以下检查：

1. **安全性**：是否存在 SQL 注入、XSS 等安全漏洞
2. **性能**：是否有明显的性能瓶颈
3. **可维护性**：代码是否清晰、是否有适当的注释
4. **最佳实践**：是否符合语言/框架的惯用法

输出格式：
- 🔴 严重问题（必须修复）
- 🟡 警告（建议修复）
- 🟢 建议（可选优化）

Step 3：安装 Skill

# 本地 Skill 自动识别
# 第三方 Skill 安装
npx skills add vercel-labs/agent-skills

3.2 Skill 的高级特性

Hooks 机制

Hooks 允许你在 Skill 生命周期的关键点插入自定义逻辑：

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/protect-files.sh"
          }
        ]
      }
    ]
  }
}

常见 Hook 类型：

  • SessionStart：会话开始时执行
  • SessionEnd：会话结束时执行
  • PreToolUse：工具使用前执行
  • PostToolUse：工具使用后执行

SubAgents

SubAgents 是独立的子代理，拥有单独的上下文环境：

# 查看当前 sub agents
/agents

# 创建新的 sub agent
# 会在 .claude/agents/ 目录下创建 md 文件

使用场景：

  • 代码审查（独立审查，不影响主流程）
  • 单元测试生成（并行执行）
  • Bug 排查（隔离环境）

3.3 Skill 的最佳实践

控制 SKILL.md 大小

# ❌ 错误示范：200+ 行的 SKILL.md
# 会导致 AI 忽略关键信息

# ✅ 正确做法：控制在 200 行以内
# 复杂逻辑拆分为多个 Skill

按需加载设计

---
name: complex-task
description: 复杂任务处理
---

## 阶段一：需求分析
（详细说明...）

## 阶段二：方案设计
（详细说明...）

## 阶段三：编码实现
（详细说明...）

## 阶段四：测试验证
（详细说明...）

使用 /compact 命令压缩上下文，保留关键信息。

四、Skill 生态与资源

4.1 推荐 Skill 源

官方/高质量 Skill

  • vercel-labs/agent-skills：React/前端最佳实践
  • anthropic-coding：官方编码 Skill

社区 Skill

  • humanizer：去除 AI 生成文本痕迹
  • code-review：代码审查专家

4.2 Skill 开发工具

调试技巧

# 查看当前 context 使用情况
/context

# 查看 token 消耗
/cost

# 压缩上下文
/compact

# 清空对话（新任务必用）
/clear

五、从 Skill 到 Agent：进阶之路

5.1 Skill 组合模式

单个 Skill 解决单点问题，组合 Skill 解决复杂场景：

需求分析 Skill → 架构设计 Skill → 编码实现 Skill → 测试验证 Skill

5.2 Agent 的定义

当 Skill 具备以下特征时，它就进化为 Agent：

  • 自主性：能自主决策下一步行动
  • 记忆性：能跨会话保持状态
  • 工具使用：能调用 MCP 等外部工具
  • 反思能力：能评估自己的输出质量

5.3 Claude Code 的 Agent 能力

Claude Code 通过以下机制支持 Agent 行为：

  • Plan Mode：shift+tab 切换，先规划后执行
  • SubAgents：独立环境，并行任务
  • MCP：外部工具集成
  • Hooks：生命周期控制

六、实战案例：开发一个完整的 Skill

6.1 需求分析

目标：开发一个"API 设计审查"Skill

功能：

  • 检查 RESTful API 设计规范
  • 识别常见设计陷阱
  • 提供改进建议

6.2 Skill 实现

---
name: api-design-review
description: API 设计审查专家，检查 RESTful API 规范
allowed-tools: [read, edit]
---

你是一位 API 设计专家。请审查提供的 API 设计，检查以下方面：

## 1. URL 设计
- [ ] 是否使用名词而非动词
- [ ] 是否使用复数形式
- [ ] 层级关系是否清晰

## 2. HTTP 方法
- [ ] GET 是否只用于获取资源
- [ ] POST 是否用于创建资源
- [ ] PUT/PATCH 是否用于更新
- [ ] DELETE 是否用于删除

## 3. 状态码
- [ ] 2xx 表示成功
- [ ] 4xx 表示客户端错误
- [ ] 5xx 表示服务端错误

## 4. 响应格式
- [ ] 是否统一包装
- [ ] 错误信息是否清晰
- [ ] 是否包含分页信息（列表接口）

输出格式：

✅ 符合规范 ❌ 问题：{具体描述} 💡 建议：{改进方案}

6.3 测试与迭代

# 安装 Skill
# 自动识别 .claude/skills/ 目录

# 测试
@api-design-review
请审查以下 API 设计：
GET /getUserInfo?id=123

七、总结与展望

Skill 是 Claude Code 生态的核心，掌握 Skill 开发意味着：

  • 效率提升：一次编写，永久复用
  • 质量保障：固化最佳实践
  • 知识沉淀：团队协作的标准化

未来趋势：

  • Skill 市场：类似 VS Code 插件生态
  • AI 生成 Skill：用 AI 辅助编写 Skill
  • 跨平台兼容：AGENTS.md 等开放标准

参考资源

文章字数：约3200字 发布时间：2026年4月19日

avatar
文章
阅读
粉丝