这不是”插件”也不是”函数调用”，而是一套能把通用大模型瞬间变成”领域专家”的提示工程与上下文管理体系。原文作者：Han Lee（《Claude Agent Skills: A First Principles Deep Dive》）。

---

为什么你总觉得 Claude code Agent 不稳定？因为你把”执行”当成了”理解”

写 Agent 时我们老犯一个错：一股脑往里塞工具，然后期待模型”自己懂”怎么调用。现实是，模型理解力强，但流程与上下文管理才是关键。

Han Lee 的结论非常直白：Claude 的 Skills 不是可执行代码，而是”注入型元工具”。它通过两步完成”专家化”：

• • 提示扩展：把一整套领域 SOP 以 Markdown 的方式注入会话上下文（如”PDF 专家工作流”）。
• • 执行上下文修改：临时改变工具权限与模型选择（如允许 Bash 的某些子命令）。

因此，技能解决的是”如何正确做事”，而不是”把事做了”。这和我们过去的函数调用思路完全相反。

---

整体架构：一个”Skill”元工具，管理一堆”skills”

• • Skill（大写 S）：一个”元工具”，放进 API 的 tools 数组里，专门用来管理 skills。
• • skills（小写 s）：一个个具体技能（如 pdf、skill-creator、internal-comms），本质是可注入的提示模板与资源包。

启动时，Claude Code只扫描每个技能的Frontmatter（name、description等），把它们合并在 Skill 的描述里，形成可用技能列表。一旦模型判断匹配，就”激活技能”——这时才把完整的 SKILL.md 注入到上下文里。

---

关键设计：两条”用户消息”，一条给人看，一条给模型看

激活技能时，系统会插入两条”user”消息：

1. 1. 可见消息（无 isMeta 或为 false）——给你看：“The ‘pdf’ skill is loading…”
2. 2. 不可见消息（isMeta: true）——给模型看：整份”PDF 专家工作流”的 Markdown 指令

这样既保持透明（你知道系统在做什么），又不污染 UI（不把几千字的专家提示堆到聊天里）。

---

最有价值的四个”工程套路”

1. 1. Script Automation（脚本自动化） 把确定性工作（格式化、抽取、分析）交给 Python/Bash 脚本，提示里只负责”怎么编排”。 示例：

• • 在 scripts/analyzer.py 里做静态分析与报告生成；SKILL.md 只写”如何调用、如何解释输出”。

1. 2. Read–Process–Write（读处理写） 最稳健的变换链：读 → 解析 → 转换 → 写。 示例：

• • 读取 Markdown 文档，按企业模板生成汇报；写入目标目录并返回完成摘要。

1. 3. Search–Analyze–Report（搜索分析报告） 先用 Grep 做范围筛选，再 Read 上下文、分析、结构化输出。 示例：

• • 代码库内”安全敏感片段”批量检出；分类风险等级与修复建议，拼成一份审计报告。

1. 4. Command Chain Execution（命令串执行） 当流程有依赖关系，用命令链串起来，逐步校验。 示例：

• • npm install && npm run lint && npm test，失败就短路，成功才生成最终产物。

---

一个”从 PDF 提取文本”的端到端例子（可直接照抄）

我的目标：用户说”从 report.pdf 提取文本”，Agent 自动按 SOP 处理并返回结果。

• • 在 ~/.claude/skills/pdf/ 下放置：

• • SKILL.md：定义”PDF 专家工作流”（验证→调用 pdftotext→读取输出→格式化展示）
• • scripts/extract.py：容错与预处理（例如统一编码、拆页）
• • references/api-docs.md：工具调用说明与错误处理规范

• • Frontmatter（关键字段要精简、准确）：

  ---
  name: pdf
  description: 从 PDF 提取文字与表格；当用户提到 PDF 抽取、表单等任务时使用
  allowed-tools: Bash(pdftotext:*), Read, Write
  ---

• • 用户输入：“帮我从 report.pdf 提取文字”

• • 模型匹配到 pdf 技能（基于 description 文本理解）

• • 系统注入两条消息：

• • 可见：加载提示
• • 不可见：完整”PDF 专家工作流”

• • 权限消息：预批准 Bash(pdftotext:*)/Read/Write
• • 模型执行：验证文件→Bash 调用→Read 输出→返回格式化正文

这套流程里，技能从不直接”执行”，只是把”正确做事的方法”注入给模型，外加暂时调整工具权限。

---

SKILL.md 怎么写，才不会把上下文压爆？

• • 用 命令式 写法（“做 A→做 B”），少用”你应该…”。
• • 控制在5,000 字以内，详尽内容移到 references/。
• • 路径用 {baseDir}，避免写绝对路径。
• • allowed-tools 最小化授权，只开必要子命令（如 Bash(git status:*)）。
• • 风险技能可设置 disable-model-invocation: true，只允许手动触发（如 /debug-mode）。

---

三个落地场景：把”专家化”用在正经事

1. 1. 团队代码评审（安全向）

• • 技能：security-review
• • 资源：references/checklist.md（OWASP Top 10）、scripts/scan.py
• • 结果：分级风险与修复建议，带可追溯证据片段。

1. 2. 企业文档生成（规范向）

• • 技能：internal-comms
• • 资源：assets/report-template.docx、references/style-guide.md
• • 结果：一键套用企业体例，标题/摘要/行动项完整闭环。

1. 3. 研发流程质控（流程向）

• • 技能：ci-quality-gate
• • 资源：scripts/check_coverage.py、references/quality-criteria.md
• • 结果：构建、静态分析、单测覆盖率三合一门禁，失败自动出具修复指引。

---

一些”坑位”与避雷

• • Token 开销：技能注入本身就很长；别把”百科全书”塞进 SKILL.md。
• • 并发安全：技能不是代码执行引擎；同时激活多个互相影响的技能容易搞崩。
• • 权限过大：allowed-tools 一股脑全开是踩雷；只开放必需子命令。
• • 过度智能：匹配完全依赖模型语言理解；description 写得笼统，容易”误触发”。

---

你该怎么开始（两小时入门版）

• • 选一个标准化强的场景（PDF、DOCX、PPTX、XLSX 任一）。
• • 按”读→处理→写”的链路，写出最小可用 SKILL.md。
• • 把繁琐步骤丢进 scripts/，把长文放进 references/，把模板放 assets/。
• • 写好 description 的”触发语境”（何时用、为啥用、用来做什么）。
• • 试跑 5 次，观察注入消息与权限是否合理，再迭代。

---

参考与延伸

• • 原文：Han Lee，《Claude Agent Skills: A First Principles Deep Dive》

• • Skill Creator Skill
• • Frontmatter 字段说明
• • References 列表

• • 官方背景与工程文章：

• • Introducing Agent Skills
• • Equipping Agents for the Real World with Agent Skills

---

最后一句话

别把 Skills 当”插件市场”的小玩意儿，它是把”团队 SOP”工程化为”模型的工作流记忆”的钥匙。先让模型”正确地做事”，再让工具”把事做对”。当你这么构建，通用模型就能在你的业务里，靠谱地扮演专家。

原文和翻译

https://cc.GuapiHub.com/blog/cc-skills-deep.html