Claude Code Skill 设计机制深度分析

最近我们对 claude code 的 skills 能力做了一些深度调研，并开发了一个在 claude 里调用 nano-banana-pro 生成图片的 skill（类似工作流），并提供 slash command 封装。

我们的nano-banana-pro生图skill支持图片打开和ascii渲染两种模式

在这个过程中我们发现，基于 skill 的单元开发模式（然后对外暴露 skill 接口、command 接口、被 Agent 调用等）可能是一种最佳实践。

基于这些发现，我们很希望通过几篇文章将这个理念进一步推广，以下是本期的第二篇文章：Claude Code Skill 设计机制深度分析。在这之前，我们还做过一次技术沙龙，欢迎移步阅读：十问 Agent Skills：一场围绕 AI 编码新范式的深度研讨。

以及这是我们整理的一些权威内容，希望对你的入门学习有所帮助：

• Introducing Agent Skills | Claude^[1]
• Agent Skills 官方文档^[2]
• Plugins 文档^[3]
• Slash Commands 文档^[4]
• Anthropic 工程博客：Equipping agents for the real world with Agent Skills^[5]
• claude-code-docs/docs/skills.md^[6]

一、
核心设计理念

1.1 定位：模型自主调用的能力扩展

Skill 的核心设计理念是 model-invoked（模型自主调用），与 Slash Commands 的 user-invoked（用户显式调用）形成鲜明对比：

这种设计反映了一个核心观点：Claude 应该像专家一样自主识别何时需要特定领域知识，而非被动等待用户指定工具。

1.2 设计哲学：Progressive Disclosure（渐进式披露）

Skill 采用三层加载系统管理上下文：

*脚本可以直接执行而无需读入上下文窗口

这种设计解决了 LLM 的核心限制：上下文窗口有限。通过分层加载，避免了将所有可能需要的知识预先塞入 prompt。

二、
架构解析

2.1 Skill 目录结构

2.2 发现机制（Discovery）

Skill 从三个位置被发现：

发现算法的核心是 description 字段的语义匹配：

2.3 allowed-tools 权限控制

这个字段实现了 最小权限原则：

• 当 Skill 激活时，Claude 只能使用指定工具
• 未指定则遵循标准权限模型（需用户确认）
• 用于创建"只读"或"受限"能力

三、
与其他扩展机制的关系

3.1 完整的扩展体系

3.2 Skill vs Slash Command 详细对比

四、
设计模式分析

4.1 "Onboarding Guide" 模式

Skill 本质上是给另一个 Claude 实例的"入职指南"：

这解释了为什么 SKILL.md 的写作风格强调：

• 祈使句/动词形式（而非第二人称）
• 包含 Claude 本身不会自然知道的程序性知识
• 提供具体例子和错误恢复策略

4.2 资源分类策略

决策树：

• 代码会被重复编写？→ scripts/
• 信息需要被参考？→ references/
• 文件用于输出？→ assets/

4.3 实际案例剖析

以官方 pdf skill 为例：

设计要点：

1. description 包含动作词（extracting, creating, merging, filling）
2. 明确触发条件（"When Claude needs to..."）
3. SKILL.md 只包含核心指令，详细内容在 reference.md 和 forms.md
4. 提供代码模板而非完整实现

五、
系统集成机制

5.1 在 System Prompt 中的呈现

Skill 被暴露为一个可调用的工具，Claude 通过 skill: "skill-name" 来激活：

5.2 激活流程

六、
最佳实践与陷阱

6.1 Description 写作原则

关键要素：

• 具体的动作（analyze, extract, generate）
• 明确的对象（Excel files, CRM exports）
• 触发场景（"Use when...", "Use for..."）

6.2 避免的问题

6.3 SKILL.md 长度控制

七、
与 
Plugin 
系统的整合

7.1 分发机制

7.2 Plugin 中的 Skill 结构

八、
设计局限与改进空间

8.1 当前局限

1. 语义匹配不透明：用户无法知道 Claude 为何选择/未选择某个 Skill
2. 无版本依赖管理：Skill 之间无法声明依赖关系
3. 无运行时参数：不像 MCP 工具可以传递参数
4. 调试困难：需要 claude --debug 查看加载错误

8.2 潜在改进方向

• 显式触发选项：允许用户强制使用某 Skill
• Skill 组合：声明式的 Skill 编排
• 条件激活：基于文件类型、项目类型的自动激活
• 监控面板：可视化 Skill 使用频率和效果

九、
总结

Claude Code 的 Skill 机制体现了一个核心设计理念：

将 AI Agent 的能力扩展从"工具调用"提升到"专业知识注入"

它不仅仅是给 Claude 更多工具，而是给它特定领域的程序性知识和决策框架。这种设计使得：

1. 用户体验更自然：无需记忆命令，自然语言即可触发
2. 知识可复用：团队专业知识被编码和共享
3. 上下文高效：按需加载，避免 prompt 膨胀
4. 权限可控：allowed-tools 实现最小权限

Skill 系统是 Claude Code 从"AI 助手"向"AI 专家团队"演进的关键基础设施。