今天我们聚焦的是 Agent Skills 这一扩展 AI 智能体能力边界的核心机制。在 AI Agent 技术快速演进的今天，无论你是希望提升开发效率的工程师，还是想要构建可复用 AI 能力的架构师，掌握 Agent Skills 的使用和理解都将成为你的重要技能储备。

  结合当前 AI 开发的实际需求，我们会重点抓住四个核心问题：Agent Skills 是什么、为什么我们需要它、如何理解它的调用机制、如何认识它的结构和生态。这四个问题将帮助你从"快速认知"到"深度理解"，完成从使用者视角到创建者视角的认知转变。

  为了把这些内容讲清楚，接下来我们会按照"快速建立认知 → 理解调用机制 → 理解结构组成 → 认识生态边界“的四阶段主线展开。每个阶段都有明确的学习目标和验证任务，确保你能够扎实掌握每一层知识，为后续深入学习打下坚实基础。

课前预检 链接到标题

  在正式进入 Agent Skills 的学习之前，我们需要先完成两项前置工作：明确学习边界和环境就绪检查。这看似是"行政流程”，实则是线上学习的关键防卡点——根据过往经验，环境问题和预期不匹配是学员在课程早期掉队的常见原因，而这些问题完全可以通过前置预检避免。

0.1 学员画像与先修声明 链接到标题

  本课程的核心受众是具备基本编程经验的开发者。如果你了解 AI 基础概念，并且希望系统学习 Agent Skills 的使用和理解，那么这门课程非常适合你。除了开发者之外，对 AI Agent 技术感兴趣的技术管理者和产品经理也可以通过本课程建立 Agent Skills 的认知框架。不过需要说明的是，如果你完全没有编程经验，建议先学习 Python 基础；如果你已经有丰富的 Agent Skills 生产经验，这门基础课程可能无法满足你的进阶需求。

  在开始学习之前，你需要具备一些前置知识。首先是必需的基础能力：你应该能够使用基本的命令行操作（比如 cd、ls、mkdir 等命令），了解 Markdown 的基本语法，并且理解 AI 大模型的基本概念（如 LLM、Prompt 等）。除此之外，如果你了解 Function Calling 的基本概念，或者有使用过 Claude Code 或类似 AI 编程工具的经验，会对理解本课程内容有更大帮助，但这些并非必需条件。

0.2 环境预检 链接到标题

  在开始学习之前，请确保你的开发环境已经准备就绪。从操作系统来看，macOS、Linux 和 Windows 都可以使用，不过我们更推荐 macOS 或 Linux 环境。你需要安装 Git（版本 2.0 及以上），以及一个顺手的文本编辑器，比如 VS Code、Sublime Text 或 Vim 都可以。

  如果你想要获得完整的学习体验，还可以准备一些可选环境。Claude Code 可以让你体验 Agent Skills 的实际调用过程，Python 3.8 或更高版本则可以用于运行课程中的示例代码。这些都不是必需的，但会让你的学习过程更加顺畅。

  你可以使用以下代码快速检查环境：

# 检查 Python 版本
import sys
print(f"Python 版本: {sys.version}")

# 检查 Git 是否安装
import subprocess
try:
    result = subprocess.run(['git', '--version'], capture_output=True, text=True)
    print(f"Git 版本: {result.stdout.strip()}")
except FileNotFoundError:
    print("Git 未安装")

  执行后，如果看到 Python 和 Git 的版本信息，说明基础环境已就绪。

📅 版本说明：本课程内容基于 Claude Code 2026年3月版本编写。Agent Skills 是一个快速发展的技术领域，部分功能和最佳实践可能随版本更新而变化。建议学习时参考官方文档的最新版本。

第一部分：快速建立认知 链接到标题

  在这一部分，我们会从一个真实的开发痛点出发，引出 Agent Skills 的核心价值，然后给出清晰的定义和关键特性。这部分的目标是让你快速建立对 Agent Skills 的整体认知，理解"它是什么"以及"为什么需要它"。

1.1 痛点场景：开发者卡在"AI 不会做" 链接到标题

  很多开发者在使用 AI 编程助手时，会遇到一个共同的困境：不是不知道怎么问，而是 AI 不知道怎么做。这个问题的本质，不在于提示词写得不够长，而在于任务背后需要稳定的能力链。

  让我们看几个熟悉的开发任务。第一个是补充单元测试：表面上看，你只是想让 AI 给某个函数写几个 it() 测试用例，但实际上你需要的是一个完整的流程——理解代码逻辑、设计测试场景、编写测试代码、验证覆盖率。痛点在于，每次你都要重新解释"我要的不只是代码，还要完整的测试流程"。

  第二个任务是批量整理 Markdown 文档。你说"把这些文档整理一下"，但实际需求包括统一格式、提取关键信息、生成目录、检查链接有效性等多个步骤。AI 可能只做了格式化，但没有完成信息提取和验证，这就是问题所在。

  第三个任务是找适合的 Skill。你说"帮我找一个处理 PDF 的工具"，实际上你希望 AI 能够理解你的需求、搜索生态、对比功能、给出推荐。但 AI 可能直接推荐一个工具，却没有说明为什么选它，这让你无法判断是否真的适合。

  这些任务的共同特点是：它们不是一句答案能结束的，而是需要一个稳定的、可复用的能力链。这就是 Agent Skills 要解决的核心问题。真正缺的不是更多话术，而是三个关键要素：可发现的能力（AI 能知道"我有这个能力"）、可执行的流程（AI 能按照结构化流程完成任务）、可复用的结构（同样的能力可以在不同场景下复用）。

1.1.2 技术视角：三大架构痛点 链接到标题

  从技术架构的角度看，传统的纯 Prompt 驱动 Agent 面临三个深层次的工程痛点。

  第一个痛点是"巨型提示词灾难"（Mega-Prompt Problem）。当开发者试图将所有业务规则、边界条件、操作流程都硬编码进系统提示词时，上下文窗口会急剧膨胀。单次交互可能消耗数万 Token，不仅推高了推理成本和响应延迟，更严重的是引发了模型的"注意力丢失"（Lost in the Middle）现象——当模型面对超过其高保真处理能力的庞杂指令时，指令遵循能力会出现断崖式下降。

  第二个痛点是"执行域"与"专业知识域"的割裂。当前的 Agent 系统通常配备了丰富的外部工具库，但"拥有工具"绝不等于"知道如何专业地使用工具"。工具仅仅提供了智能体的"手脚"，却没有赋予 Agent 解决特定领域问题的"操作智慧"。面对复杂的商业需求，仅仅提供一个可以执行 SQL 查询的工具是远远不够的，Agent 还需要知道如何针对特定的海量数据表结构进行多步查询、如何交叉验证数据质量、以及如何处理异常回退。

  第三个痛点是复杂任务中对复用性、约束力、稳定性和可维护性的苛刻需求。在企业级应用场景下，同一个任务往往需要在不同时间、由不同用户高频触发。如果系统行为依赖动态的上下文生成或临时的短提示词，系统输出将展现出极大的随机性。工程化系统要求的是确定性和高可靠性，需要一种机制能够将资深专家的"隐性知识"转化为大模型可理解的"标准操作流程（SOP）"。

⚠️ 关键洞察：这三个痛点的共同本质是——传统架构缺乏一种"可插拔的领域专家大脑"机制，而这正是 Agent Skills 要解决的核心问题。

1.2 核心定义：一句话理解 Agent Skill 链接到标题

  在理解了痛点之后，我们可以给出 Agent Skills 的核心定义：

Skill 是一个可被 Agent 在运行时发现、理解、调用和组合的能力模块。

  这个定义包含了四个关键动词，它们共同构成了 Skill 的完整生命周期。首先是"发现"，Agent 能知道这个能力存在，并且知道它适合什么任务。其次是"理解"，Agent 能理解这个能力的边界和使用方式。第三是"调用"，Agent 能在合适的时机调用这个能力。最后是"组合"，Agent 能将多个能力组合起来完成复杂任务。

  为了更容易记住，我们可以用一个类比：

Agent Skills 的类比理解

  这个类比帮助我们理解整个生态的运作方式。Agent 就像手机，它本身有基础能力（打电话、发短信）；Skill 就像 App，它扩展了手机的能力（拍照、导航、支付）；生态就像应用商店，它让你能找到和安装需要的 App。

图：Agent Skills 核心角色类比

  如果你觉得"手机-App"的类比还不够直观，我们可以用另一个更贴近工作场景的类比：

Agent Skills 的工作场景类比

  当老板要求实习生"处理一下退款并发一份财务报告"时，实习生不需要凭空猜测或死记硬背所有规则，他只需从书架上抽出"退款处理与报告生成 SOP”（系统动态加载 Skill），翻开照着上面的详细步骤，一步步使用电脑和电话（Tool）来完美执行任务。

  这种方式犹如给 Agent 发放了一张图书馆借阅证，而不是强迫它背下整个图书馆。

1.3 三大特性：可发现、可执行、可复用 链接到标题

  理解了定义之后，我们需要进一步理解 Agent Skills 的三大核心特性。后面所有展开内容，其实都围绕这三个关键词。

特性一：可发现

  Agent 能知道这个 Skill 适合什么任务，不只是"这个能力存在"。这意味着 Skill 需要有清晰的描述（description），需要有明确的触发条件，需要能被 Agent 的路由系统识别。举个例子：当用户说"帮我补充单元测试"时，Agent 需要能够识别这是一个"测试相关"的任务，判断这个任务需要结构化流程，然后匹配到 test-driven-development Skill。

特性二：可执行

  进入 Skill 后，不是自由发挥，而是有结构化流程支撑。这意味着 Skill 内部有明确的执行步骤，能够引导 Agent 完成任务，能够处理常见的边界情况。继续上面的例子：test-driven-development Skill 会引导 Agent 依次完成理解代码逻辑、设计测试场景、编写测试代码、验证测试覆盖率这四个步骤。

特性三：可复用

  同一份能力可以跨场景、跨任务、跨时间持续使用和优化。这意味着 Skill 是独立的模块，不依赖特定上下文；Skill 可以被多个任务复用；Skill 可以被持续优化和迭代。这就是为什么 Skill 比"一次性 Prompt"更有价值：一次性 Prompt 每次都要重新写，容易遗漏细节；而 Skill 写一次就能到处复用，还能持续优化。

1.4 Skill vs Prompt：本质区别 链接到标题

  很多人会问：Skill 和 Prompt 有什么区别？它们不都是"告诉 AI 怎么做"吗？

  这个问题的答案，就藏在前面讲的三大特性里。让我们通过一个对比表格来理解：

Skill vs Prompt 本质区别对比

图：Skill 与 Prompt 的重量级对比

  用一个具体例子来说明：

场景：补充单元测试

使用 Prompt 的方式：

用户：“帮我给这个函数补充单元测试，要覆盖边界情况，要用 Jest 框架，要检查覆盖率，要…”

  这种方式存在三个明显问题。首先，每次都要重新描述需求，容易遗漏细节；其次，AI 可能理解偏差，执行不一致；最后，下次遇到类似任务，又要重新写一遍。

使用 Skill 的方式：

用户：“帮我补充单元测试” Agent：识别到 test-driven-development Skill Agent：按照 Skill 的流程执行

  相比之下，Skill 的优势非常明显。一句话就能触发，无需重复描述；执行流程一致，结果可预期；下次遇到类似任务，自动复用。

  这就是 Skill 的核心价值：它不是"更长的 Prompt"，而是"可发现、可执行、可复用的能力模块"。

1.5 三种技能结构对比 链接到标题

  在理解了 Skill 与 Prompt 的本质区别之后，我们需要进一步认识到：Skill 的结构并不是固定的，而是根据任务复杂度和资源需求灵活设计的。让我们通过三个真实的 Skill 案例，来理解不同复杂度的 Skill 是如何组织的。

1.5.1 简单技能：commit-message-generator 链接到标题

  最简单的 Skill 只需要一个清晰的 frontmatter 和简洁的 body，不依赖任何外部资源。让我们看一个生成 Git 提交信息的 Skill：

---
name: commit-message-generator
description: 基于暂存区的更改生成符合规范的提交信息
---

# 提交信息生成器 (Commit Message Generator)

## Goal
生成清晰、符合最佳实践的规范化提交信息。

## Workflow
1. 使用 git diff 分析暂存区的代码更改
2. 识别提交的主要类型 (feat/fix/docs/refactor/test)
3. 从被修改的文件中提取作用范围 (scope)
4. 生成一条简明扼要的标题行 (最多 50 个字符)
5. 如果更改逻辑复杂，可以在之后添加详细的正文说明

## Constraints
- 遵循 Conventional Commits 格式规范: `type(scope): subject`
- 标题行必须使用祈使句语气 (例如使用 "add" 而不是 "added")
- 标题行的长度严格控制在 50 个字符以内
- 标题行和正文之间必须用一个空行分隔

  这个 Skill 的特点是：结构简单、无外部依赖、执行流程清晰。它只需要 SKILL.md 一个文件就能完成任务，适合处理单一、明确的任务。

1.5.2 多步骤工作流技能：test-driven-development 链接到标题

  当任务需要多个步骤协同完成时，Skill 的 body 会包含更复杂的 Workflow 和分支逻辑。让我们看一个测试驱动开发的 Skill：

---
name: test-driven-development
description: 在实现任何新功能或修复 Bug 时使用，必须在编写实现代码之前调用
---

# 测试驱动开发 (Test-Driven Development)

## Goal
引导使用 TDD (测试驱动开发) 方法论来实现具体功能。

## Workflow
1. **理解需求 (Understand Requirements)**
   - 阅读功能描述或 Bug 报告的原始说明
   - 识别各项功能的验收标准
   - 如有必要，主动与用户澄清边缘情况

2. **设计测试用例 (Design Test Cases)**
   - 列举出所有需要进行测试的场景 (理想路径 + 边缘情况)
   - 按重要性对这些测试用例进行优先级排序
   - 重点考虑业务的边界条件情况

3. **测试先行 (Write Tests First)**
   - 使用项目指定的测试框架来实现测试用例代码
   - 确保这些测试最初都会运行失败 (红灯验证阶段)
   - 验证这些测试的覆盖率是否涵盖了所有的场景设计

4. **实现代码 (Implement Code)**
   - 编写恰好能让测试通过的最小代码 (绿灯实现阶段)
   - 在实现代码的过程中极其频繁地运行测试
   - 当跑通所有测试用例时即可停止编写代码

5. **重构代码 (Refactor)**
   - 在不改变任何外在行为的前提下提高代码内部质量
   - 在每个小的重构步骤之后立即运行测试用以验证
   - 确保所有测试依然通过 (即最终的重构验证阶段)

## Constraints
- 绝对不要在编写测试用例代码之前违规编写实现代码
- 每个测试函数/块都必须拥有异常清晰的断言 (assertion)
- 不同的测试必须是独立的，并且能够被重复稳定运行
- 以大于 80% 的代码测试覆盖率为最低要求标准

  这个 Skill 的特点是：多步骤流程、有明确的阶段划分、包含决策点。它通过结构化的 Workflow 引导 Agent 完成复杂的开发任务，确保每个步骤都不会遗漏。

1.5.3 资源依赖型技能：lesson-interaction-architect 链接到标题

  最复杂的 Skill 不仅有复杂的执行流程，还依赖外部资源（脚本、模板、数据文件）。让我们看一个设计交互式课件的 Skill：

---
name: lesson-interaction-architect
description: 基于用户大纲、课堂主题、课件笔记或交互灵感，专门设计用于网页端的单节课 HTML 交互体验架构
---

# 交互课件架构师 (Lesson Interaction Architect)

## Goal
设计引人入胜的、基于 HTML 的交互式教育学习体验。

## Workflow
1. **分析学习目标 (Analyze Learning Objectives)**
   - 从源材料中提取核心教学概念
   - 识别学员目前需要解决的知识盲点
   - 规划可被衡量和测试的学习成果

2. **选择交互模式 (Select Interaction Patterns)**
   - 从模式库文档 (patterns/) 中挑选交互模式
   - 将特定的交互模式与学习目标严格匹配
   - 考量认知负荷与用户参与度的极限边界

3. **设计信息架构 (Design Information Architecture)**
   - 将内容结构化为符合人脑逻辑的前后段落
   - 规划用户浏览和探索这部分内容的导航流
   - 设计当用户交互后的即时正向反馈机制

4. **生成 HTML 原型 (Generate HTML Prototype)**
   - 使用内置的 templates/ 中的页面模板库
   - 根据选出的交互模式，将抽象内容注入其中
   - 丰富细节，为静态元素添加 CSS 等过渡与动画

5. **验证初步设计 (Validate Design)**
   - 检查其无障碍访问能力是否达标 (基于 WCAG 2.1 AA 标准)
   - 要求代理终端在多种设备断点下进行渲染流测试
   - 模拟用户的全流程进行多轮体感走查并汇总

## Resources
- `patterns/`: 针对各种场景的交互组件流模式库
- `templates/`: 开箱即用的 HTML/CSS/JS 页面模板骨架
- `scripts/validate.py`: HTML 节点无障碍规范自动检查器

  这个 Skill 的特点是：依赖外部资源、需要调用脚本、使用模板文件。与其同级的资源文件夹包含了执行任务所需的所有辅助资源，使得 Skill 可以处理更复杂的任务。

1.5.4 三种结构的对比分析 链接到标题

  现在让我们通过一个对比表格，清晰地理解这三种 Skill 结构的差异：

三种 Skill 结构对比

  通过这个对比，我们可以看到：Skill 的结构设计是灵活的，应该根据任务的复杂度和资源需求来选择合适的组织方式。简单任务用简单结构，复杂任务用复杂结构，这样既能保持 Skill 的可维护性，又能充分发挥 Skill 的能力。

  在实际使用中，你会发现：大部分 Skill 都是简单技能或多步骤工作流技能，只有少数需要复杂资源支持的 Skill 才会采用资源依赖型结构。这种设计哲学体现了"简单优先、按需复杂"的原则。

第二部分：理解调用机制 链接到标题

  在第一部分，我们建立了对 Agent Skills 的整体认知。现在，我们需要深入理解：Agent 是如何判断要不要调用 Skill 的？整个调用流程是怎样的？这部分的目标是让你理解 Skill 的调用机制，能够判断哪些任务适合使用 Skill。

2.1 Agent 如何判断调用 Skill 链接到标题

  当用户发出一个请求时，Agent 需要经历一个完整的决策流程，才能决定是否调用 Skill。这个流程可以分为五个步骤。

  首先是识别任务。Agent 需要理解用户的请求是什么类型的任务。比如"帮我补充单元测试"会被识别为测试相关任务，“整理这些 Markdown 文档"会被识别为文档处理任务，“找一个处理 PDF 的 Skill"会被识别为 Skill 搜索任务。

  接着是判断能力边界。Agent 需要判断这个任务是否需要 Skill。判断依据包括：任务是否需要结构化流程、是否需要多步骤执行、是否有明确的验证标准。如果任务很简单（如"什么是 Python”），Agent 可以直接回答，不需要调用 Skill。

  第三步是匹配 Skill。如果判断需要 Skill，Agent 会在可用的 Skill 列表中查找匹配的 Skill。匹配依据包括：Skill 的 description 是否与任务相关、Skill 的触发条件是否满足、Skill 的能力边界是否覆盖任务需求。

  第四步是执行 Skill。匹配到 Skill 后，Agent 会调用 Skill 并传入上下文信息。Skill 内部会引导 Agent 完成任务。

  最后是整合输出。Skill 执行完成后，Agent 会将 Skill 的输出整合到对话中，返回给用户。

  让我们通过一个具体例子来理解这个流程：

示例：用户请求"帮我补充单元测试”

步骤一：识别任务 → 任务类型：测试相关 → 任务特征：需要理解代码、设计用例、编写测试

步骤二：判断能力边界 → 需要结构化流程：是 → 需要多步骤执行：是 → 有明确验证标准：是 → 结论：需要调用 Skill

步骤三：匹配 Skill → 搜索关键词：test, unit test, TDD → 匹配到：test-driven-development → 验证能力边界：是，覆盖测试编写流程

步骤四：执行 Skill → 调用 test-driven-development → 传入上下文：当前代码文件 → Skill 引导：理解代码 → 设计用例 → 编写测试

步骤五：整合输出 → Skill 输出：测试代码 + 覆盖率报告 → Agent 整合：返回给用户

图：Agent Skills 执行流程的阶段推进

2.1.3 Token 经济学：为什么这种设计如此高效 链接到标题

  Agent Skills 的发现机制背后有一个精妙的设计哲学——渐进式信息披露（Progressive Disclosure）。

  在系统空闲或处理无关任务时，系统仅仅加载包含数百 Token 的所有技能元数据（名字和描述），以维持技能的全局可见性。一旦识别到特定任务匹配，Agent 才通过内部工具读取完整的 SKILL.md（几千 Token），最后才按需动态加载体积庞大的参考资产（可能高达数万 Token）。

  这种极具巧思的压缩与解压机制，使得系统能够在不牺牲局部上下文深度的同时，赋予了单体 Agent 几乎无限的广度和可扩展性。

渐进式信息披露的 Token 消耗对比

  这种设计让 Agent 能够"知道"数百个技能的存在，但只在需要时才"学习"具体的操作细节，极大地优化了系统的资源消耗。

2.2 路由决策的完整流程 链接到标题

  在上面的五步流程中，最关键的是"步骤三：匹配 Skill"。这个步骤涉及到 Agent 的路由决策机制。

  路由决策的核心是：Agent 如何从多个可用的 Skill 中，选择最合适的那一个？

  决策依据包括三个主要方面。首先是语义匹配度，Agent 会评估 Skill 的 description 与用户请求的语义相似度，同时进行关键词匹配（如"test"、“PDF”、“markdown”）。其次是能力边界匹配，Agent 会判断 Skill 的能力范围是否覆盖任务需求，以及 Skill 是否有处理类似任务的经验。最后是优先级规则，某些 Skill 可能有更高的优先级，或者被标记为"推荐"。

  让我们通过一个综合的"五步执行流与路由过滤漏斗图"来直观理解这个完整的决策机制：

图：五步执行流与路由过滤漏斗图

  这个过滤式漏斗模型展示了 Agent 如何一步步缩小候选 Skill 的范围，最终淬炼出最合适的那一个送入执行流水线。

2.3 实际案例演示 链接到标题

  为了更好地理解路由机制，让我们看三个不同类型的请求，观察 Agent 如何做出不同的决策。

案例一：补充单元测试

用户请求：“帮我给这个函数补充单元测试”

Agent 分析： 任务类型为测试相关，需要 Skill（因为需要结构化流程）， 候选 Skill 为 test-driven-development， 匹配度高（description 包含"unit test"）， 决策结果是调用 test-driven-development

执行结果： 依次完成理解代码逻辑、设计测试场景、编写测试代码、验证覆盖率

案例二：整理 Markdown 文档

用户请求：“帮我整理这些 Markdown 文档”

Agent 分析： 任务类型为文档处理，需要 Skill（因为需要批量处理）， 候选 Skill 可能有多个（文档整理、格式化等）， 匹配度需要进一步判断具体需求， 决策结果是可能需要询问用户具体需求

执行结果： 询问用户是格式化、还是提取信息、还是生成目录， 根据用户回答，调用相应 Skill

案例三：找 PDF Skill

用户请求：“帮我找一个处理 PDF 的 Skill”

Agent 分析： 任务类型为 Skill 搜索，需要 Skill（需要搜索生态）， 候选 Skill 为 find-skills， 匹配度高（description 包含"find skill"）， 决策结果是调用 find-skills

执行结果： 搜索关键词 PDF，找到 pdf Skill， 返回 Skill 描述和使用方式

2.4 任务判断练习 链接到标题

  现在轮到你来判断了。能开始区分任务类型，你才算真正进入"理解 Skill"的阶段。

  下面是几个真实场景，请判断：这个需求会触发 Skill 吗？如果会，是哪个 Skill？

场景一：补充单元测试

  用户请求：“帮我给这个函数补充单元测试”

💭 思考：这个需求会触发 Skill 吗？如果会，是哪个 Skill？

答案：会触发 test-driven-development Skill

推理过程：

  这是一个需要结构化流程的任务，需要理解代码逻辑、设计测试用例、编写测试代码，符合 TDD Skill 的触发条件。

场景二：简单问答

  用户请求：“什么是 Python？”

💭 思考：这个需求会触发 Skill 吗？

答案：不一定需要 Skill

推理过程：

  这是一个简单的知识问答任务，Agent 可以直接回答，不需要结构化流程，不符合 Skill 的触发条件。

场景三：找 PDF Skill

  用户请求：“帮我找一个处理 PDF 的 Skill”

💭 思考：这个需求会触发 Skill 吗？如果会，是哪个 Skill？

答案：会触发 find-skills Skill

推理过程：

  这是一个 Skill 搜索任务，需要搜索生态、对比功能、给出推荐，符合 find-skills Skill 的触发条件。

场景四：复杂工作流

  用户请求：“帮我创建一个新项目，包括初始化 Git、创建目录结构、配置 ESLint”

💭 思考：这个需求会触发 Skill 吗？可能需要几个 Skill？

答案：可能需要多个 Skill 组合

推理过程：

  这是一个复杂的工作流任务，可能需要项目初始化 Skill 加上配置管理 Skill，或者使用一个综合的项目脚手架 Skill。

  通过这些练习，你应该能够初步判断：哪些任务适合使用 Skill，哪些任务不需要 Skill。

2.5 执行机制的代码实现 链接到标题

  在理解了 Agent 的五步决策流程之后，我们需要进一步理解：这个流程在代码层面是如何实现的？Skill 是如何被加载、解析、注入到 Agent 的系统提示词中的？

  让我们通过一个简化的 Python 实现来理解这个机制。这个实现展示了 Skill 执行器的核心逻辑，帮助你从"使用者视角"切换到"实现者视角"。

2.5.1 SkillExecutor 类的核心逻辑 链接到标题

  首先，我们需要一个 SkillExecutor 类来管理 Skill 的加载、解析和匹配。这个类是整个 Skill 系统的核心。

import os
import yaml
from pathlib import Path
from typing import Dict, List, Optional

class SkillExecutor:
    """Skill 执行器：负责加载、解析和匹配 Skill"""

    def __init__(self, skills_dir: str = ".claude/skills"):
        """
        初始化 Skill 执行器

        Args:
            skills_dir: Skill 目录路径
        """
        self.skills_dir = Path(skills_dir)
        self.skills: Dict[str, Dict] = {}
        self.load_all_skills()

    def load_all_skills(self):
        """加载所有 Skill"""
        if not self.skills_dir.exists():
            print(f"Skill 目录不存在: {self.skills_dir}")
            return

        # 遍历 skills 目录下的所有子目录
        for skill_path in self.skills_dir.iterdir():
            if skill_path.is_dir():
                skill_file = skill_path / "SKILL.md"
                if skill_file.exists():
                    self.load_skill(skill_file)

    def load_skill(self, skill_file: Path):
        """
        加载单个 Skill

        Args:
            skill_file: SKILL.md 文件路径
        """
        with open(skill_file, 'r', encoding='utf-8') as f:
            content = f.read()

        # 解析 frontmatter 和 body
        frontmatter, body = self.parse_skill_content(content)

        if frontmatter and 'name' in frontmatter:
            skill_name = frontmatter['name']
            self.skills[skill_name] = {
                'name': skill_name,
                'description': frontmatter.get('description', ''),
                'body': body,
                'path': skill_file
            }
            print(f"✅ 加载 Skill: {skill_name}")

    def parse_skill_content(self, content: str) -> tuple:
        """
        解析 Skill 内容，分离 frontmatter 和 body

        Args:
            content: SKILL.md 文件内容

        Returns:
            (frontmatter_dict, body_string)
        """
        # 检查是否有 frontmatter（以 --- 开头和结尾）
        if not content.startswith('---'):
            return None, content

        # 分离 frontmatter 和 body
        parts = content.split('---', 2)
        if len(parts) < 3:
            return None, content

        # 解析 YAML frontmatter
        try:
            frontmatter = yaml.safe_load(parts[1])
        except yaml.YAMLError as e:
            print(f"❌ YAML 解析错误: {e}")
            return None, content

        body = parts[2].strip()
        return frontmatter, body

    def match_skill(self, user_request: str) -> Optional[Dict]:
        """
        根据用户请求匹配最合适的 Skill

        Args:
            user_request: 用户请求文本

        Returns:
            匹配到的 Skill 字典，如果没有匹配则返回 None
        """
        # 简化的匹配逻辑：基于关键词匹配
        keywords = user_request.lower().split()

        best_match = None
        best_score = 0

        for skill_name, skill_data in self.skills.items():
            description = skill_data['description'].lower()

            # 计算匹配分数
            score = sum(1 for keyword in keywords if keyword in description)

            if score > best_score:
                best_score = score
                best_match = skill_data

        if best_match and best_score > 0:
            print(f"🎯 匹配到 Skill: {best_match['name']} (匹配分数: {best_score})")
            return best_match

        print("❌ 未找到匹配的 Skill")
        return None

  这段代码实现了 Skill 执行器的核心功能。load_all_skills() 方法遍历 Skill 目录，加载所有 SKILL.md 文件；parse_skill_content() 方法解析 frontmatter 和 body，分离元数据和主体内容；match_skill() 方法根据用户请求匹配最合适的 Skill。

  这个实现虽然简化了很多细节（比如实际的匹配算法会使用语义相似度而不是简单的关键词匹配），但它展示了 Skill 系统的核心工作原理：加载 → 解析 → 匹配。

2.5.2 Prompt 注入机制的实现 链接到标题

  当 Agent 匹配到合适的 Skill 后，需要将 Skill 的内容注入到系统提示词中。这个过程称为"Prompt 注入"。让我们看看这个机制是如何实现的。

class AgentWithSkills:
    """带有 Skill 支持的 Agent"""

    def __init__(self, skills_dir: str = ".claude/skills"):
        """
        初始化 Agent

        Args:
            skills_dir: Skill 目录路径
        """
        self.skill_executor = SkillExecutor(skills_dir)
        self.base_system_prompt = """
        你是一个智能助手，可以帮助用户完成各种任务。
        你可以调用已加载的 Skill 来完成复杂的工作流。
        """

    def build_system_prompt(self, skill: Optional[Dict] = None) -> str:
        """
        构建系统提示词

        Args:
            skill: 要注入的 Skill 字典

        Returns:
            完整的系统提示词
        """
        prompt = self.base_system_prompt

        if skill:
            # 注入 Skill 的内容
            prompt += f"\n\n# 当前激活的 Skill: {skill['name']}\n\n"
            prompt += f"## Skill 描述\n{skill['description']}\n\n"
            prompt += f"## Skill 执行指南\n{skill['body']}\n\n"
            prompt += "请严格按照上述 Skill 的 Workflow 执行任务。\n"

        return prompt

    def process_request(self, user_request: str) -> str:
        """
        处理用户请求

        Args:
            user_request: 用户请求文本

        Returns:
            Agent 的响应
        """
        # 步骤一：识别任务（简化实现）
        print(f"\n 用户请求: {user_request}")

        # 步骤二：判断能力边界（简化实现）
        needs_skill = self.needs_skill(user_request)

        if not needs_skill:
            print(" 任务简单，无需 Skill")
            return self.simple_response(user_request)

        # 步骤三：匹配 Skill
        matched_skill = self.skill_executor.match_skill(user_request)

        if not matched_skill:
            print(" 未找到合适的 Skill，使用默认处理")
            return self.simple_response(user_request)

        # 步骤四：执行 Skill（注入 Prompt）
        system_prompt = self.build_system_prompt(matched_skill)
        print(f"\n 系统提示词已更新，注入 Skill: {matched_skill['name']}")
        print(f" 系统提示词长度: {len(system_prompt)} 字符")

        # 步骤五：整合输出（这里简化为返回系统提示词）
        return f"已激活 Skill: {matched_skill['name']}\n系统提示词已更新"

    def needs_skill(self, user_request: str) -> bool:
        """
        判断任务是否需要 Skill

        Args:
            user_request: 用户请求文本

        Returns:
            是否需要 Skill
        """
        # 改进的判断逻辑：包含中英文关键词则需要 Skill
        skill_keywords = [
            # 中文关键词
            '测试', '重构', '部署', '分析', '生成', '设计', '学习路径', '课程',
            # 英文关键词
            'test', 'refactor', 'deploy', 'analyze', 'generate', 'design', 
            'learning path', 'course', 'plan', 'create', 'build'
        ]
        user_request_lower = user_request.lower()
        return any(keyword.lower() in user_request_lower for keyword in skill_keywords)

    def simple_response(self, user_request: str) -> str:
        """
        简单响应（不使用 Skill）

        Args:
            user_request: 用户请求文本

        Returns:
            简单响应
        """
        return f"收到请求: {user_request}\n使用默认处理流程"

# 初始化 Agent
agent = AgentWithSkills(skills_dir="./skills")

# 示例一：需要 Skill 的请求
print("=" * 60)
print("示例一：设计学习路径（英文请求）")
print("=" * 60)
response = agent.process_request("design a learning path for Python")
print(f"\n Agent 响应:\n{response}")

# 示例二：不需要 Skill 的请求
print("\n" + "=" * 60)
print("示例二：简单问答")
print("=" * 60)
response = agent.process_request("什么是 Python？")
print(f"\n Agent 响应:\n{response}")

# 示例三：查看注入后的完整系统提示词
print("\n" + "=" * 60)
print("示例三：查看注入后的完整系统提示词")
print("=" * 60)
matched_skill = agent.skill_executor.match_skill("design a learning path for Python")
if matched_skill:
    system_prompt = agent.build_system_prompt(matched_skill)
    print(f"\n 完整的系统提示词 ({len(system_prompt)} 字符):")
    print("=" * 60)
    print(system_prompt)
    print("=" * 60)
else:
    print(" 未找到匹配的 Skill")

# 示例四：对比注入前后的差异
print("\n" + "=" * 60)
print("示例四：对比注入前后的系统提示词")
print("=" * 60)
print("\n【注入前】基础系统提示词:")
print("-" * 60)
base_prompt = agent.build_system_prompt(skill=None)
print(base_prompt)
print("-" * 60)

matched_skill = agent.skill_executor.match_skill("design a learning path for Python")
if matched_skill:
    print(f"\n【注入后】激活 Skill: {matched_skill['name']}")
    print("-" * 60)
    enhanced_prompt = agent.build_system_prompt(matched_skill)
    print(enhanced_prompt)
    print("-" * 60)
    print(f"\n 提示词增长: {len(base_prompt)} → {len(enhanced_prompt)} 字符 (+{len(enhanced_prompt) - len(base_prompt)} 字符)")

  这段代码展示了 Prompt 注入的核心机制。build_system_prompt() 方法将 Skill 的 description 和 body 注入到系统提示词中，形成一个完整的执行指南。process_request() 方法实现了完整的五步流程：识别任务 → 判断能力边界 → 匹配 Skill → 执行 Skill（注入 Prompt）→ 整合输出。

  这个注入机制的关键在于：Skill 的内容不是"代码"，而是"提示词"。Agent 通过读取 Skill 的 body，将其作为执行指南注入到系统提示词中，从而"学会"如何完成这个任务。

2.5.3 完整的执行流程演示 链接到标题

2.5.3.1 选择一个简单的 Skill 案例 链接到标题

  为了更好地理解 Skill 的执行流程，我们选择一个结构简单、逻辑清晰的 Skill 作为案例：verification-before-completion。

  这个 Skill 的核心功能是：在声称任务完成之前，强制要求先运行验证命令并确认输出。它的设计理念非常简单——“先验证，再声明”（Evidence before claims）。

  让我们先看看这个 Skill 的基本信息：

verification-before-completion Skill 基本信息

  这个 Skill 的结构要简单得多：所有逻辑都在一个文件中，没有外部依赖。这使得它非常适合用来理解 Skill 的执行机制。

2.5.3.2 Skill 的核心内容结构 链接到标题

  让我们看看 verification-before-completion 的 SKILL.md 文件包含哪些核心部分：

---
name: verification-before-completion
description: Use when about to claim work is complete, fixed, or passing,
             before committing or creating PRs - requires running verification
             commands and confirming output before making any success claims
---

# Verification Before Completion

## Overview
核心原则：Evidence before claims, always.

## The Iron Law
NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE

## The Gate Function (5 步验证流程)
1. IDENTIFY: What command proves this claim?
2. RUN: Execute the FULL command (fresh, complete)
3. READ: Full output, check exit code, count failures
4. VERIFY: Does output confirm the claim?
5. ONLY THEN: Make the claim

## Common Failures (常见错误表格)
列举了各种常见的错误场景和正确做法

## Red Flags - STOP (危险信号)
列举了需要立即停止的危险信号

  从结构上看，这个 Skill 包含以下几个关键部分：

1. Frontmatter（YAML 头部）：定义 Skill 的名称和描述

2. Overview（概述）：说明核心原则

3. The Iron Law（铁律）：强调核心规则

4. The Gate Function（门控函数）：定义 5 步验证流程

5. Common Failures（常见错误）：列举错误场景

6. Red Flags（危险信号）：列举需要警惕的信号

  这种结构非常清晰：先说明原则，再给出具体步骤，最后列举常见错误。这正是一个好的 Skill 应该具备的结构。

2.5.3.3 Skill 执行流程解析 链接到标题

  现在让我们深入分析：当用户发出请求 “帮我提交这段代码” 时，系统是如何执行 verification-before-completion 这个 Skill 的？

第一阶段：Skill 激活与匹配

  当用户说 “帮我提交这段代码” 时，系统会经历以下步骤：

1. AgentWithSkills.process_request() 接收用户请求
2. needs_skill() 判断是否需要 Skill
   • 检测到关键词 “提交”（对应英文 “commit”）
   • 返回 True
3. SkillExecutor.match_skill() 匹配最合适的 Skill
   • 在所有 Skills 中搜索描述包含 “commit” 的 Skill
   • 找到 verification-before-completion（描述中包含 “before committing”）
   • 返回匹配分数（例如：2 分）
4. build_system_prompt() 将 Skill 内容注入到系统提示词

这个过程就像是在图书馆找书：先判断需要什么类型的书（needs_skill），然后在书架上找到最匹配的那本（match_skill），最后把书的内容展示给读者（build_system_prompt）。

第二阶段：系统提示词注入

  注入后的系统提示词会变成这样：

你是一个智能助手，可以帮助用户完成各种任务。
你可以调用已加载的 Skill 来完成复杂的工作流。

# 当前激活的 Skill: verification-before-completion

## Skill 描述
Use when about to claim work is complete, fixed, or passing,
before committing or creating PRs - requires running verification
commands and confirming output before making any success claims

## Skill 执行指南
[完整的 SKILL.md 内容，包括 5 步验证流程、常见错误等]

请严格按照上述 Skill 的 Workflow 执行任务。

  这就像是给 LLM 提供了一份详细的"作业指导书"，不仅告诉它要做什么（验证后再提交），还告诉它应该怎么做（5 步验证流程）。

第三阶段：按照 Workflow 执行

  LLM 接收到增强后的系统提示词后，会按照 “The Gate Function” 中定义的 5 步流程执行：

步骤 1: IDENTIFY（识别验证命令）
   └─> 问题："提交代码前需要验证什么？"
   └─> 答案："需要运行测试命令，确保所有测试通过"

步骤 2: RUN（运行完整命令）
   └─> 执行：pytest tests/ 或 npm test
   └─> 注意：必须是完整命令，不能只运行部分测试

步骤 3: READ（读取完整输出）
   └─> 检查：退出码（exit code）
   └─> 统计：失败数量（failures count）
   └─> 读取：完整的输出信息

步骤 4: VERIFY（验证输出是否确认声明）
   └─> 判断：输出是否显示 "0 failures"？
   └─> 如果 NO：报告实际状态（"有 3 个测试失败"）
   └─> 如果 YES：继续下一步

步骤 5: ONLY THEN（只有在验证通过后才能声明）
   └─> 声明："所有测试通过，可以提交代码"
   └─> 附带证据："[pytest 输出: 34/34 passed]"

  这个流程的关键在于：每一步都是强制性的，不能跳过。如果 LLM 试图在没有运行验证命令的情况下说 “测试应该通过”，就违反了 Skill 的规则。

2.5.3.4 为什么不需要读取外部文件？ 链接到标题

  你可能会问：为什么 verification-before-completion 不需要像 learning-path-architect 那样读取外部的 references 文件？

  答案很简单：因为它的逻辑足够简单，所有信息都可以放在一个文件中。

  让我们对比一下两种 Skill 的复杂度：

两种 Skill 的复杂度对比

  从表格中可以看出：

• 简单 Skill（如 verification-before-completion）：逻辑单一，所有内容都在 SKILL.md 中
• 复杂 Skill（如 learning-path-architect）：涉及多个知识领域，需要拆分为多个 references 文件

  这种设计遵循了"渐进式披露"（Progressive Disclosure）的原则：简单的 Skill 保持简单，复杂的 Skill 才引入外部文件。

2.5.3.5 完整执行流程图 链接到标题

  让我们用一个完整的流程图来总结 verification-before-completion 的执行过程：

  从流程图中可以看出，整个执行过程可以分为三个大阶段：

1. 激活阶段：识别任务（“提交代码”） → 匹配 Skill → 注入提示词
2. 执行阶段：按照 5 步验证流程执行 → 运行验证命令 → 读取输出
3. 决策阶段：验证输出 → 如果通过则声明成功 → 如果失败则报告实际状态

  这个流程的设计非常巧妙：它不是简单的"提示词拼接"，而是一个结构化的执行框架。Skill 通过明确的规则和步骤，确保 LLM 不会在没有验证的情况下声称任务完成。

2.5.3.6 核心设计原则总结 链接到标题

  通过对 verification-before-completion 的深度解析，我们可以总结出 Skill 系统的几个核心设计原则：

1. 单一职责原则：每个 Skill 只做一件事，并把它做好

   • verification-before-completion 只负责验证，不负责其他

2. 渐进式披露：简单的 Skill 保持简单，复杂的 Skill 才引入外部文件

   • 简单 Skill：所有内容在 SKILL.md 中
   • 复杂 Skill：拆分为 SKILL.md + references/ + scripts/

3. 强制执行规则：通过明确的 Workflow 和约束，确保 LLM 按规则执行

   • “The Iron Law”：NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE
   • “The Gate Function”：5 步验证流程，缺一不可

4. 可验证性：Skill 的执行结果必须是可验证的

   • 不能说 “应该通过”，必须说 “已验证通过，输出为 [具体输出]”

  这些设计原则不仅适用于 verification-before-completion，也适用于所有其他 Skills。理解了这些原则，你就能够更好地设计和使用 Agent Skills 系统。

 💡 关键洞察：Skill 系统的强大之处在于它将"规则"和"执行"分离。SKILL.md 定义了规则（做什么、怎么做、不能做什么），LLM 负责执行。这种分离使得系统既灵活又可控——你可以修改规则而不改变 LLM，也可以升级 LLM 而不改变规则。

 更重要的是，Skill 系统通过结构化的 Workflow 和明确的约束，将 LLM 从"自由发挥"变成了"按规则执行"。这正是 Agent Skills 能够可靠完成复杂任务的关键所在。

第三部分：理解 Skill 结构 链接到标题

  在第二部分，我们理解了 Agent 如何调用 Skill。现在，我们需要深入理解：Skill 内部是什么样的？它是如何组织的？这部分的目标是让你从"使用者视角"切换到"创建者视角"，理解 Skill 的基本结构。

3.1 从外到内看 Skill（语义缩放） 链接到标题

  理解 Skill 结构的最好方式，是从外到内逐层放大。我们把这个过程称为"语义缩放"——就像用地图软件，从全局视图逐步放大到街道细节。

Level 1: 使用者视角（黑盒）

  从使用者角度，Skill 就是一个黑盒能力模块：

用户请求 → Agent → Skill → 结果

  在这个层级，你只需要知道三个关键信息：Skill 能做什么（能力描述）、什么时候会触发它（触发条件）、它会返回什么结果（输出格式）。

Level 2: 文件夹视角（目录结构）

  打开 Skill 目录，你会看到：

my-skill/ ├── SKILL.md # 必需：Skill 的核心文件（包含 Frontmatter 和 指令） ├── scripts/ # 可选：可执行脚本（例如 Python, Node.js） ├── references/ # 可选：参考文档（文本、CSV、JSON 等） ├── assets/ # 可选：静态资产（图片、图标等） └── templates/ # 可选：模板文件（输出模板、配置模板等）

重要提示：目录结构非常灵活。SKILL.md 是唯一必需的文件，其他目录都是可选的，根据 Skill 需要添加。不同 Skill 的资源目录直接与 SKILL.md 同级即可。

  在这个层级，你需要知道：SKILL.md 是 Skill 的核心，包含所有关键信息；scripts/ 等目录是可选的，用于存放辅助资源；目录结构是扁平的。

Level 3: 结构细节（内容组成）

  深入到 SKILL.md 内部，你会看到两个主要部分：

---
name: my-skill
description: 简明扼要地描述这个 Skill 能做什么以及应当在什么场景下被路由到
---

# Skill 主体内容 (Skill Body)

这里是组成该 Skill 核心心智模型的具体执行说明与流程规范...

  在这个层级，你需要知道：frontmatter（--- 之间的部分）用于路由和元数据，body（frontmatter 之后的部分）是 Skill 的主要内容。

图：从外到内看 Skill 的三层切片视角

  这个三层结构帮助我们理解：使用者视角关注能力和触发条件，文件夹视角理解文件组织方式，结构细节理解 frontmatter 和 body 的作用。

3.2 frontmatter：路由的入口 链接到标题

  frontmatter 是 SKILL.md 文件开头的 YAML 配置块，它是 Agent 路由系统的入口。它不是备注，而是决定 Skill 能否被发现和调用的关键。

  一个典型的 frontmatter 长这样：

---
name: lesson-interaction-architect
description: 基于用户大纲、课堂主题、课件笔记或交互灵感，专门设计用于网页端的单节课 HTML 交互体验架构。
---

  让我们理解每个字段的作用：

name 字段

  name 是 Skill 的唯一标识符，用于在系统中引用这个 Skill、在日志中追踪 Skill 的调用、在文档中说明 Skill 的依赖关系。

  命名规范包括：使用小写字母和连字符（kebab-case），名称应该简洁且有意义，避免使用通用词汇（如 “helper”、“util”）。

description 字段

  description 是 Skill 的能力描述，用于让 Agent 理解这个 Skill 能做什么、决定什么时候触发这个 Skill、在 Skill 列表中展示给用户。

  描述规范包括：使用清晰的动词开头（如 “Design”、“Generate”、“Analyze”），说明 Skill 的核心能力和适用场景，避免模糊或过于宽泛的描述。

  让我们通过一个对比来理解好的 description 和坏的 description：

description 质量对比

  frontmatter 的核心作用是：通过 name 和 description 让 Skill 可被发现，通过清晰的能力描述让 Skill 可被理解，通过语义匹配让 Skill 可被路由。

3.2.2 Skill 与相关概念的边界对比 链接到标题

  在 Agent 生态系统中，存在大量易混淆的专有名词。为了建立清晰的认知，我们需要从工程角度划定 Skill 与相邻概念的严格边界。

Skill 与相关概念的关系定位

  理解这些边界的关键在于：Skill 处于基础语言模型（大脑皮层）和工具接口（运动神经）之间，扮演着"可插拔的领域专家大脑"的角色。

  让我们通过一个具体例子来理解这些概念的协同工作：

场景：自动化代码审查

• System Prompt：设定 Agent 的基础身份和安全红线（“你是一个代码审查助手，必须遵守安全规范”）

• Skill：code-reviewer 提供审查流程和判断标准（“先检查安全漏洞，再检查代码规范，最后生成报告”）

• Tool：文件读取工具、代码分析工具、报告生成工具

• MCP Server：连接到 GitHub API，获取 Pull Request 信息

• Workflow：CI/CD 流水线触发审查任务，审查完成后自动评论

  在这个场景中，各个组件各司其职：System Prompt 确保基础规范，Skill 提供专业知识，Tool 提供执行能力，MCP Server 提供数据通道，Workflow 提供触发机制。它们共同构成了一个完整的自动化系统。

3.3 SKILL.md：能力的载体 链接到标题

  frontmatter 之后的部分，就是 Skill 的 body。这是 Skill 的主要内容，包含了 Skill 的执行逻辑、使用说明、示例等。

  body 的内容是 Markdown 格式的提示词，它会被 Agent 读取并执行。一个典型的 body 结构如下：

# Skill Name

## Goal
Brief description of what this skill does.

## Workflow
1. Step 1: Do something
2. Step 2: Do something else
3. Step 3: Return result

## Constraints
- Constraint 1
- Constraint 2

## Examples
Example usage...

  让我们理解每个部分的作用：

Goal 部分

  说明 Skill 的目标和核心能力。这部分应该简洁明了，一两句话说清楚，与 frontmatter 的 description 保持一致，强调 Skill 的核心价值。

Workflow 部分

  说明 Skill 的执行流程。这部分应该使用有序列表，清晰展示步骤，每个步骤都有明确的输入和输出，包含关键的决策点和分支逻辑。

Constraints 部分

  说明 Skill 的约束条件和注意事项。这部分应该列出必须遵守的规则，说明不应该做的事情，提供边界情况的处理方式。

Examples 部分

  提供 Skill 的使用示例。这部分应该给出真实的使用场景，展示输入和输出的格式，说明常见的使用模式。

  body 的核心作用是：通过清晰的 Workflow 让 Skill 可被执行，通过 Goal 和 Examples 让 Skill 可被理解，通过 Constraints 让 Skill 可被约束。

3.4 扁平化的可选资源目录 链接到标题

  除了核心的 SKILL.md 外，你还可以根据需要为 Skill 添加一些辅助资源目录。这些目录直接与 SKILL.md 处于同一层级（扁平结构）。

  资源目录的使用原则是：按需添加（不是所有 Skill 都需要额外的目录），保持简洁（只放必要的资源，避免冗余），清晰组织（使用不同的同级文件夹分类，便于管理）。

Skills 目录文件类型与作用

  一个复杂的 Skill 结构示例：

advanced-skill/ ├── SKILL.md # 核心指令文件 ├── scripts/ # 脚本文件夹 │ ├── process.py # 数据处理脚本 │ └── validate.js # 验证脚本 ├── references/ # 参考文档 │ ├── api-docs.md # API 文档 │ └── config.json # 配置参考 ├── assets/ # 静态资产 │ ├── logo.png # 图标 │ └── diagram.svg # 架构图 └── templates/ # 模板文件 └── output.md # 输出模板

  让我们通过一个完整的例子来理解这些文件是如何协同工作的：

场景：用户请求 “帮我生成一个技术文档”

执行流程：

1. 系统匹配 Skill：

   • 系统扫描所有 Skills 的 frontmatter
   • 找到 doc-generator Skill（假设）

2. 注入 SKILL.md：

   # Doc Generator Skill
   
   ## Workflow
   1. 读取 references/template-guide.md 了解模板规范
   2. 运行 scripts/analyze_code.py 分析代码结构
   3. 使用 assets/doc-template.md 作为模板
   4. 生成最终文档
   

3. LLM 执行 Workflow：

   步骤 1：读取参考文档

Read(file_path="/path/to/skill/references/template-guide.md")

返回：模板规范说明 链接到标题

步骤 2：执行分析脚本

Bash(command=“python3 /path/to/skill/scripts/analyze_code.py –input src/”)

返回：代码结构分析结果 链接到标题

步骤 3：读取模板

Read(file_path="/path/to/skill/assets/doc-template.md")

返回：文档模板内容 链接到标题

步骤 4：生成文档

LLM 根据模板和分析结果生成文档 链接到标题

Write(file_path=“docs/API.md”, content="[生成的文档内容]")

  通过这个完整的流程，我们可以看到：

1. SKILL.md 是"指挥官"：定义了整体流程和规则
2. references/ 是"知识库"：提供详细的参考信息
3. scripts/ 是"工具箱"：提供可执行的自动化脚本
4. assets/ 是"素材库"：提供模板和配置文件

  所有这些文件都不是由 Skill 系统直接执行的，而是由 LLM 通过 Tool 调用（Read、Bash、Write 等）来使用的。这种设计使得 Skills 既强大又灵活——你可以在不改变 LLM 的情况下，通过修改这些文件来改变 Skill 的行为。

第四部分：生态与边界 链接到标题

  在第三部分，我们理解了 Skill 的内部结构。现在，我们需要理解：Skill 从哪里来？它与其他技术有什么区别？我应该如何继续学习？这部分的目标是让你认识 Skill 的生态和边界，规划自己的学习路径。

4.1 Skill 的来源与生态 链接到标题

  Skill 不是凭空产生的，它有一个完整的生态系统。理解这个生态，可以帮助你找到需要的 Skill，也可以帮助你理解如何创建和分享 Skill。

Skill 的三大来源

Agent Skills 来源类型说明

  让我们详细了解每种来源：

1. 官方内置 Skill

  这些 Skill 是 Claude Code 系统自带的，无需安装即可使用。它们通常是最常用的开发任务（如测试、代码审查），核心的工作流支持（如 Git 操作、项目管理），系统级的能力扩展（如 Skill 创建、文档生成）。

  查看内置 Skill 的方式包括：在 Claude Code 中，系统会在提示中列出可用的 Skill；你可以通过自然语言询问：“有哪些可用的 Skill？”

2. 官方仓库 Skill

  这些 Skill 由 Anthropic 官方维护，存放在 GitHub 仓库中。它们通常是经过验证的高质量 Skill，遵循最佳实践的示例，社区贡献后经过审核的 Skill。

  获取官方仓库 Skill 的方式包括：访问 [https://github.com/anthropics/skills/tree/main]，克隆仓库到本地，按照文档说明安装和使用。

3. 社区生态 Skill

  这些 Skill 由第三方开发者创建和分享。它们通常是针对特定领域的专业 Skill，实验性的新功能，个人或团队的定制化 Skill。

  获取社区 Skill 的方式包括：使用 find-skills Skill 搜索，在 GitHub 上搜索相关关键词，在社区论坛和讨论组中寻找推荐。或者类似 https://skillsmp.com/ 这类的网站都是可以查找的，但是需要注意安全性！

4.2 Skills vs Function Calling vs MCP 链接到标题

  在 AI 能力扩展领域，除了 Agent Skills，还有 Function Calling 和 MCP（Model Context Protocol）。很多人会问：它们有什么区别？我应该选择哪一个？

  让我们通过一个全面的对比表格来理解：

三种能力扩展方式对比

三种技能结构对比（Function Calling vs MCP vs Agent Skills）

图：三种能力扩展方式角逐场

  让我们通过具体场景来理解如何选择：

场景一：快速原型开发

  假设你正在验证一个新的产品想法，需要快速搭建一个 AI 助手来处理用户反馈。在这个阶段，你最关心的是速度和灵活性，而不是完美的工程实现。

  这时候，Agent Skills 是最佳选择。原因很简单：你只需要用 Markdown 描述你想要的能力，不需要写复杂的代码。比如，你可以创建一个"用户反馈分析"Skill，描述如何提取关键信息、分类问题类型、生成摘要报告。整个过程可能只需要30分钟，而如果用 Function Calling，你可能需要花几个小时写代码、调试、测试。

  更重要的是，当你发现流程需要调整时（比如增加一个情感分析步骤），你只需要修改 Markdown 文档，而不需要重新编译和部署代码。这种灵活性在快速迭代阶段非常宝贵。

场景二：生产系统集成

  现在假设你的产品已经成熟，需要将 AI 能力集成到现有的企业级系统中。这个系统可能有严格的安全要求、性能指标、错误处理机制。

  在这种情况下，Function Calling 或 MCP 更合适。为什么？因为生产环境需要的不仅仅是"能用"，还需要"稳定、可控、可监控"。Function Calling 让你可以精确控制每个步骤的执行，捕获每个可能的异常，记录详细的日志。MCP 则提供了标准化的协议，让你可以在不同的 AI 系统之间复用能力。

  举个具体例子：如果你要在银行系统中集成 AI 能力来审核贷款申请，你不能接受任何不确定性。每个决策步骤都需要有明确的输入、输出、错误处理。这时候，Function Calling 的确定性执行就显得至关重要。

场景三：非技术人员使用

  你的团队中有产品经理、运营人员、内容创作者，他们也想要扩展 AI 的能力，但他们不会编程。比如，产品经理想要创建一个"需求分析"Skill，运营人员想要创建一个"活动策划"Skill。

  这时候，Agent Skills 是唯一的选择。因为它不需要编程知识，只需要清晰地描述"我想要 AI 做什么"。产品经理可以用自然语言写出需求分析的流程：收集用户反馈 → 提取核心需求 → 评估优先级 → 生成需求文档。整个过程就像写一份工作流程文档，而不是写代码。

  这种低门槛的特性，让 AI 能力的扩展不再是技术团队的专属，而是整个团队都可以参与的事情。这对于快速响应业务需求、提升团队效率非常有价值。

场景四：复杂工作流

  假设你需要实现一个完整的代码审查流程：检查代码风格 → 运行静态分析 → 执行单元测试 → 生成审查报告 → 如果发现问题，提供修复建议 → 验证修复后的代码。这个流程有多个步骤，有分支逻辑，还需要根据中间结果动态调整。

  这种复杂工作流，Agent Skills 更有优势。因为你可以用自然语言描述整个流程，包括分支逻辑、异常处理、动态调整。而如果用 Function Calling，你需要写大量的条件判断、循环控制、状态管理代码，维护成本会很高。

  更重要的是，当业务需求变化时（比如增加一个安全扫描步骤），你只需要在 Skill 中增加一段描述，而不需要重构整个代码结构。这种灵活性在复杂工作流中尤为重要。

场景五：精确控制

  最后，假设你需要实现一个金融交易系统，每笔交易都涉及资金转移、账户更新、风险检查。这种场景下，任何不确定性都可能导致严重后果。

  这时候，Function Calling 是必选项。因为它提供了确定性执行：给定相同的输入，一定会得到相同的输出。每个步骤都是精确可控的，不会因为 AI 的"理解偏差"而产生意外结果。

  在这种场景下，Agent Skills 的灵活性反而成了劣势。你不希望 AI"灵活地理解"你的意图，你希望它"精确地执行"你的指令。这就是为什么在金融、医疗、安全等关键领域，Function Calling 仍然是主流选择。

4.3 常见风险与避坑指南 链接到标题

  随着 Agent Skills 被大规模部署到生产环境，各种特有的失效模式开始暴露。理解这些风险不仅有助于排障，更是在早期架构设计中进行防御的关键。

Agent Skills 常见风险与解决策略

新手最容易踩的坑：将 Skill 当作传统函数库对待，试图在 Markdown 中编写复杂的伪代码算法；或是在 description 字段里写上一部小长篇小说，导致整个系统的路由机制彻底瘫痪。

  正确的做法是：遵循最简单的文件约定，使用清晰的动名词结构（如 analyzing-spreadsheets 或 testing-code）对文件夹进行命名，在元数据中保持简练而富含高频触发关键词的描述。

风险详解一：路由瘫痪与技能打架

  这是最常见的问题。当你的 Skill 库中有几十个甚至上百个 Skill 时，如果它们的 description 描述词典存在严重的语义重叠或边界极度模糊不清，Agent 就会陷入"选择困难症"。

  典型症状包括：用户说"帮我处理这个文件"，Agent 在 file-processor、document-analyzer、data-extractor 之间反复犹豫；或者针对编程任务错误唤醒了财务审批技能。

  解决方案是强制重写并审查所有技能描述，大幅增加具体的负向触发器（防误触）。例如：

description: |
  当用户明确要求提取文本、表格数据或处理 PDF 文档文件结构时，应路由到本技能。
  绝对、严禁将此技能用于对简单的纯文本文件或代码仓库中的项目进行扫描和处理（防误触）。

风险详解二：上下文隐性恶性膨胀

  这个问题往往在系统运行一段时间后才会暴露。Skill 内部的架构设计极度不良，毫无节制地指挥 Agent 利用文件读取工具一次性地吞入巨大的 references/ 业务库文件，而没有任何中间摘要与数据提取过滤环节。

  解决方案是在技术规范上强制实施严格的主指令 5000 Token 上限约束机制；在技能说明中明确指导 Agent 优先使用底层的 Bash grep 过滤命令或专门的数据提取过滤脚本引擎，绝对禁止盲目全量读取大文件入内存。

4.4 适用场景判断 链接到标题

  通过前面五个场景的分析，我们可以提炼出一个实用的判断框架。这个框架不是简单的"用 A 还是用 B"，而是帮助你理解在什么情况下，哪种技术的优势最明显。

图：业务场景技术选型坐标系

判断维度一：确定性要求

  首先问自己：这个任务对确定性的要求有多高？

  如果任务需要绝对的确定性（如金融交易、数据库操作），那么 Function Calling 是首选。因为它提供了代码级的精确控制，每个步骤都是可预测的。

  如果任务允许一定的灵活性（如文档生成、需求分析），那么 Agent Skills 更合适。因为它可以根据上下文动态调整，不需要预先定义所有可能的分支。

  举个例子：生成测试用例这个任务，不同的代码可能需要不同的测试策略。用 Agent Skills，AI 可以根据代码特点灵活调整测试方案。而如果用 Function Calling，你需要预先定义所有可能的测试策略，这会非常复杂。

判断维度二：迭代速度要求

  第二个问题：你需要多快地迭代和调整？

  如果你处于快速验证阶段，需要频繁调整流程，那么 Agent Skills 的优势明显。修改 Markdown 文档比修改代码快得多，而且不需要重新编译和部署。

  如果你的流程已经稳定成熟，不需要频繁调整，那么 Function Calling 的工程化优势更重要。虽然初期开发成本高，但长期维护成本低，而且性能和稳定性更好。

  这就像建筑行业：快速搭建原型时用木板和胶水（Agent Skills），正式建造时用钢筋混凝土（Function Calling）。

判断维度三：团队技术能力

  第三个问题：谁会使用和维护这个能力？

  如果使用者包括非技术人员（产品经理、运营、内容创作者），那么 Agent Skills 是唯一可行的选择。因为它不需要编程知识，只需要清晰的逻辑思维。

  如果使用者都是专业开发者，那么可以根据具体需求选择。简单任务用 Agent Skills 提高效率，复杂任务用 Function Calling 保证质量。

  这里有个有趣的现象：很多技术团队一开始倾向于用 Function Calling（因为"更专业"），但后来发现 Agent Skills 在很多场景下更高效。这是因为不是所有问题都需要代码级的精确控制。

判断维度四：集成复杂度

  第四个问题：这个能力需要与多少外部系统集成？

  如果需要跨平台、跨系统集成，那么 MCP 的标准化协议优势明显。它定义了统一的接口规范，让不同的 AI 系统可以无缝对接。

  如果只是单一系统内部使用，那么 Agent Skills 或 Function Calling 都可以。选择哪个取决于前面三个维度的判断。

  MCP 的价值在于"一次实现，到处使用"。如果你的能力需要在多个 AI 系统中复用（比如 Claude、GPT、本地模型），那么投入时间实现 MCP 是值得的。

组合使用策略

  在实际项目中，这三种技术并不是互斥的。一个成熟的 AI 系统，往往会组合使用它们：

  高层工作流用 Agent Skills：比如"代码审查"这个大流程，用 Skill 来描述整体逻辑。这样可以保持灵活性，方便调整流程。

  底层精确操作用 Function Calling：比如"执行单元测试"这个具体步骤，用 Function Calling 来保证确定性。这样可以避免因为 AI 理解偏差导致的错误。

  跨平台能力用 MCP：比如"代码分析"这个通用能力，用 MCP 实现标准化接口。这样可以在不同的 AI 系统中复用。

  这种组合使用的策略，可以让你在灵活性、确定性、可维护性之间找到最佳平衡点。

第五部分实战对比演示：获取天气信息 链接到标题

  理论对比看完了，现在让我们通过一个真实的代码示例，直观感受 Function Calling 和 Agent Skills 的区别。我们选择一个经典任务：获取天气信息。

  这个任务看似简单，但足以体现两种技术的核心差异：代码量、灵活性、维护成本、执行确定性。

任务说明

  我们要实现一个能力：根据用户的请求，获取指定城市的天气信息。用户可能会这样问：

• “北京今天天气怎么样？”

• “帮我查一下上海的天气”

• “明天适合出门吗？"（需要根据当前位置获取天气）

  让我们分别用 Function Calling 和 Agent Skills 来实现，然后对比它们的差异。

方案一：Function Calling 实现

  使用 Function Calling，我们需要完成四个步骤：定义函数签名、实现函数逻辑、调用 OpenAI API、处理返回结果。

步骤一：定义函数签名

  首先，我们需要用 JSON Schema 定义函数的签名，告诉 AI 这个函数接受什么参数、返回什么结果。

# 定义 get_weather 函数的签名
weather_function = {
    "type": "function",
    "function": {
        "name": "get_weather",
        "description": "获取指定城市的天气信息",
        "parameters": {
            "type": "object",
            "properties": {
                "location": {
                    "type": "string",
                    "description": "城市名称，例如：北京、上海"
                },
                "unit": {
                    "type": "string",
                    "enum": ["celsius", "fahrenheit"],
                    "description": "温度单位"
                }
            },
            "required": ["location"]
        }
    }
}

  这个定义看起来很严谨，但也很繁琐。每个参数都需要明确类型、描述、是否必需。如果需求变化（比如增加"空气质量"参数），你需要修改这个 Schema。

步骤二：实现函数逻辑

  接下来，我们需要实现真正获取天气的函数。这里我们用一个简化的实现（实际项目中需要调用真实的天气 API）。

import json
import random

def get_weather(location, unit="celsius"):
    """
    获取指定城市的天气信息

    Args:
        location: 城市名称
        unit: 温度单位（celsius 或 fahrenheit）

    Returns:
        JSON 格式的天气信息
    """
    # 模拟天气数据（实际应该调用真实的天气 API）
    weather_data = {
        "location": location,
        "temperature": random.randint(15, 30),
        "unit": unit,
        "condition": random.choice(["晴天", "多云", "小雨", "阴天"]),
        "humidity": random.randint(40, 80),
        "wind_speed": random.randint(5, 20)
    }

    return json.dumps(weather_data, ensure_ascii=False)

  这段代码很标准，但也很"工程化”。你需要处理参数验证、错误处理、返回格式等细节。

步骤三：调用 OpenAI API

  现在，我们需要将函数注册到 OpenAI API，并处理用户请求。

import os
from dotenv import load_dotenv
from openai import OpenAI

# 从项目根目录的 .env 文件加载环境变量（DEEPSEEK_API_KEY 等）
load_dotenv()

# 测试连接
client = OpenAI(
    api_key=os.environ.get("DEEPSEEK_API_KEY"),
    base_url="https://api.deepseek.com"
)
model="deepseek-chat"

def chat_with_weather(user_message):
    """
    处理用户的天气查询请求
    """
    # 第一次调用：让 AI 决定是否需要调用函数
    response = client.chat.completions.create(
        model=model,
        messages=[{"role": "user", "content": user_message}],
        tools=[weather_function],
        tool_choice="auto"
    )

    # 检查 AI 是否决定调用函数
    if response.choices[0].message.tool_calls:
        tool_call = response.choices[0].message.tool_calls[0]
        function_args = json.loads(tool_call.function.arguments)

        # 调用我们的函数
        function_response = get_weather(
            location=function_args.get("location"),
            unit=function_args.get("unit", "celsius")
        )

        # 第二次调用：将函数结果传回给 AI
        second_response = client.chat.completions.create(
            model=model,
            messages=[
                {"role": "user", "content": user_message},
                response.choices[0].message,
                {
                    "role": "tool",
                    "tool_call_id": tool_call.id,
                    "content": function_response
                }
            ]
        )

        return second_response.choices[0].message.content
    else:
        return response.choices[0].message.content

  注意这里的复杂度：我们需要调用 API 两次（第一次让 AI 决定调用函数，第二次将结果传回），需要处理 tool_calls、解析参数、构造消息历史。这些都是"必要的复杂度"，但也增加了维护成本。

步骤四：测试运行

# 测试
user_query = "北京今天天气怎么样？"
result = chat_with_weather(user_query)
print(result)

  Function Calling 的优势在于：执行是确定性的，给定相同的输入，一定会调用相同的函数，返回结构化的数据。但代价是：需要写大量的代码，需要处理很多技术细节。

方案二：Agent Skill 实现

  现在让我们看看用 Agent Skills 如何实现同样的功能。你会发现，代码量大幅减少，而且更容易理解和维护。

步骤一：创建 SKILL.md

  我们只需要创建一个 Markdown 文件，用自然语言描述这个能力。

---
name: get-weather
description: 获取指定城市的天气信息。在用户询问当地的天气、实时气温或出门户外状况时使用（触发）。
---

# 获取天气信息 (Get Weather Information)

## Goal
针对用户询问的任何城市天气，提取其诉求从而提供能够给到帮助信息的准确天气预报结果集。

## Workflow
1. **提取位置信息 (Extract location)**: 从用户的请求大意中识别出城市名称
   - 如果用户说"今天"或"这里"，尝试从对话上下文中推断出其具体地理位置
   - 如果用户输入的位置包含歧义或不明确，请主动向用户询问以确认精准地点

2. **获取天气数据 (Fetch weather data)**: 调取当地当前最新的天气气象信息
   - 温度情况数据 (若无指定，默认使用摄氏度展示)
   - 天气云图与降水状况 (晴天、多云天气、下雨等)
   - 气象局播报的相对湿度和风速数据
   - 实时空气质量指数信息 (前提是调用的数据源支持呈现)

3. **格式化响应 (Format response)**: 以自然人说话、易读亲和的对话口吻展示综合天气信息
   - 对于一般简单的查询：只提供极度核心的基础信息 (气温 + 天气基本状况)
   - 对于相对细节的查询：向用户进一步补充湿度走势、风速以及相关的外出建议
   - 被问及户外相关问题时：结合当前恶劣或良好天气，主动给出户外活动的可行性与意见

4. **异常边界处理 (Handle edge cases)**:
   - 若系统内外部因素导致天气数据无法获取：向用户解释无果的客观原因，并建议其他获取方法
   - 若用户询问关于未来的长远天气预测：及时澄清当前服务能力仅包含提供实时的天气数据
   - 若用户正在比对多个不同城市环境：分别为每个不同城市分头拉取数据，随后整合给出一份横向对比报告

## Constraints
- 除非用户在请求中明确要求使用"华氏度"为口径，否则强制一律默认使用摄氏度呈现
- 严格保证只对外提供该需求时间的最新天气数据，绝对不做未经授权的长时间未来预测
- 遇到诸如强沙尘暴/大雾等代表空气环境非常差的天气，即便用户没查，强制要求主动发声提醒
- 全局把控输出的结果文字量，务必保证回复内容高度精炼而不失关键数据信息量

## Examples

**Example 1: 简单的单次查询**
User: "北京今天天气怎么样？"
Response: "北京今天晴天，温度 25°C，空气质量良好，适合外出活动。"

**Example 2: 多城市对比查询**
User: "帮我对比一下北京和上海的天气"
Response: "北京：晴天，25°C；上海：多云，28°C。上海温度更高一些，但两地都适合出行。"

**Example 3: 带有隐喻场景意图的延伸活动建议**
User: "明天适合出门旅游吗？"
Response: "根据当前天气（明天晴天，25°C），这应该是一个非常棒的天气，很适合出远门呼吸新鲜空气。不过中午时分紫外线偏强，建议临走前带上一顶鸭舌帽或者防晒霜。"

  就这样，我们完成了！整个 Skill 只有一个 Markdown 文件，大约 50 行，而且全部是自然语言描述。

步骤二：自然语言调用

  使用这个 Skill 非常简单，用户只需要自然地提问：

用户：“北京今天天气怎么样？” Agent：识别到 get-weather Skill Agent：按照 Workflow 执行 Agent：返回结果

5.1 openai的框架调用 链接到标题

# 导入的本地的agent_skills_engine.py文件里面的逻辑
from agent_skills_engine import AgentSkillsEngine

# 初始化引擎（指向你的 Skills 目录）
engine = AgentSkillsEngine(skills_dir="./skills")

# 测试 1: 天气查询
print("=" * 60)
print("测试 1: 天气查询")
print("=" * 60)
result, skill = engine.process("北京今天天气怎么样？")
print(f" AI 回复: {result}")
print(f" 使用的 Skill: {skill}\n")

# 测试 2: 多城市对比
print("=" * 60)
print("测试 2: 多城市对比")
print("=" * 60)
result, skill = engine.process("帮我对比一下北京和上海的天气")
print(f" AI 回复: {result}")
print(f" 使用的 Skill: {skill}\n")

# 测试 3: 无法匹配的请求
print("=" * 60)
print("测试 3: 无法匹配的请求")
print("=" * 60)
result, skill = engine.process("帮我写一首诗")
print(f" AI 回复: {result}")
print(f" 使用的 Skill: {skill}\n")

# 列出所有可用的 Skills
print("=" * 60)
print("所有可用的 Skills:")
print("=" * 60)
for skill_name in engine.list_skills():
    print(f"- {skill_name}")

5.2 langchain的框架调用 链接到标题

# 导入的本地的agent_skills_engine.py文件里面的逻辑
from agent_skills_engine_langchain import AgentSkillsEngine

# 初始化引擎（指向你的 Skills 目录）
engine = AgentSkillsEngine(skills_dir="./skills")

# 测试 1: 天气查询
print("=" * 60)
print("测试 1: 天气查询")
print("=" * 60)
result, skill = engine.process("北京今天天气怎么样？")
print(f" AI 回复: {result}")
print(f" 使用的 Skill: {skill}\n")

# 测试 2: 多城市对比
print("=" * 60)
print("测试 2: 多城市对比")
print("=" * 60)
result, skill = engine.process("帮我对比一下北京和上海的天气")
print(f" AI 回复: {result}")
print(f" 使用的 Skill: {skill}\n")

# 测试 3: 无法匹配的请求
print("=" * 60)
print("测试 3: 无法匹配的请求")
print("=" * 60)
result, skill = engine.process("帮我写一首诗")
print(f" AI 回复: {result}")
print(f" 使用的 Skill: {skill}\n")

# 列出所有可用的 Skills
print("=" * 60)
print("所有可用的 Skills:")
print("=" * 60)
for skill_name in engine.list_skills():
    print(f"- {skill_name}")

对比总结

  现在让我们对比一下两种实现方式的关键差异：

Function Calling vs Agent Skills 实现成本对比

  通过这个实战对比，我们可以清晰地看到：

  Function Calling 的优势： 执行确定性高，适合关键业务逻辑；返回结构化数据，便于后续处理；性能可控，可以精确优化。

  Agent Skills 的优势： 开发速度快，代码量少；维护成本低，易于迭代；灵活性高，可以处理多种场景；门槛低，非技术人员也能创建。

  选型建议： 如果你的任务需要精确控制（如金融交易、数据库操作），选择 Function Calling。如果你的任务需要灵活处理（如信息查询、内容生成），选择 Agent Skills。如果你的团队包括非技术人员，优先考虑 Agent Skills。如果你处于快速迭代阶段，先用 Agent Skills 验证，稳定后再考虑是否需要 Function Calling。

  记住：这两种技术不是互斥的，而是互补的。在实际项目中，你可以用 Agent Skills 处理高层工作流，用 Function Calling 处理底层精确操作，发挥各自的优势。

5.3 四阶段学习路径 链接到标题

  学完本课程，你已经完成了 Agent Skills 学习的第一阶段。但这只是开始，真正的成长路径是从"会用"一路走到"独立创造和持续优化"。让我们详细规划一下这条路径，帮助你明确每个阶段的目标和方法。

图：Agent Skills 四阶段学习路径

阶段一：体验（30分钟）——建立初始认知

  这个阶段的核心目标是快速建立对 Agent Skills 的整体认知，理解它是什么、为什么需要它、它能解决什么问题。

  在这个阶段，你应该能够回答三个基本问题：第一，Skill 的三大特性是什么？（可发现、可执行、可复用）第二，Skill 和 Prompt 有什么本质区别？（Skill 是结构化的能力模块，Prompt 是一次性的指令）第三，什么样的任务适合用 Skill？（需要结构化流程、多步骤执行、可复用的任务）

  如何验证你已经完成这个阶段？试着向一个不了解 Agent Skills 的同事解释它是什么。如果你能用简单的语言说清楚，并且能举出一两个实际例子，那就说明你已经建立了初始认知。

  这个阶段的学习资源包括：本课程的第一、二部分，以及 Claude Code 的官方文档。不要急于深入细节，先建立整体框架。就像学习一门新语言，先掌握基本句型，再学习语法规则。

阶段二：理解（2小时）——深入结构和机制

  这个阶段的核心目标是理解 Skill 的内部结构和调用机制，从"知道它能做什么"到"理解它是怎么做的"。

  在这个阶段，你需要深入理解三个关键概念：第一，frontmatter 的作用是什么？它不是简单的备注，而是 Agent 路由系统的入口，决定了 Skill 能否被发现和调用。第二，Skill 的 body 是如何组织的？它包含 Goal、Workflow、Constraints、Examples 等部分，每个部分都有明确的作用。第三，Agent 是如何决定调用哪个 Skill 的？它会经历识别任务、判断能力边界、匹配 Skill、执行、整合输出这五个步骤。

  如何验证你已经完成这个阶段？找一个现有的 Skill（比如 test-driven-development），阅读它的 SKILL.md 文件，然后尝试回答：这个 Skill 适合什么任务？它的执行流程是什么？它有哪些约束条件？如果你能清晰地回答这些问题，说明你已经理解了 Skill 的结构。

  这个阶段的学习资源包括：本课程的第三、四部分，以及官方 Skill 仓库中的示例代码。建议你至少阅读 3-5 个不同类型的 Skill，观察它们的共同点和差异。这就像学习写作，多读优秀作品才能理解好文章的结构。

阶段三：设计（4小时）——掌握设计原理

  这个阶段的核心目标是理解 Skill 的设计原理和最佳实践，从"理解别人的 Skill"到"能够设计自己的 Skill"。

  在这个阶段，你需要掌握三个核心能力：第一，如何写好 description？一个好的 description 应该清晰地说明 Skill 的能力边界、适用场景、触发条件。它不是简单的功能描述，而是帮助 Agent 理解"什么时候应该调用我"。第二，如何设计 Workflow？一个好的 Workflow 应该有清晰的步骤、明确的输入输出、合理的分支逻辑。它不是流水账，而是可执行的流程指南。第三，如何设置 Constraints？一个好的 Constraints 应该明确"必须做什么"和"不能做什么"，帮助 Agent 避免常见错误。

  如何验证你已经完成这个阶段？尝试设计一个简单的 Skill，比如"会议纪要生成"或"代码注释补充"。写出完整的 frontmatter 和 body，然后请有经验的同事或社区成员帮你审查。如果他们认为你的设计清晰、合理、可执行，说明你已经掌握了基本的设计能力。

  这个阶段的学习资源包括：《Skill 设计最佳实践》文档、skill-creator-pro Skill（它可以帮助你创建高质量的 Skill）、社区中的优秀 Skill 案例。建议你加入 Agent Skills 的讨论社区，观察其他人是如何设计和优化 Skill 的。

阶段四：创造（持续）——独立创建和优化

  这个阶段的核心目标是独立创建满足实际需求的 Skill，并根据反馈持续优化。这不是一个有明确终点的阶段，而是一个持续实践和成长的过程。

  在这个阶段，你需要培养三个关键习惯：第一，从实际需求出发。不要为了创建 Skill 而创建 Skill，而是从你的日常工作中发现重复性任务、复杂流程、团队协作痛点，然后思考如何用 Skill 来解决。第二，快速迭代。第一版 Skill 不需要完美，先让它能用，然后根据实际使用情况不断优化。就像软件开发中的敏捷方法，小步快跑比一次性做到完美更有效。第三，收集反馈。让其他人使用你的 Skill，观察他们遇到的问题，听取他们的建议。最好的 Skill 往往是在实际使用中打磨出来的。

  如何验证你已经进入这个阶段？当你能够：独立创建一个 Skill 并在实际工作中使用；根据使用反馈优化 Skill，让它更好用；将你的 Skill 分享给团队或社区，帮助其他人解决类似问题。这时候，你就已经从"学习者"转变为"创造者"了。

  这个阶段的学习资源包括：《Skill 开发进阶》文档、官方 Skill 贡献指南、社区讨论和反馈。更重要的是，你需要建立自己的 Skill 库，记录每个 Skill 的设计思路、使用场景、优化历程。这个库不仅是你的作品集，也是你持续学习的记录。

跨阶段的学习建议

  在整个学习过程中，有几个建议可以帮助你更高效地成长：

  第一，不要跳过阶段。很多人急于创建自己的 Skill，但如果没有经过"体验"和"理解"阶段，创建出来的 Skill 往往质量不高。就像学习编程，如果不理解基本语法就去写复杂程序，结果往往是事倍功半。

  第二，多看优秀案例。每个阶段都应该阅读和分析优秀的 Skill。看别人是如何描述能力边界的、如何设计执行流程的、如何处理边界情况的。这就像学习写作，多读好文章才能写出好文章。

  第三，实践是最好的老师。不要只是阅读文档和教程，要动手尝试。即使是简单的 Skill，自己动手创建一遍，收获也会比只看文档大得多。

  第四，加入社区。Agent Skills 是一个快速发展的领域，新的最佳实践、新的使用场景不断涌现。加入社区，你可以及时了解最新动态，也可以从其他人的经验中学习。

  记住：学习 Agent Skills 不是一蹴而就的，而是一个持续实践和优化的过程。每个阶段都有明确的目标和检查点，但不要给自己太大压力。按照自己的节奏，稳步前进，你一定能够掌握这项技能。

附录 链接到标题

附录A：常见问题解答 链接到标题

  在学习和使用 Agent Skills 的过程中，你可能会遇到一些常见问题。这里我们整理了最常被问到的问题，并提供详细的解答。

Q1: Skill 和内置斜杠命令（如 /commit）有什么区别？

  这是一个非常常见的混淆点。让我们先明确一个概念：内置斜杠命令不是 Agent Skills。

  内置斜杠命令（如 /commit、/help、/clear）是 Claude Code 系统自带的功能，它们是硬编码在系统中的，由系统直接处理。你可以把它们理解为"系统级快捷方式"，就像操作系统的快捷键一样。

  而 Agent Skills 是可安装的能力模块，通过 SKILL.md 文件定义。它们的主要区别在于：

  实现方式不同：斜杠命令是系统代码实现的，Skill 是通过 Markdown 文档定义的。这意味着你可以创建和修改 Skill，但不能修改斜杠命令。

  调用方式不同：斜杠命令需要用户显式输入（如 /commit），而 Skill 是由 Agent 根据任务自动匹配和调用的。用户不需要知道 Skill 的名字，只需要描述任务。

  扩展性不同：斜杠命令的数量是固定的，由系统维护。而 Skill 可以无限扩展，任何人都可以创建新的 Skill。

  举个例子：当你说"帮我提交代码"，Agent 可能会调用 Git 相关的 Skill，而不是 /commit 命令。但如果你直接输入 /commit，系统会执行内置的提交命令。

Q2: 我可以修改官方内置的 Skill 吗？

  这个问题涉及到 Skill 的管理和定制化。简短的答案是：不建议直接修改官方内置的 Skill。

  原因很简单：官方内置的 Skill 是系统的一部分，直接修改可能会导致系统不稳定，而且在系统更新时你的修改可能会被覆盖。这就像你不应该直接修改操作系统的核心文件一样。

  但这不意味着你不能定制化。如果你需要定制化，有几个更好的方法：

  方法一：创建新的 Skill。参考官方 Skill 的设计，创建一个新的 Skill 来满足你的特定需求。这个新 Skill 可以与官方 Skill 共存，Agent 会根据任务特点选择最合适的那个。

  方法二：在项目中添加自定义 Skill。在你的项目目录中创建 .claude/skills/ 目录，把你的自定义 Skill 放在这里。这样可以实现项目级的定制化，不影响全局配置。

  方法三：向官方提交改进建议。如果你发现官方 Skill 有可以改进的地方，可以在 GitHub 上提交 Issue 或 Pull Request。这样不仅能帮助你，也能帮助整个社区。

Q3: Skill 的 frontmatter 可以有哪些字段？

  这是一个关于 Skill 结构的技术问题。frontmatter 的设计哲学是：灵活但有核心。

  核心字段只有两个，它们是必需的：

  name：Skill 的唯一标识符。这个字段用于在系统中引用 Skill，在日志中追踪调用，在文档中说明依赖关系。命名规范是使用小写字母和连字符（kebab-case），比如 test-driven-development。

  description：Skill 的能力描述。这个字段是 Agent 路由系统的核心依据，决定了什么时候会触发这个 Skill。一个好的 description 应该清晰地说明 Skill 的能力边界和适用场景。

  除了这两个核心字段，你可以根据需要添加其他字段。但要注意：添加的字段必须是 Agent 能够理解的。如果你添加了一个自定义字段，但 Agent 不知道如何使用它，那这个字段就只是注释，不会影响 Skill 的行为。

  常见的可选字段包括：version（版本号）、author（作者）、tags（标签）等。但这些字段主要用于文档和管理，不影响 Skill 的核心功能。

Q4: 如何判断一个 Skill 的质量？

  这是一个非常实用的问题。评估 Skill 质量，可以从三个维度入手，这三个维度正好对应 Skill 的三大特性：

  可发现性维度：这个 Skill 容易被 Agent 发现和匹配吗？

  检查 description 是否清晰。一个好的 description 应该让 Agent 能够准确判断"什么时候应该调用我"。如果 description 太模糊（如"帮助测试"），Agent 可能不知道什么时候该用它。如果 description 太宽泛（如"处理所有代码相关任务"），可能会导致误触发。

  检查触发条件是否明确。Skill 应该清楚地说明它适合什么场景、不适合什么场景。这样可以避免 Agent 在不合适的时候调用它。

  可执行性维度：这个 Skill 的执行流程清晰吗？

  检查 Workflow 是否完整。一个好的 Workflow 应该有清晰的步骤、明确的输入输出、合理的分支逻辑。如果 Workflow 太简单（只有一两个步骤），可能不需要单独做成 Skill。如果 Workflow 太复杂（有很多嵌套的条件判断），可能需要拆分成多个 Skill。

  检查 Constraints 是否合理。Constraints 应该明确"必须做什么"和"不能做什么"，帮助 Agent 避免常见错误。但 Constraints 不应该过于严格，否则会限制 Skill 的灵活性。

  可复用性维度：这个 Skill 可以在不同场景下复用吗？

  检查 Skill 是否过于具体。如果一个 Skill 只能用于某个特定项目、特定文件，那它的复用价值就很低。好的 Skill 应该是通用的，可以在不同项目、不同场景下使用。

  检查 Skill 是否易于维护。如果 Skill 的逻辑很复杂，文档很少，那么后续维护会很困难。好的 Skill 应该有清晰的文档、合理的结构、易于理解的逻辑。

Q5: 我应该什么时候创建自己的 Skill？

  这是一个关于时机的问题。创建 Skill 需要投入时间和精力，所以要确保这个投入是值得的。

  以下几种情况，值得考虑创建 Skill：

  情况一：重复性任务。如果你发现自己经常做同样的事情，而且每次都要重新解释给 AI 听，那就值得创建一个 Skill。比如，你每周都要生成项目进度报告，每次都要说明报告的格式、内容、数据来源。这时候创建一个"项目进度报告"Skill，可以大大提高效率。

  情况二：复杂流程。如果某个任务有多个步骤、有分支逻辑、需要处理各种边界情况，那么用 Skill 来固化这个流程是值得的。比如，代码审查流程包括检查风格、运行测试、分析性能、生成报告等多个步骤，用 Skill 可以确保每次都不会遗漏。

  情况三：团队协作。如果你的工作流程需要团队其他成员也能使用，那么创建 Skill 可以实现知识共享。比如，你总结出了一套需求分析的方法，创建成 Skill 后，团队其他成员也可以使用，不需要你每次都手把手教。

  情况四：现有 Skill 不满足需求。如果你尝试了现有的 Skill，发现它们都不能完全满足你的需求，那么创建一个新的 Skill 是合理的。但在创建之前，建议先在社区搜索一下，看看是否有类似的 Skill 可以参考或改进。

  反过来，以下情况不建议创建 Skill：

  一次性任务：如果这个任务只做一次，创建 Skill 的成本大于收益。

  过于简单的任务：如果任务只有一两个步骤，直接用 Prompt 就够了，不需要 Skill。

  高度定制化的任务：如果任务只适用于某个特定场景，复用价值很低，那么创建 Skill 的意义不大。

附录B：推荐学习资源 链接到标题

  学习 Agent Skills 是一个持续的过程，这里我们整理了一些推荐的学习资源，帮助你在不同阶段找到合适的学习材料。

官方文档

  官方文档是最权威、最准确的学习资源。建议你从这里开始：

  Claude Code 官方文档：这是 Claude Code 的完整文档，包括安装、配置、使用、最佳实践等内容。你可以在 Anthropic 官网找到最新版本。

  Agent Skills 设计规范与指南：这份指南详细说明了如何设计高质量的 Skill，包括 frontmatter 的写法、Workflow 的设计、Constraints 的设置等。你可以在官方仓库的 spec 规范文档，或查阅官方支持文档：How to create custom skills 中找到具体的实现细节。

  Skill 贡献指南：如果你想要向官方仓库贡献 Skill，这份指南会告诉你如何提交、如何审查、如何发布。地址是 [https://github.com/anthropics/skills/blob/main/CONTRIBUTING.md]

示例代码

  阅读优秀的示例代码是学习的最佳方式之一。推荐以下资源：

  官方 Skill 仓库：[https://github.com/anthropics/skills/tree/main] 包含了所有官方维护的 Skill。这些 Skill 都经过了严格的审查，代码质量高，文档完善，是学习的最佳范例。

  社区 Skill 集合：在 GitHub 上搜索 “claude-code-skills” 标签，可以找到很多社区贡献的 Skill。这些 Skill 覆盖了各种不同的领域和场景，可以给你很多灵感。

  建议你至少阅读 5-10 个不同类型的 Skill，观察它们的共同点和差异。特别关注那些 star 数量多、文档完善的 Skill，它们往往代表了社区认可的最佳实践。

社区资源

  加入社区可以让你及时了解最新动态，也可以从其他人的经验中学习：

  Claude Code 讨论区：官方论坛是提问、讨论、分享经验的好地方。你可以在这里找到很多实用的技巧和解决方案。

  GitHub Issues：如果你遇到问题或有改进建议，可以在 GitHub 上提交 Issue。这不仅能帮助你解决问题，也能帮助改进整个生态。

  社区博客：很多开发者会在博客上分享他们使用 Agent Skills 的经验、遇到的问题、解决的方案。搜索 “Agent Skills” 或 “Claude Code” 可以找到很多有价值的文章。

进阶课程

  当你完成了基础学习，想要进一步提升时，可以参考以下进阶资源：

  《Skill 设计最佳实践》：这份文档深入讲解了 Skill 设计的原理、模式、反模式。它会帮助你理解为什么某些设计是好的，某些设计是不好的。

  《Skill 开发进阶》：这份文档介绍了高级的 Skill 开发技巧，包括如何处理复杂的分支逻辑、如何优化 Skill 的性能、如何测试 Skill 的质量等。

  《Agent Skills 生态指南》：这份文档介绍了完整的 Skill 生态系统，包括如何发现 Skill、如何评估 Skill、如何贡献 Skill、如何维护 Skill 等。

学习建议

  最后，给你几个学习建议：

  循序渐进：不要试图一次学完所有内容。先掌握基础，再深入细节。就像学习一门新语言，先学会基本对话，再学习复杂语法。

  动手实践：不要只是阅读文档，要动手尝试。即使是简单的 Skill，自己创建一遍，收获也会比只看文档大得多。

  持续关注：Agent Skills 是一个快速发展的领域，新的最佳实践、新的使用场景不断涌现。定期查看官方文档和社区动态，保持学习状态。

  分享交流：把你的学习心得、使用经验分享给社区。教是最好的学，在帮助别人的过程中，你也会加深自己的理解。

课程总结 链接到标题

  恭喜你完成了 Agent Skills 基础入门课程！让我们回顾一下你学到的核心内容，并展望接下来的学习方向。

你已经掌握的核心知识

  在第一部分：快速建立认知中，你理解了开发者的真实痛点——不是不知道怎么问，而是 AI 不知道怎么做。你掌握了 Skill 的核心定义：它是一个可被 Agent 在运行时发现、理解、调用和组合的能力模块。你理解了 Skill 的三大特性：可发现、可执行、可复用。你也明白了 Skill 与 Prompt 的本质区别：Skill 不是"更长的 Prompt"，而是结构化的能力模块。

  在第二部分：理解调用机制中，你深入理解了 Agent 如何判断调用 Skill。你知道了完整的决策流程包括五个步骤：识别任务、判断能力边界、匹配 Skill、执行、整合输出。你通过实际案例和练习，学会了判断哪些任务适合使用 Skill，哪些任务不需要 Skill。

  在第三部分：理解 Skill 结构中，你从使用者视角切换到了创建者视角。你理解了"语义缩放"的概念：从黑盒视角到文件夹视角再到结构细节。你掌握了 frontmatter 的作用——它不是备注，而是路由的入口。你理解了 SKILL.md 的结构：Goal、Workflow、Constraints、Examples。你也知道了 Skill 可以搭配 scripts/ 等扁平化的可选资源目录来处理复杂任务。

  在第四部分：生态与边界中，你了解了 Skill 的三大来源：官方内置、官方仓库、社区生态。你深入理解了 Skills、Function Calling、MCP 三种技术的区别和适用场景。你学会了如何根据确定性要求、迭代速度、团队能力、集成复杂度来选择合适的技术。你也规划了自己的学习路径：从体验到理解，从设计到创造。

你现在可以做什么

  完成这门课程后，你已经具备了以下能力：

  理解能力：你可以清晰地解释什么是 Agent Skills，为什么需要它，它与其他技术有什么区别。你可以向团队成员、同事、朋友介绍这个概念，帮助他们理解它的价值。

  判断能力：你可以判断一个任务是否适合使用 Skill，应该使用哪种类型的 Skill。你可以评估现有 Skill 的质量，识别它们的优点和不足。

  阅读能力：你可以阅读和理解现有 Skill 的代码，理解它们的设计思路、执行流程、约束条件。你可以从优秀的 Skill 中学习最佳实践。

  规划能力：你可以规划自己的学习路径，知道接下来应该学什么、怎么学、如何验证学习效果。

接下来的学习方向

  这门课程只是你 Agent Skills 学习之旅的起点。接下来，你可以：

  在实际项目中使用 Skill：找一个你日常工作中的重复性任务，尝试用 Skill 来解决。观察它的效果，记录遇到的问题，思考如何改进。

  阅读优秀 Skill 的源码：选择 3-5 个官方或社区的优秀 Skill，仔细阅读它们的代码。分析它们的设计思路、实现方式、处理边界情况的方法。

  尝试创建简单的 Skill：从一个简单的任务开始，比如"会议纪要生成"或"代码注释补充"。完整地写出 frontmatter 和 body，然后请有经验的人帮你审查。

  参与社区讨论：加入 Agent Skills 的讨论社区，观察其他人在讨论什么问题、分享什么经验。你不需要立即发言，先观察和学习就很有价值。

接下来的学习方向

  这门课程只是你 Agent Skills 学习之旅的起点。接下来，你可以：

  在实际项目中使用 Skill：找一个你日常工作中的重复性任务，尝试用 Skill 来解决。观察它的效果，记录遇到的问题，思考如何改进。

  阅读优秀 Skill 的源码：选择 3-5 个官方或社区的优秀 Skill，仔细阅读它们的代码。分析它们的设计思路、实现方式、处理边界情况的方法。

  尝试创建简单的 Skill：从一个简单的任务开始，比如"会议纪要生成"或"代码注释补充"。完整地写出 frontmatter 和 body，然后请有经验的人帮你审查。

  参与社区讨论：加入 Agent Skills 的讨论社区，观察其他人在讨论什么问题、分享什么经验。你不需要立即发言，先观察和学习就很有价值。

最后的建议

  学习 Agent Skills，最重要的是持续实践。不要害怕犯错，不要追求完美。第一个 Skill 可能不够好，但这是正常的。重要的是开始行动，在实践中学习，在反馈中成长。

  记住：最好的 Skill 往往是在实际使用中打磨出来的。不要等到"学会了所有知识"再开始创建 Skill，而是边学边做，在做中学。

  祝你在 Agent Skills 的学习和实践中取得成功！如果你有任何问题或想要分享你的经验，欢迎在社区中与我们交流。