当前位置：首页 » AI编程开发

新手入门：深入浅出 Agent Skills 底层原理全解析（附实战案例）

2小时前 AI编程开发 55 0

OpenClaw 近期大热，但很多人连 Skill 的门槛都还没迈进去。

可偏偏，Skill 才是 OpenClaw 的地基。

你可能以为 Claude 的 Skill 系统背后是复杂算法与精密工程？

这正是最大的误解：没有神秘架构，没有花哨代码。

它的关键，几乎完全建立在“阅读理解”之上。

我把 Claude Agent Skills 源码从头到尾过了一遍。

所谓“技能”，本质就是一个 Markdown 文件。

不需要 Python，不需要 JavaScript，不需要服务器。

一个目录配上一段精心设计的提示词，就足够成体系。

接下来，我就用一篇文章深入浅出的拆解 Skill 的所有核心环节：从技能的发现机制，到 SKILL.md 的写作规则，再到技能如何被选择、展开与执行，以及如何打造高质量的可复用技能。

每一步都结合源码与实战案例，帮助你不仅会用，还能看懂它为什么这样设计。

Skills 到底是什么？

先建立全景认知：Skill 是什么、不是什么、如何运转。

Skill 是提升 Claude 在特定任务上表现的“提示词资产”。每个技能就是一个目录，内含指令、脚本与资源。
当需要时，这些内容会被加载到对话与执行环境中，改变 Claude 的行为与权限。
技能的发现与调用，依赖“声明式、基于提示词”的系统：把所有技能的名称与描述汇总为清单，引导 Claude 自主选择。
源码层面，不存在额外的算法来替你“路由”技能：没有词向量、没有分类器。所有决策发生在模型自身的推理里。

技能不是什么？

不是可执行程序：不会直接跑 Python/JavaScript，也没有背后服务或函数调用。
不是系统提示词里写死的一段文字：技能独立存放在各自目录内，通过机制在需要时注入。

技能是什么？

技能是“专用提示词模板”。被激活时，它会同时：

注入一段详细指令到对话上下文（改变 Claude 的思考与行动策略）
修改执行上下文（预授权工具、切换模型等）

技能本身不直接“干活”。它是展开成详尽指令的操作手册，让 Claude 以正确角色和流程处理任务。

请求进入系统后，发生了什么？

当用户发起请求时，Claude 会同时接收到：

用户消息（例：请帮我从这个 PDF 中提取文字）
可用工具列表（如 Read、Write、Bash 等）
Skill 工具（列出了全部技能的名称与描述）

Claude 读完技能清单后，基于语言理解把“用户意图”与“技能描述”进行匹配。例如用户让它“创建一个技能”，它看到 skill-creator 的描述正是“帮助创建新技能”，就会决定调用该技能。

技能选择的机制

无算法路由、无意图分类、无正则、无 embeddings 或分类器。
系统只负责把所有技能描述格式化为一段可读文本，嵌入到 Skill 工具提示词中。
选择完全由模型的推理完成。这是“纯 LLM 推断”。

技能被调用后，系统的动作

加载技能目录中的 SKILL.md
把文件内容展开为详细指令
将这些指令作为新的用户消息注入到对话上下文
调整执行上下文（授权工具、切换模型等）
带着“增强后的环境”继续对话

与传统工具不同：工具是“执行动作并返回结果”，技能是“塑形与准备”，让 Claude 以正确的方式去完成任务。

工具 vs. 技能

执行方式：工具是同步执行；技能是提示词展开（Prompt Expansion）。
用途：工具做具体操作；技能引导复杂工作流。
返回：工具直接给结果；技能修改对话与执行上下文。
并发：工具通常安全；技能本质为 prompt，不提供并发能力。
类型：工具多样；技能始终是“提示词类型”。
示例：工具如 Read/Write/Bash；技能如 internal-comms、skill-creator。

如何构建 Agent Skills？

以 Anthropic 官方 skill-creator 为例，拆解构建方法。

核心公式：

技能 = 提示词模板 + 对话上下文注入 + 执行上下文修改 + 可选的数据文件与脚本

文件结构

每个技能由一个名为 SKILL.md 的 Markdown 文件定义（文件名大小写不敏感），可配套放置辅助文件。以 skill-creator 为例：

SKILL.md —— 核心指令
LICENSE.txt —— 许可证
scripts/ —— 可执行脚本集合

技能的发现与加载来源

用户级：~/.config/claude/skills/
项目级：.claude/skills/
插件提供的技能
内置技能

桌面版 Claude Desktop 也支持直接上传自定义技能。

核心设计思想：渐进式披露

“只在需要的时刻，展示刚好足够的信息”，再逐层展开。分为三步：

先展示技能的元数据头（Frontmatter）：名称、简介、许可证等最小必要信息
当 Claude 做出选择，才加载完整 SKILL.md
执行过程中，按需加载脚本、参考文档或资源文件

SKILL.md 的两段式结构

YAML 元数据头（Frontmatter）：声明权限、模型与元信息
Markdown 正文：给 Claude 的具体指令、流程与示例

可以类比“信件”：信封是投递信息（元数据），信的内容才是操作指南（正文）。

1. YAML 元数据头（配置）

---
name: skill-name
description: 简要说明
allowed-tools: Bash, Read
version: 1.0.0
---

2. Markdown 正文（指令）

用途说明
详细指令
示例与指南
分步工作流程

Frontmatter 字段详解

以 skill-creator 为例：

---
name: skill-creator
description: Guide for creating effective skills. This skill should be used
  when users want to create a new skill (or update an existing skill) that
  extends Claude's capabilities with specialized knowledge, workflows, or
  tool integrations.
license: Complete terms in LICENSE.txt
---

必填字段

name：技能名称，会作为 Skill 工具的 command 参数（例如 command: skill-creator）。
description：一句到两句说明“做什么与何时用”。它是 Claude 判断是否调用该技能的主要依据，必须清晰、面向行动。

可能存在但不建议使用

when_to_use：代码库中常见，但官方文档未公开，可能已弃用或仍在实验。若存在，系统会把它拼接到 description 之后。更稳妥做法是直接把触发条件写入 description。

可选字段

license：许可证信息。
allowed-tools：技能可以无需额外确认即可使用的工具白名单（逗号分隔，将被解析为数组）。可使用通配符限制范围，例如 Bash(git:) 仅允许 git 命令，Bash(npm:) 仅允许 npm 操作。

示例（推荐与不推荐）：

# 精准授权：只列必须工具
allowed-tools: Read,Write,Edit,Glob,Grep

# 精准授权：仅开放特定 git 命令
allowed-tools: Bash(git status:*),Bash(git diff:*),Read,Grep

# 不推荐：过宽的权限边界，存在安全风险
allowed-tools: Bash,Read,Write,Edit,Glob,Grep,WebSearch,Task,Agent

model：指定技能使用的模型，默认继承会话模型。复杂任务（如代码审查）可指定更强模型。

model: claude-opus-4-20250514  # 指定模型
model: inherit                  # 使用会话模型（默认）

version：版本号，便于追踪与文档管理。
disable-model-invocation：true 时禁止 Claude 自动调用，仅允许用户通过 /技能名 手动触发，适合高风险或需强控制的流程。
mode：true 时将该技能归为“模式命令”，在列表顶部独立呈现（如 debug-mode、expert-mode）。

正文写作：让技能真正“好用”

Frontmatter 下方即为 Markdown 正文——Claude 激活技能后实际接收到的指令。写作要点：聚焦核心，配合渐进式披露；把细节外置为文件，按需加载。

写作最佳实践

整体控制在 5000 字以内（约 800 行），避免撑满上下文窗口。
使用祈使句（例：“分析代码中的…”），避免“你应该…”。
细节外置：把长文档和模板放入外部文件，由技能按需加载。
路径统一使用 {baseDir}，不要写死绝对路径。

资源目录结构与职责

my-skill/
├── SKILL.md               # 核心指令
├── scripts/               # Python/Bash 可执行脚本
├── references/            # 需要读入上下文的参考文档
└── assets/                # 模板与二进制，通常不读入上下文

为什么要拆到外部

为了让 SKILL.md 保持精简，避免浪费上下文容量；把复杂说明、自动化脚本与模板放外部，按需加载更高效。

scripts/ —— 可执行脚本

用于承载需要“精确控制”的逻辑：自动化、多步转换、API 交互或比自然语言更稳的机械性任务。例：初始化脚本 init_skill.py，在正文中指示执行：

python {baseDir}/scripts/init_skill.py

references/ —— 需要读入上下文的文档

适合 Markdown、JSON 模式定义、配置模板等；通过 Read 工具加载（例：Read({baseDir}/references/mcp_best_practices.md)）。

assets/ —— 静态资源

放模板与二进制（HTML/CSS/图片/配置模板等）。Claude 知道路径，但一般不把内容读入上下文；可复制、替换占位符、或在输出中引用。

references/ 与 assets/ 的关键差异

references/：文本会读入上下文，占用 Token。
assets/：仅按路径引用，不消耗上下文。

为了通用性，路径一律使用 {baseDir}，避免绝对路径。

常见技能设计模式

模式一：脚本自动化

场景：多步命令、精确逻辑。把计算交给 scripts/，技能负责“调用→解析输出→整理结果”。

模式二：读取-处理-写入

场景：文件转换、数据清洗、报告生成。读入→转换→写出，最直接的流水线。

模式三：搜索-分析-报告

场景：代码库模式检测或企业数据分析。借助 Grep 搜索→Read 获取上下文→分析→产出结构化报告。

模式四：命令链执行

场景：步骤有依赖的串行流程（如类 CI/CD）。每一步依赖上一步成功。

进阶设计模式

向导式多步工作流

场景：每一步都需用户确认的复杂流程（如安装/配置向导）。

模板生成

场景：基于 assets/ 的模板化输出：加载模板→解析需求→填充占位符→写出成品。

迭代优化

场景：多轮扫描与深入。

第一轮：广域扫描，发现高层问题
第二轮：逐项深挖，标注成因与严重度
第三轮：结合最佳实践，给出修复建议

多源信息汇总

场景：整合多文件多工具的数据，形成全景式总结（如项目概况、依赖分析、影响评估）。

案例：PDF 技能的完整生命周期

阶段一：发现与加载（启动）

Claude Code 启动时并行扫描：

加载用户级命令（~/.claude/commands/）
加载技能与插件（.claude/skills/ 与插件目录）
加载插件定义的命令
加载内置命令

合并并过滤禁用项后，得到可用技能列表。PDF 技能的数据对象大致如下：

type: prompt
name: pdf
description: 从 PDF 文档中提取文字
allowedTools: [Bash(pdftotext:*), Read, Write]
isSkill: true

阶段二：用户请求与技能选择

用户请求：从 report.pdf 提取文字。系统将技能列表以文本形式提供给 Claude，但不是所有技能都会出现，需满足：

type 为 prompt
isSkill: true
未禁用模型调用
有用户可读的描述或 when_to_use

通过过滤的技能会被格式化为单行描述，例如：

pdf: 从 PDF 文档中提取文字 - 当用户想提取或处理 PDF 文件中的文字时使用

Claude 的推断过程大致是：任务是 PDF 文本提取→列表中有 pdf 技能→描述完全匹配→调用 Skill 工具并将 command 设为 pdf。

阶段三：Skill 工具执行

输入验证：检查空名称、是否存在、能否加载、是否禁用模型调用、类型是否为 prompt。
权限检查：先看“阻止规则”，再看“允许规则”；都未命中则询问用户是否执行。
加载并生成执行上下文修改器：
- 读取完整 SKILL.md
- 生成可视的加载元信息
- 创建消息数组（元信息 + 隐藏技能提示词 + 附件/权限消息）
- 提取配置（允许工具、模型覆盖等）
- 生成 contextModifier：把 allowed-tools 加入预授权；若指定模型则切换

阶段四：发送 API 请求（第一轮完成）

系统组装并发送消息序列：

用户原始消息：Extract text from report.pdf
Claude 的工具调用：调用 Skill 工具（command: pdf）
元数据消息（可见）：pdf 技能正在加载
技能提示词（隐藏）：你是一个 PDF 处理专家...
权限消息：预授权 Bash(pdftotext:*)、Read、Write

此时技能只“注入了上下文”，并未直接完成任务。系统需要带着这些上下文再次与 Claude 交互，才进入实操环节。

阶段五：在技能上下文中执行工具

Claude 收到响应后，已经具备：

PDF 专业指令（来自对话上下文）
预授权工具（来自执行上下文）
清晰工作流（来自对话上下文）

接着按工作流执行：

检查 report.pdf 是否存在
通过 Bash 执行 pdftotext 提取文字（无需再询问）
用 Read 读取输出文件
将结果返回给用户

可以看到，技能的核心在于“对话上下文注入 + 执行上下文授权”。

结语：为何这套设计足够“简单但有力”

很多人会问：为什么 Anthropic 把技能系统做得如此“朴素”？

答案是：当模型的阅读理解能力足够强，复杂路由与调度常常是负担。

一个 Markdown 文件，就能让 Claude 理解意图、执行工作流。

归纳起来，技能系统就是三件事：

发现：扫描目录，汇总技能清单
注入：把技能提示词插入对话上下文
执行：预授权工具，让 Claude 依指令工作

没有魔法，没有黑盒，只有清晰的工程边界与对 LLM 能力的正确利用。

真正的 Agent 能力，不在于写多少 API 和框架，而在于用自然语言精心设计工作流。

这篇文章建议收藏、反复阅读，每次回看都会有新的理解与改进方向。

声明：本站原创文章文字版权归本站所有，转载务必注明作者和出处；本站转载文章仅仅代表原作者观点，不代表本站立场，图文版权归原作者所有。如有侵权，请联系我们删除。

未经允许不得转载：新手入门：深入浅出 Agent Skills 底层原理全解析（附实战案例）

请登录后发表评论