RMDC系统设计文档 整体转换为SKILL

98-AgentSkills/2-prompt-for-prompt.md

@@ -0,0 +1,4 @@
+你是一名精通prompt engineering和context engineering的大师，非常精通利用LLM大模型
+进行代码开发工作。
+对于ClaudeCode Agent Skills有着深刻的理解和认识，熟练掌握官方的SKILL开发指导说明，熟练掌握开源的SKILL用法。
+请你为一名具备LLM开发prompt经验的人员，写一份详细的SKILL使用及开发说明，对比Prompt与SKILL的差异，突出SKILL的特点

98-AgentSkills/3-Agent Skills 使用与开发实战指南-p.md

@@ -0,0 +1,601 @@
+# Claude Code Agent Skills 使用与开发实战指南
+
+（面向有 Prompt 经验的 LLM 开发者）
+
+***
+
+## 0. 面向谁 \& 要解决什么问题
+
+本指南面向已经熟悉「写系统 Prompt / 模板 Prompt 来驱动大模型」的工程师，重点回答三个问题：
+
+1. **从 Prompt 到 Skill 的本质差异是什么？**
+2. **在 Claude Code / Agent SDK 里，Skill 实际是怎么被发现、触发和执行的？**
+3. **如何把现有的 Prompt 工作流系统性迁移为 Skill，并做好工程化维护？**
+
+全文会大量对比 Prompt vs Skill，突出 Skill 在「可复用、可维护、可组合」上的优势，并给出面向工程实践的设计建议。
+
+***
+
+## 1. 核心概念：什么是 Agent Skill？
+
+从官方定义出发，**Skill = 指令包（Markdown）+ 元数据（YAML）+ 可选脚本/资源文件**，用于给 Claude 注入特定领域的专业能力，并在需要时**按需加载（progressive disclosure）**。
+
+可以粗略理解为：
+> 从「一次性 Prompt」升级为「可发现、可触发、可共享的领域专家插件」。
+
+### 1.1 Skill 的组成
+
+典型 Skill 目录结构（Claude Code / Agent SDK 默认形式）如下：
+
+```text
+my-skill/
+├── SKILL.md          # 必须，有 YAML frontmatter + 主指令
+├── reference.md      # 可选，详细文档/规范，按需加载
+├── examples.md       # 可选，用法示例
+└── scripts/          # 可选，可执行脚本（Python/JS/bash 等）
+    └── helper.py
+```
+
+其中：
+
+- **SKILL.md**
+    - 顶部 `---` 之间为 YAML frontmatter：
+        - `name`: Skill 名（唯一标识）
+        - `description`: Skill 做什么 \& 何时使用（触发判断关键信号）
+    - 下方为 Markdown 正文：指令、步骤、示例、链接到其它文件等
+- **其他 Markdown 文件**
+    - 延伸文档、规范、API 说明、更多示例
+    - Skill 激活后才按需加载，避免一开始就占满上下文
+- **scripts/**
+    - 放可执行脚本，由 Claude 通过 code execution / bash 调用，结果再由模型解释
+
+
+### 1.2 Skill 在系统里的位置
+
+在 Agent SDK / Claude Code 中，Skill 被作为一种特殊的「工具」存在（工具名通常为 `Skill`），出现在工具列表中，与 `Read` / `Write` / `Bash` 等并列。
+
+但它和传统工具最大的区别是：
+
+- 传统工具：**执行动作 → 返回结果**
+- Skill：**注入指令/上下文 → 修改后续推理环境**
+
+换句话说，Skill 更像是**上下文工程 (context engineering) 的模块化单元**，通过：
+
+- 在对话历史中插入系统/用户级指令
+- 动态调整可用工具、模型、思考 token 限制等
+
+***
+
+## 2. Prompt vs Skill：从 Prompt 工程师视角的系统性对比
+
+为了方便有 Prompt 经验的读者，先用表格给出高层对比。
+
+### 2.1 Prompt / Slash Command / Skill / MCP / Subagent 对比
+
+| 维度 | 普通 Prompt | Slash Command (`/xxx`) | Skill (Agent Skill) | MCP 工具 | Subagent |
+| :-- | :-- | :-- | :-- | :-- | :-- |
+| 触发方式 | 用户临时输入 | 用户显式输入命令 | 模型根据描述自动触发（可带确认） | 模型显式选择调用 | 用户或模型显式切换 |
+| 存储形态 | 文本片段 / 模板 | 单一 `.md` 文件 | 目录 + `SKILL.md` + 资源文件/脚本 | 外部服务 / 进程 | 独立 agent 配置文件 |
+| 作用范围 | 当前对话 | 当前项目或用户 | 全局（用户级）+ 项目级 | 任意集成的应用 | 子上下文 |
+| 核心能力 | 影响一次或一段对话行为 | 复用一段 Prompt | 封装**可重用工作流 + 资源 + 可执行逻辑** | 访问外部数据/服务 | 长期专职 agent，独立上下文 |
+| 上下文成本 | 每次要重新输入或粘贴 | 命令内容一次性进入上下文 | 先只加载 metadata，触发后再加载全文（progressive disclosure） | 按调用次数计入提示 | 独立 context window |
+| 发现机制 | 人脑记忆/文档 | 人主动记命令名 | 模型基于 `description` 自动匹配任务 | 调用逻辑通常在 app 代码里 | 由 orchestrator 决定何时委派 |
+| 脚本支持 | 需要外部 pipeline | 支持有限（多数为文本） | 可绑定脚本并在 code execution 环境中运行 | 自己就是代码 | 可使用一组工具 |
+| 复用 \& 版本管理 | 很难系统管理 | 可以通过 Git 管理单文件 | 自然地通过 Git / 目录版本化、共享 | 依赖微服务/Git | 类似 micro-service 配置 |
+
+从 Prompt 工程师角度，可以总结为：
+
+> **Prompt 是「指令文本」，Skill 是「指令系统」**
+> Prompt 强在「灵活，快速试验」，Skill 强在「标准化，可复制，可演化」。
+
+### 2.2 Skill 相比纯 Prompt 的关键优势
+
+1. **发现 \& 自动触发**
+    - 不需要用户记住「要贴哪段 Prompt」，模型通过 Skill 的 `description` 判断当前请求是否适配，然后请求使用该 Skill。
+    - 对于团队内部知识，极大降低使用门槛（只要「说人话描述任务」即可）。
+2. **进阶的上下文工程**
+    - Progressive disclosure：启动时只加载 metadata；触发 Skill 时再读 `SKILL.md` 和相关文件，既省 token 又避免污染通用对话。
+    - 能把长文档、规范、脚本拆分到多个文件，按需加载，而不是一次性塞进系统 Prompt。
+3. **与可执行代码融合**
+    - 可在 `scripts/` 里放好经过验证的 Python/JS/Bash 脚本，Skill 中只写「何时、如何调用脚本、如何解释输出」。
+    - 把「确定性处理」（解析文件、复杂计算、格式转换）迁到脚本，「不确定性决策」留给模型。
+4. **工程化与团队协作**
+    - Skill 目录可以直接纳入 Git 仓库，与代码、文档同一生命周期进行评审、测试、发布。
+    - 可以在个人级 (`~/.claude/skills/`) 和项目级 (`.claude/skills/`) 间共享和组合。
+5. **跨界面统一复用**
+    - 同一个 Skill 可同时在 Claude App / Claude Code / API / 支持 Skills 的 IDE 插件中使用。
+    - 你在本地为团队开发的 Skill，理论上可以作为「统一的工作流组件」在多个入口使用。
+
+***
+
+## 3. Skill 的运行机制：发现 → 触发 → 执行
+
+理解运行机制，有助于更好地做「技能触发设计」和「上下文工程」。
+
+### 3.1 Discovery：启动时的轻量加载
+
+当 Agent 启动（Claude Code、SDK 程序、支持 Skill 的 app）时，会做：
+
+1. 扫描 `~/.claude/skills/` 和当前工程 `.claude/skills/` 中的子目录。
+2. 对每个目录，只读取 `SKILL.md` 的 YAML frontmatter（`name` + `description` 等）。
+3. 把这些 metadata 以文本形式加入 Skill 工具的描述中，出现在模型能看到的 system 提示中。
+
+**此时模型只知道：**
+> 「有哪些技能、叫啥名字、干什么、什么时候用」，
+> 但还没有看到真正的长指令和资源内容。
+
+### 3.2 Activation：根据自然语言请求触发
+
+当用户输入任务（例如「帮我生成一份符合公司品牌规范的 PPT」），流程大致是：
+
+1. 模型在看到当前用户消息 + Skill 列表描述后，**根据语义匹配**，判断有哪些 Skill 适用。
+2. 如果判断某个 Skill 合适，会通过 `Skill` 工具发起一次调用，内部携带 `command`/`name` 等信息。
+3. 前端/SDK 通常会给用户一个「是否使用某某 Skill」的确认提示（尤其在 Claude Code/Claude App 中）。
+
+匹配质量高度依赖：
+
+- `description` 里是否写清楚**任务类型、输入形式、关键关键词**；
+- 是否给出类似「当用户说 X/Y/Z 时，使用本 Skill」的语句。
+
+
+### 3.3 Execution：加载指令、脚本与资源
+
+Skill 激活后，系统会做：
+
+1. 通过 `Bash` / 文件访问工具读取 `SKILL.md` 正文内容，插入到对话上下文中（通常以用户可见 + 隐藏两条消息注入）。
+2. 如果 `SKILL.md` 里引用了其他 Markdown 文件（如 `reference.md` / `examples.md`），则在需要时再读取对应内容，进一步注入上下文。
+3. 若指令中包含像「运行 `scripts/analyzer.py` 并解析输出」的步骤，Claude 会：
+    - 使用 code execution / bash 工具执行脚本；
+    - 读取输出文件（比如 JSON/CSV），再进行解释和总结。
+4. 在整个 Skill 激活期内，可以调整：
+    - 可用工具的白名单/黑名单（例如只读文件、不允许 Bash 修改文件）；
+    - 使用的模型（例如对某 Skill 固定使用 Sonnet / Opus）；
+    - 思考 token 等参数，使复杂任务能更稳定完成。
+
+Skill 完成任务后，可以自然退出，其指令虽然已在对话里，但后续模型可根据上下文判断是否继续遵循，或在需要时再次触发其它 Skill。
+
+***
+
+## 4. Skill 目录结构与 `SKILL.md` 设计详解
+
+### 4.1 `SKILL.md` 最小可用示例
+
+以一个「解释代码」的 Skill 为例（官方文档类似示例）：
+
+```markdown
+---
+name: explaining-code
+description: Explain source code in clear, structured language; use when users ask you to explain or understand code.
+---
+
+# Explaining Code
+
+## Goal
+When this skill is active, you explain the given code in a way that is:
+- Clear and concise
+- Structured with headings and bullet points where helpful
+- Focused on behavior, design decisions, and potential issues
+
+## Instructions
+
+1. First, identify the language, framework, and main purpose of the code.
+2. Then, explain:
+   - What the code does step by step
+   - How key functions, classes, and modules interact
+   - Any assumptions or implicit behaviors
+3. Highlight:
+   - Potential bugs or edge cases
+   - Performance concerns
+   - Security considerations
+4. Provide suggestions for improvement if relevant.
+
+## Examples
+
+### Example 1: Small function
+
+_User request_: "Explain what this JavaScript function does and if there are any issues."
+
+...
+```
+
+要点：
+
+- **YAML frontmatter 必须有 `name` \& `description`**；模型就是靠这两个字段判断何时使用该 Skill。
+- 正文建议包含：
+    - 明确的目标（Goal）
+    - 详细的步骤（Instructions）
+    - 若干典型示例（Examples）
+- Skill 是给「另一实例的 Claude」看的文档，写法应面向模型：步骤清晰、可执行、少模糊语义。
+
+
+### 4.2 推荐的正文结构模板
+
+对于多数工程类 Skill，可以采用固定骨架：
+
+```markdown
+# <Skill 名称（人类友好标题）>
+
+## 1. 适用场景（When to use this Skill）
+- 当用户...
+- 当输入包含...
+- 不要在以下情况使用...
+
+## 2. 输入与输出约定
+- 输入可以是：
+  - ...
+- 输出必须包括：
+  - ...
+- 对输出格式的要求（如 JSON schema / Markdown 结构）
+
+## 3. 工作流步骤
+1. ...
+2. ...
+3. ...
+
+## 4. 参考规范 / 约束
+- 引用 `style-guide.md` / `api-reference.md` 等
+- 明确必须遵守的约束（安全/隐私/合规）
+
+## 5. 示例
+### 示例 1
+_用户..._
+_期望输出..._
+
+## 6. 常见错误与修正
+- 如果出现 X，则...
+```
+
+这样设计有几个好处：
+
+- 方便未来的 Claude 实例按「When to use」部分进行自我检查；
+- 输入输出约定可以和脚本/下游系统严格对齐；
+- 工作流步骤使 Skill 更像一份 SOP（标准作业流程），可复用性强。
+
+
+### 4.3 多文件 Skill 的组织方式
+
+多文件 Skill 适合复杂领域，例如：
+
+- 公司级代码规范/安全规范；
+- 复杂文档模板（产品需求文档、设计文档、测试计划）；
+- 大型 API / 数据仓库查询规范。
+
+典型做法是：
+
+```text
+code-review/
+├── SKILL.md          # Overview + 导航
+├── SECURITY.md       # 安全审计检查表
+├── PERFORMANCE.md    # 性能审查要点
+├── STYLE.md          # 代码风格规范
+└── scripts/
+    └── run-linters.sh
+```
+
+在 `SKILL.md` 中：
+
+- 先给出总体工作流；
+- 再指示 Claude 在特定步骤「按需打开 SECURITY.md / PERFORMANCE.md」等文件。
+
+这天然支持 progressive disclosure：仅在安全相关检查时才加载 `SECURITY.md`，避免所有规范一次性进入上下文。
+
+***
+
+## 5. 在 Claude Code / Agent SDK / App 中使用 Skill
+
+### 5.1 Claude Code 中的使用路径
+
+在 Claude Code（VS Code / 其他 IDE 集成）中，Skill 的使用大致包括：
+
+1. **安装/放置位置**
+    - 全局：`~/.claude/skills/<skill-name>/SKILL.md`
+    - 项目级：`<project>/.claude/skills/<skill-name>/SKILL.md`
+      项目级具备更高优先级，更适合项目特定约束。
+2. **启用 Skill 工具**
+    - Agent SDK 或 Claude Code 的配置中，需要将 `Skill` 工具加入 `allowedTools` / `allowed_tools` 才能使用 Skill。
+3. **交互方式**
+    - **自然语言触发**：直接按业务语言提需求，只要和 `description` 匹配，模型就会尝试触发 Skill。
+    - **显式指定技能名**：如「使用 `explaining-code` 这个技能帮我…」，可提高触发概率。
+    - **列出可用 Skill**（在 IDE 中）：例如通过命令面板或直接问 Claude 「列出当前可用的 Skills」，方便调试加载是否成功。
+4. **结合 Subagent 使用**
+    - 在 Subagent 的配置里可以指定 `skills: skill1, skill2`，让某个 Subagent 启动时自动加载对应技能。
+    - 典型用法：创建 `code-reviewer` Subagent，并为其加载 `code-review` Skill，包括安全/性能/风格规范。
+
+### 5.2 在 Claude App / Web / 桌面端中的使用
+
+技能同样在 web/桌面端可用：
+
+- 在设置中的「Skills」部分可以：
+    - 启用内置官方技能（Excel/Word/PPT/PDF 等）；
+    - 上传自定义 Skill（打包成 zip 或按要求目录）；
+- 对话中，当 Claude 自动使用 Skill 时，会有明显标记（例如「已使用某某 Skill」），便于观察和调试；
+- 「Skill Creator」技能可以辅助用自然语言生成新的 Skill 初稿（对 prompt 工程师尤其友好）。
+
+
+### 5.3 在 API / Agent SDK 中使用
+
+在 Agent SDK 或直接使用 Claude Messages API 时：
+
+- 在 agent 配置中声明开启 Skills，并允许 `Skill` 工具。
+- 上下文中会自动注入已安装技能的 metadata，后续与 Claude Code 的逻辑一致。
+- 某些环境还支持在 API 调用中显式指定要使用的 Skill 名称，以更强约束模型行为。
+
+***
+
+## 6. 从 Prompt 到 Skill：一个系统化迁移方法论
+
+假设你已经有一批在日常工作中频繁使用的 Prompt（代码审查模板、文档模板、业务流程模板等），可以按如下步骤逐步迁移为 Skill。
+
+### 6.1 Step 1：挑选适合作为 Skill 的场景
+
+优先选择具备以下特征的 Prompt：
+
+- **任务稳定、重复频率高**
+  例如「生成符合公司模板的周报」、「按照固定格式写 PRD」、「执行特定框架的代码审查」。
+- **指令较长，粘贴成本高**
+  每次要粘贴 100+ 行 Prompt 才能用的流程。
+- **有明确可复用工作流**
+  如「先收集需求 → 再分析约束 → 再生成文档 → 再生成测试用例」。
+- **需要结合外部资源 / 规范**
+  如品牌规范 PDF、API 文档、现有脚本。
+
+这类场景用 Skill 迁移后收益最大。
+
+### 6.2 Step 2：抽象为「领域工作流」
+
+把原 Prompt 拆成几个维度：
+
+1. **适用场景 / 不适用场景**（写入 `description` 和正文「When to use」部分）
+2. **输入输出契约**（类型、格式、字段）
+3. **步骤化工作流**（尽量写成 numbered list）
+4. **引用的外部知识/规范**
+5. **可交给脚本完成的确定性操作**
+
+再决定：
+
+- 哪些应该留在 `SKILL.md` 主体中；
+- 哪些应拆出到 `reference.md` / `examples.md`；
+- 哪些迁移到 `scripts/` 中由代码执行。
+
+
+### 6.3 Step 3：创建目录与 `SKILL.md`，写好 frontmatter
+
+在本地或项目中创建目录：
+
+```bash
+mkdir -p ~/.claude/skills/my-weekly-report
+```
+
+然后新建 `SKILL.md`，至少包含：
+
+```yaml
+---
+name: weekly-report
+description: Create structured weekly status reports following our team's format, tone, and content guidelines. Use when users want to draft, revise, or polish weekly reports.
+---
+```
+
+描述里建议同时包含：
+
+- **任务类型**（create / review / analyze…）
+- **对象类型**（weekly report / PRD / code / log…）
+- **关键触发词**（weekly report, 周报, 状态更新 等）
+
+有实践表明，过于抽象的描述会导致触发不稳定，描述应「贴近用户会说的话」。
+
+### 6.4 Step 4：迁移 Prompt 内容为结构化指令
+
+把原来的大段 Prompt 迁移到 `SKILL.md` 正文里：
+
+- 按前文推荐的「适用场景 / 输入输出 / 工作流 / 规范 / 示例」骨架重构；
+- 适当拆分为多个 Markdown 文件，通过链接组织；
+- 将那些「给人看的摆设性说明」删减，把关键的决策规则和格式要求留下。
+
+此时建议使用官方的 `skill-creator` Skill 做一次「反向审阅」：让 Claude 作为「Skill 审查专家」检查你的 `SKILL.md` 是否清晰、可执行。
+
+### 6.5 Step 5：引入脚本（可选）
+
+对于涉及复杂文件处理、数据转换的 Skill：
+
+- 在 `scripts/` 目录中放置脚本（如 `scripts/generate_charts.py`）；
+- 在 `SKILL.md` 中写明：
+    - 何时触发该脚本；
+    - 调用方式（命令行参数、输入输出文件）；
+    - 如何基于脚本输出继续生成响应。
+
+示例片段：
+
+```markdown
+### Step 3: Generate metrics
+
+1. Run `python {baseDir}/scripts/metrics.py --input "{INPUT_PATH}" --output "metrics.json"`.
+2. Read `metrics.json` and:
+   - Summarize key metrics
+   - Highlight anomalies
+   - Propose follow-up actions
+```
+
+这样可以让 Skill 在执行时自动落地可靠、可测试的脚本逻辑。
+
+### 6.6 Step 6：测试、迭代与版本管理
+
+- 在 Claude Code 中打开工程，触发 Skill 相关任务，观察：
+    - Skill 是否被正确检测与加载；
+    - 输出是否稳定、可预期；
+    - 是否存在错误触发或遗漏触发的情况。
+- 把 Skill 目录纳入 Git：
+    - 对 `SKILL.md` 和脚本做 code review；
+    - 用单元测试或 golden test 验证脚本输出与模型输出模式；
+    - 给 Skill 加上版本号和 changelog，避免团队混乱。
+
+***
+
+## 7. 与其它能力的关系：Prompt / Slash Commands / MCP / Subagents
+
+### 7.1 与 Slash Commands 的关系
+
+官方文档已经明确给出对比：
+
+- **Slash Commands 更适合：**
+    - 简单、单文件的快捷 Prompt 片段；
+    - 用户显式调用的「动作」（如 `/review`、`/optimize`）。
+- **Skills 更适合：**
+    - 多步骤、复杂工作流；
+    - 需要脚本/多个文档支持的能力；
+    - 希望由模型自动发现与触发的能力。
+
+一个现实做法是：
+
+- 将「一两句话就能说清楚的常用命令」做成 Slash Command；
+- 将「背后有 SOP/规范/脚本组合」的能力做成 Skill。
+
+
+### 7.2 与 MCP（Model Context Protocol）工具的关系
+
+MCP 工具解决的是「对接外部服务和数据源」的问题，而 Skill 解决的是「**如何使用这些工具与数据完成任务**」的问题。
+
+常见组合方式：
+
+- MCP 提供：
+    - 数据库查询；
+    - 外部 API 调用；
+    - 文件存储与检索。
+- Skill 提供：
+    - 如何根据业务规则选择查询；
+    - 如何解释结果并组装报告；
+    - 如何处理失败/重试逻辑（在指令层面）。
+
+可以理解为：
+
+> MCP = 手里的工具箱
+> Skill = 用这些工具完成某项工程的施工手册
+
+### 7.3 与 Subagents 的关系
+
+Subagent 是具备独立系统 Prompt / 上下文 / 工具集合的「子代理」：
+
+- 适合：
+    - 长期运行的专职角色（如「安全审核专家」「数据科学家」）；
+    - 需要独立上下文，避免主对话污染。
+- 而 Skill 本身不创建新上下文，只是在当前 agent 环境里注入额外知识与流程。
+
+两者可以协同：
+
+- Subagent 的系统 Prompt 里定义角色；
+- 为该 Subagent 配置一组 Skills（通过 `skills:` 字段自动加载），让其在子上下文中运用这些技能处理任务。
+
+***
+
+## 8. Skill 设计与实现的最佳实践（结合 Prompt 工程经验）
+
+从 Prompt 工程到 Skill 工程，有几条实践尤为关键：
+
+### 8.1 面向「触发」写 description，而不是面向人写标题
+
+- 不要只写「Brand style enforcement skill」；
+- 应写「Enforce our company's brand style when generating documents, slides, and emails; use when users request brand-compliant content or mention brand guidelines.」
+
+要点：
+
+- 包含**动词 + 对象 + 触发语句**；
+- 尽量覆盖用户实际会说的关键词（包括中英文同义词）；
+- 明确排除场景（可写在正文里）。
+
+
+### 8.2 把 Skill 当「SOP + Playground」而不是「单次提示」
+
+- SOP：用 numbered steps 描述必须遵守的流程；
+- Playground：在示例部分给出多个「现实场景 -> 标准输出」的例子，帮助模型对齐风格。
+
+对比传统 Prompt，把「元层说明」（你是谁、你要怎么做）抽象到稳定 SOPS；把一次性的上下文保留在对话中。
+
+### 8.3 严格区分「模型擅长」和「脚本擅长」的部分
+
+- 让脚本做：
+    - 复杂解析（PDF/Excel/日志）；
+    - 一致性要求高的格式转换；
+    - 算法类计算、指标统计。
+- 让模型做：
+    - 决策、总结、解释；
+    - 文本生成、风格迁移；
+    - 多步推理。
+
+Skill 文本中应明确告诉 Claude 什么时候「先运行脚本再思考」，减轻 hallucination 风险。
+
+### 8.4 使用 progressive disclosure 优化上下文
+
+- 把大型规范/文档拆分为多个文件；
+- 在 `SKILL.md` 中通过「当执行到某步时，再读取某文件」的方式引用；
+- 避免在 Skill 中「一上来就复制粘贴整本手册」。
+
+这样不仅省 token，还减少上下文「噪音」，提高任务对齐度。
+
+### 8.5 将测试和迭代流程制度化
+
+- 为关键 Skill 设计一组「golden prompts + expected patterns」；
+- 每次改动 `SKILL.md` 或脚本后，跑一遍回归验证；
+- 把「Skill 使用问题」回溯到：
+    - description 不清；
+    - 指令歧义；
+    - 示例不足；
+    - 或脚本行为与说明不一致。
+
+社区和官方仓库里的 Skill（如 `skill-creator`）是很好的参考和基准，可以从中抽取通用结构和写法。
+
+***
+
+## 9. 常见坑与排错思路
+
+结合官方文档与社区经验，总结几个典型问题及解决方向：
+
+1. **Skill 明明写好了，但从未触发**
+    - 检查：
+        - 目录名是否正确，`SKILL.md` 是否位于根目录；
+        - frontmatter 是否合法 YAML，`name`/`description` 是否存在；
+        - 是否在 agent 配置中启用了 `Skill` 工具；
+        - `description` 是否过于抽象、不含实际触发关键词。
+2. **Skill 误触发或过度触发**
+    - 现象：稍有相关就被加载，导致上下文被早早塞满。
+    - 解决：
+        - 在 description 中更明确限定任务范围；
+        - 在正文「When NOT to use」部分增加自检指令，让 Claude 自我约束；
+        - 将多个任务拆成多个更细粒度的 Skill。
+3. **Skill 行为不一致，时好时坏**
+    - 可能原因：
+        - 工作流步骤过于模糊，缺少关键约束；
+        - 示例不足，导致风格漂移；
+        - 依赖的脚本无单测或输出不稳定。
+    - 建议：
+        - 增加「负例」示例，说明不应该产生的输出；
+        - 对关键决策处增加明确的「思考检查清单」。
+4. **多 Skill 并用时出现冲突**
+    - 例如：多个文档生成 Skill 都认为自己适用。
+    - 治理方式：
+        - 在 description 中加入更具体的触发条件（如特定文件类型、特定领域关键词）；
+        - 在 Skill 正文中加入互斥说明：如「如果 X 更匹配另一个 Skill，则不要使用本 Skill」。
+
+***
+
+## 10. 总结：从 Prompt 工程到 Skill 工程
+
+从体系化视角看：
+
+- **Prompt 工程**解决的是：
+  「如何构造一次性上下文，让模型在当前会话表现良好」。
+- **Skill 工程**解决的是：
+  「如何以模块化方式封装知识与流程，让模型在不同场景、长期、多人协作下都表现一致」。
+
+对于已经有成熟 Prompt 经验的开发者，下一步的升级路径可以概括为：
+
+1. 把高频、高价值 Prompt 抽象成可重用工作流（SOP）；
+2. 迁移为 Skill：写好 `SKILL.md` 的 frontmatter 与结构化正文；
+3. 将领域知识与脚本一起封装，利用 progressive disclosure 和 code execution 提升稳定性与效率；
+4. 通过 Git + 测试 + 版本管理，把 Skill 纳入工程资产；
+5. 结合 MCP 和 Subagent，把 Skill 作为「领域 Playbook」，构建真正可运营的 AI agent 体系。
+
+在 Claude Code / Agent SDK 生态下，Skill 已经成为官方推荐的「中间层抽象」：
+与 MCP 工具、Subagent、Projects 等能力一起，构成从 Prompt 工程到 Agent 工程的关键桥梁。
+
+如果后续希望，可以进一步围绕你的具体场景（例如代码库结构、文档模板、数据分析流程）给出一份「定制 Skill 设计蓝图」，直接从现有 Prompt 资产出发设计目录和 `SKILL.md` 模板。
+
+

98-AgentSkills/4-Claude Code Agent Skills 架构深度解析与实战实施指南：从提示工程到智能体编排的范式转移.md

@@ -0,0 +1,429 @@
+## 1. 执行摘要：智能体时代的上下文工程新前沿
+
+在生成式人工智能（Generative AI）的演进历程中，开发者与大语言模型（LLM）的交互模式正经历着一场深刻的范式转移。长期以来，\*\*提示工程（Prompt Engineering）\*\*一直是驾驭模型能力的核心手段，通过精心构造的静态文本来引导模型的随机性输出。然而，随着软件工程复杂度的指数级上升，单纯依赖无状态（Stateless）的提示词已难以满足构建大规模、多步骤、具备长期记忆的自动化系统的需求。
+
+本报告旨在为具备深厚提示工程背景的专家提供一份关于 **Claude Code Agent Skills** 的权威技术指南。Claude Code Skills 不仅仅是提示词的延伸，它们代表了一种全新的\*\*智能体编排（Agentic Orchestration）\*\*架构。在这种架构中，静态的文本指令被转化为动态的、可执行的、且具备文件系统感知能力的“技能”模块。这种转变使得 LLM 从一个被动的文本生成器，进化为一个能够主动感知环境、执行确定性代码、并根据任务需求动态加载上下文的智能实体 <sup>1</sup>。
+
+通过对 **模型上下文协议（Model Context Protocol, MCP）** 、文件系统级记忆架构以及混合执行模式（Hybrid Execution Pattern）的深度剖析，本报告将揭示 Skill 如何解决传统提示工程中面临的“上下文窗口过载”、“工具幻觉”以及“复杂逻辑推理不稳定”等核心痛点 <sup>3</sup>。对于致力于构建自动化代码开发工作流的资深工程师而言，掌握 Skill 的开发与部署，是迈向下一代 AI 辅助开发（AI-Assisted Development）的关键一步。
+
+---
+
+## 2. 架构基础：从无状态对话到有状态智能体
+
+要理解 Agent Skills 的本质，首先必须解构 Claude Code 的运行时环境。与传统的 ChatGPT 或 Claude.ai 网页端对话不同，Claude Code 是一个运行在开发者本地终端（CLI）中的**智能体循环（Agentic Loop）** 。这种环境差异决定了其认知架构的根本不同。
+
+### 2.1 文件系统即认知中枢
+
+在传统的 LLM 应用开发中，所谓的“记忆”通常是通过向量数据库（Vector Database）实现的检索增强生成（RAG），或者是硬编码在系统提示词（System Prompt）中的规则。然而，Claude Code 引入了一种更为原生且符合开发者直觉的架构：**文件系统即长期记忆与能力注册表** <sup>1</sup>。
+
+Agent Skills 并非存储在云端数据库或复杂的配置中心，而是以扁平文件的形式直接驻留在项目的 `.claude/skills/` 目录或用户的主目录 `~/.claude/skills/` 中。这种设计带来了几个关键的架构优势：
+
+1. **上下文局部性（Contextual Locality）：**  Claude Code 具备递归发现机制。当智能体在 `packages/frontend/` 目录下工作时，它不仅会加载全局技能，还会自动发现并挂载该子目录下的 `.claude/skills/`。这意味着，开发者可以为前端项目定义一套特定的构建和测试技能，而为后端项目定义另一套数据库迁移技能，模型会根据当前的工作路径自动切换“思维模式”和“工具箱” <sup>6</sup>。
+2. **版本控制即治理（GitOps for AI）：**  由于 Skill 本质上是 Markdown 和脚本文件，它们完全纳入 Git 版本控制体系。这意味着团队对智能体行为的每一次修改、优化或回滚，都像代码审查（Code Review）一样可追溯、可管理。这解决了传统提示工程中 Prompt 版本混乱、难以协作的难题 <sup>7</sup>。
+3. **环境感知（Environment Awareness）：**  Skill 能够直接访问本地环境。通过 `{baseDir}` 等变量插值，Skill 可以精确调用与其关联的 Python 或 Bash 脚本，实现从“文本建议”到“代码执行”的跨越 。
+
+### 2.2 元工具（Meta-Tool）范式与动态加载
+
+从技术实现的角度来看，Skill 是对 LLM **工具使用（Tool Use / Function Calling）**  能力的高级抽象。当开发者创建一个 `SKILL.md` 文件时，Claude Code 的运行时环境（Runtime）并不会立即将文件中的数千字说明全部塞入模型的上下文窗口。这样做会导致上下文窗口迅速耗尽，且过多的无关信息会干扰模型的注意力机制。
+
+相反，系统采用了一种\*\*元工具（Meta-Tool）\*\*机制 。在启动阶段，Claude Code 仅扫描所有 Skill 的 YAML 前置元数据（Frontmatter），提取 `name`（名称）和 `description`（描述）。这些轻量级的信息被注册为模型可见的工具定义。
+
+当用户发出指令（例如“分析这个 Git 仓库的提交历史”）时，模型首先基于 `description` 进行语义匹配，判断是否需要调用某个 Skill。只有当模型决定激活特定 Skill 时，运行时环境才会读取 `SKILL.md` 的完整内容，并将其作为“临时系统指令”注入到当前的上下文窗口中。这种\*\*按需加载（Just-in-Time Context Loading）\*\*策略，是 Skill 能够支持数百个工具而不会导致模型“痴呆”或成本爆炸的核心原因 <sup>6</sup>。
+
+### 2.3 执行生命周期深度解析
+
+一个典型的 Skill 执行过程包含以下几个严密的微步骤，理解这一流程对于调试和优化至关重要：
+
+1. **意图识别（Intent Recognition）：**  用户输入自然语言。模型在后台评估所有可用 Skill 的描述字段。
+2. **路由决策（Routing Decision）：**  模型输出一个工具调用请求，例如 `UseSkill(name="git-analyzer")`。
+3. **上下文注入（Context Injection）：**  系统拦截该调用，读取 `.claude/skills/git-analyzer/SKILL.md`，解析其中的 `{baseDir}` 等变量，将处理后的 Markdown 文本插入对话历史。
+4. **混合推理（Hybrid Reasoning）：**  模型阅读 Skill 中的详细步骤（Prompt），结合用户输入的参数（Arguments），规划执行路径。
+5. **代码执行（Code Execution）：**  如果 Skill 指示运行脚本，模型会生成 `Bash` 或 `CodeExecution` 工具调用，系统在本地沙箱中执行脚本并返回 stdout/stderr 结果。
+6. **结果合成（Result Synthesis）：**  模型根据脚本的输出，结合 Skill 中定义的输出格式要求，生成最终回复 <sup>2</sup>。
+
+---
+
+## 3. 比较分析：提示词、MCP 与 Skills 的三角关系
+
+对于精通提示工程的开发者来说，最大的认知障碍往往在于混淆 **Prompt（提示词）** 、**MCP（模型上下文协议）**  和 **Skill（技能）**  的边界。它们虽然都旨在增强模型能力，但在架构栈中处于完全不同的层级。
+
+### 3.1 提示工程 vs. 技能工程
+
+从提示工程向技能工程的演进，本质上是从**无状态指令**向**有状态能力**的跨越。
+
+| **维度** | **提示工程 (Prompt Engineering)**                                                               | **技能工程 (Skill Engineering)**                                                 | **核心差异分析**                                                                |  |  |  |  |
+| -- | ---------------------------------------------------------------- | -------------------------------------------------- | ----------------------------------------------------------------- | -- | -- | -- | -- |
+| **持久性** | 临时性；仅存在于当前会话窗口或需手动粘贴。                     | 持久性；作为文件驻留于项目结构中 (`.claude/skills`)。            | Skill 是项目的永久资产，而 Prompt 是临时消耗品。                |  |  |  |  |
+| **上下文成本** | 高；复杂的 System Prompt 会持续占用 Token 配额。               | 低；采用“懒加载”机制，仅在激活时消耗 Token。   | Skill 架构允许定义成百上千种能力，而不影响基础对话成本<sup>6</sup>。        |  |  |  |  |
+| **执行确定性** | 低；依赖模型生成代码并由用户复制粘贴。                         | 高；通过捆绑 Python/Bash 脚本实现确定性逻辑。    | Prompt 告诉模型“如何写代码”，Skill 赋予模型“运行代码的手”<sup>4</sup>。 |  |  |  |  |
+| **作用域** | 全局（System Prompt）或 局部（User Message）。                 | 层级化；支持组织级、用户级、项目级和目录级覆盖。 | Skill 具备继承和覆盖特性，更适合大型工程团队的协作管理<sup>6</sup>。        |  |  |  |  |
+| **逻辑封装** | 困难；超长 Prompt 容易导致“中间迷失”（Lost-in-the-Middle）。 | 模块化；复杂逻辑被封装在独立文件和脚本中。       | Skill 鼓励“关注点分离”，将业务逻辑从 LLM 的推理中剥离出来<sup>11</sup>。   |  |  |  |  |
+
+**深度洞察：**  传统的提示工程实际上是在试图用自然语言“模拟”计算机程序的逻辑。例如，通过 Prompt 要求模型“像 Python 解释器一样行事”。而 Skill 工程则是**回归本源**，让模型调用真正的 Python 解释器来处理计算任务，只保留模型作为“推理引擎”和“自然语言接口”的角色。这种“脑（LLM）+ 手（Script）”的分离是构建可靠智能体的基石 <sup>12</sup>。
+
+### 3.2 技能 vs. 模型上下文协议 (MCP)
+
+**模型上下文协议 (MCP)**  是 Anthropic 推出的一项开放标准，旨在解决 AI 模型与外部数据源连接的“碎片化”问题 <sup>3</sup>。许多开发者困惑于何时使用 MCP，何时使用 Skill。
+
+MCP（连接层 / "USB-C 接口"）：
+
+MCP 是底层的数据管道和工具协议。它定义了 Client（如 Claude Code）如何与 Server（如 Postgres 数据库、Google Drive、GitHub）进行通信。MCP Server 暴露的是原子化的工具（Atomic Tools）和资源（Resources）。
+
+- *例子：*  `postgres.query_table`、`github.get_pull_request`、`filesystem.read_file`。
+- *特点：*  通用、标准化、无业务逻辑。
+
+Skills（编排层 / "驱动程序"）：
+
+Skill 是上层的业务逻辑编排器。它定义了如何使用这些 MCP 工具来完成一个复杂的任务。Skill 是一份 SOP（标准作业程序），指导模型按顺序调用 MCP 工具，处理中间结果，并做出决策。
+
+- *例子：*  一个名为“自动化代码审查”的 Skill，可能会先调用 MCP 的 `git.diff` 获取变更，再调用 `filesystem.read` 读取代码规范，最后综合生成审查意见。
+
+**对比表格：**
+
+| **特性** | **Model Context Protocol (MCP)**                                                        | **Claude Code Agent Skills**                                         |  |  |  |
+| -- | --------------------------------------------------------- | ------------------------------------------ | -- | -- | -- |
+| **抽象层级** | 低层级；原子化 API 接口。                               | 高层级；端到端工作流（Workflow）。       |  |  |  |
+| **实现方式** | 编写代码（TypeScript/Python SDK）。                     | 编写 Markdown (`SKILL.md`) + 脚本。                |  |  |  |
+| **主要角色** | 提供数据访问和基础动作（躯干）。                        | 提供操作指南和策略推理（大脑）。         |  |  |  |
+| **可移植性** | 通用协议；适用于所有支持 MCP 的客户端（IDE、Desktop）。 | 目前主要针对 Claude Code CLI 优化。      |  |  |  |
+| **核心价值** | 连接孤岛数据（Data Connectivity）。                     | 固化专家经验（Expertise Distillation）。 |  |  |  |
+
+架构协同效应：
+
+最强大的模式是将 Skill 作为 MCP 工具的“包装器”。直接将原始的 SQL 查询工具（通过 MCP 暴露）交给 LLM 往往是危险的，因为它可能执行 DROP TABLE。但是，通过编写一个 SKILL.md，可以限制模型只能执行特定的查询模式，或者强制模型在执行破坏性操作前进行二次确认。Skill 在这里充当了 MCP 工具的安全护栏和上下文增强器 2。
+
+---
+
+## 4. 深度解析：Skill 开发规范与 `SKILL.md` 详解
+
+作为 Context Engineering 的大师，理解 `SKILL.md` 的微观结构是至关重要的。这不仅仅是写文档，而是在编写**可执行的自然语言代码**。
+
+### 4.1 Skill 的解剖学结构
+
+一个标准的 Skill 是一个包含 `SKILL.md` 的文件夹。该文件由两部分组成：**YAML Frontmatter**（元数据）和 **Markdown Body**（指令体）<sup>1</sup>。
+
+#### 4.1.1 YAML Frontmatter：元数据配置
+
+这是 Skill 的“注册表信息”，决定了 Skill 何时以及如何被系统调度。
+
+YAML
+
+```
+---
+name: api-schema-validator
+description: Validates API response JSON against the OpenAPI specification. Use when user asks to check API consistency or debug backend responses.
+allowed-tools: Bash, Read, Write(test_reports/*)
+model: claude-3-opus-20240229
+user-invocable: true
+---
+```
+
+**关键字段深度分析：**
+
+- **`name`**：必须是 kebab-case（短横线连接）。这是模型内部引用该 Skill 的唯一标识符。
+- **`description`**：这是**上下文工程**中最关键的部分。它实际上是语义路由（Semantic Router）的匹配键。一个模糊的描述（如 "Helper tool"）会导致 Skill 永远不被触发。一个优秀的描述应该包含用户的潜在意图（Intent）和触发场景（Trigger Context），例如 "Use when user asks to..." <sup>6</sup>。
+- **`allowed-tools`**：这是一个**安全沙箱**机制。通过显式列出允许使用的工具，开发者可以防止 Skill 执行未授权的操作。
+
+    - *高级用法：*  支持 Glob 模式匹配。例如 `Bash(python scripts/*.py:*)` 表示仅允许执行 `scripts` 目录下的 Python 脚本，严禁执行 `rm -rf /` 等危险命令。这是企业级部署中不可或缺的安全特性 <sup>2</sup>。
+- **`model`**：可选字段。允许强制指定 Skill 运行的模型版本。对于需要极其复杂推理（如架构设计）的 Skill，可以强制指定 `claude-3-opus`；而对于简单的格式化任务，可以使用 `claude-3-haiku` 以降低延迟和成本 <sup>17</sup>。
+- **`user-invocable`**：如果设置为 `false`，则该 Skill 不会出现在 `/` 斜杠命令菜单中，只能由模型根据上下文隐式触发。这适用于那些作为“后台进程”存在的辅助 Skill <sup>6</sup>。
+
+#### 4.1.2 Markdown Body：指令工程
+
+`SKILL.md` 的正文是 Skill 的灵魂。它采用了“思维链（Chain-of-Thought）”的最佳实践，将模糊的任务转化为确定的步骤。
+
+**结构化最佳实践：**
+
+1. **目标声明（Objective Statement）：**  用一句话清晰定义 Skill 的产出。
+2. **参数解析（Argument Handling）：**  明确指示模型如何处理 `$ARGUMENTS` 变量。
+3. **分步逻辑（Step-by-Step Logic）：**  使用编号列表强制模型按顺序执行。这是防止模型“跳步”或“幻觉”的最有效手段。
+4. **输出规范（Output Schema）：**  严格定义输出的格式（如 XML 标签、JSON 结构或 Markdown 表格），以便于后续工具或人类阅读。
+
+**示例片段：**
+
+# API Schema Validator
+
+## Context
+
+You are a QA Automation Engineer. Your goal is to verify that the API response matches the rigorous OpenAPI v3.0 standard.
+
+## Execution Plan
+
+1. **Parse Arguments:**  The user input is stored in `$ARGUMENTS`. Treat this as the target API endpoint URL.
+2. **Fetch Schema:**  Read the `openapi.yaml` file from the project root.
+3. **Execute Request:**  Use `curl` to fetch the response from `$ARGUMENTS`.
+4. **Compare:**
+
+    - Validate field types (e.g., string vs int).
+    - Check for required fields.
+5. **Report:**  Output findings in a Markdown table listing any violations.
+
+### 4.2 复杂参数处理与变量插值
+
+在 Prompt Engineering 中，我们习惯于处理自然语言。但在 Skill Engineering 中，我们需要处理结构化数据和变量。这是一个常见的陷阱区域。
+
+\$ARGUMENTS 变量的微妙之处：
+
+当 Skill 被触发时，Claude Code 会捕捉用户的输入并将其放入 \$ARGUMENTS 变量中。
+
+- *场景：*  用户输入 `/validate-api https://api.example.com/users`。
+- *变量：*  `$ARGUMENTS` 的值为 `"https://api.example.com/users"`。
+
+引用与空格问题：
+
+根据研究片段 18，在处理包含空格的参数时存在一定的不确定性。传统的 Shell 脚本习惯使用位置参数 \$1, \$2。虽然 Claude Code 的 Slash Command 支持这种位置参数解析，但在纯 Skill 模式下，最佳实践是将 \$ARGUMENTS 视为一个原始字符串（Raw String），并在 Skill 内部指示模型或脚本去解析它。
+
+- *错误模式：*  直接假设 `$1` 可用，或者未加引号直接传入 Shell：`python script.py $ARGUMENTS`（如果参数含空格，会导致脚本接收到错误的参数个数）。
+- *正确模式：*  始终使用双引号包裹：`python script.py "$ARGUMENTS"`。并在脚本内部使用 `argparse` 处理复杂的参数逻辑 <sup>20</sup>。
+
+JSON 注入模式：
+
+对于需要传入复杂配置（如多个标志位、嵌套结构）的 Skill，最稳健的工程实践是要求（或由前置 Agent 生成）JSON 格式的参数。
+
+- *指令设计：*  "Analyze the input `$ARGUMENTS`. If it is not valid JSON, stop and ask the user for JSON format."
+- *优势：*  LLM 解析 JSON 的能力远强于解析复杂的 Shell 命令行参数，这规避了转义字符和参数错位的风险 <sup>21</sup>。
+
+---
+
+## 5. 高级实现：确定性代码集成与混合智能
+
+Claude Code Skills 的真正威力在于它能够将**确定性代码（Deterministic Code）与概率性推理（Probabilistic Reasoning）**  结合。这是解决 LLM “数学不好”、“逻辑跳跃”或“无法精确操作文件”等弱点的终极方案。
+
+### 5.1 “大脑 + 计算器”混合架构模式
+
+在这个模式中，`SKILL.md` 充当“大脑”，负责理解意图、规划任务和解释结果；而伴随的 Python/Node.js 脚本充当“计算器”，负责执行具体的计算、文件分析或 API 调用。
+
+目录结构示例：
+
+.claude/skills/
+
+└── git-churn-analyzer/
+
+├── SKILL.md
+
+└── scripts/
+
+└── calculate\_churn.py
+
+实现细节：
+
+LLM 非常不擅长直接统计 git 提交记录（因为上下文窗口有限，且计数容易出错）。因此，我们在 SKILL.md 中禁止模型手动统计，而是强制其运行脚本。
+
+**SKILL.md 核心指令：**
+
+## Execution Strategy
+
+DO NOT attempt to count commits by reading git logs manually.
+
+1. Execute the analysis script located in this skill's directory:
+   python {baseDir}/scripts/calculate\_churn.py --target "\$ARGUMENTS"
+2. The script will generate a file named `churn_report.json`. Read this file.
+3. Based on the JSON data, explain to the user which modules require refactoring due to high churn.
+
+**关键技术点：**
+
+-  **`{baseDir}`**  **插值：**  这是一个极其重要的系统变量。它会被运行时环境动态替换为 Skill 所在的绝对路径。这确保了无论用户在项目的哪个子目录下调用 Skill，Claude 都能准确找到配套的脚本文件，解决了相对路径引用的噩梦 。
+
+### 5.2 规避 Shell 解析限制与安全沙箱
+
+在 Agent 开发中，直接让 LLM 生成复杂的 Shell 命令（包含管道符 `|`、重定向 `>`、通配符 `*`）是极具风险的。
+
+1. **语法错误风险：**  模型生成的 Shell 命令可能在不同 OS（MacOS vs Linux vs Windows）上表现不一致。
+2. **权限拒绝风险：**  `allowed-tools` 的解析器可能无法正确理解复杂的管道命令，导致权限校验失败 <sup>11</sup>。
+
+解决方案：封装脚本化。
+
+将复杂的逻辑（如 find. -name "\*.ts" | xargs grep "pattern" \> result.txt）封装进 scripts/search.sh。Skill 只需要申请运行 bash scripts/search.sh 的权限。这不仅绕过了 Shell 解析的歧义，还极大地提升了安全性——因为审核一个固定的脚本比审核模型生成的随机命令要容易得多。
+
+### 5.3 钩子（Hooks）与“守门人”模式
+
+Skill 还可以与 Claude Code 的 **Hooks** 系统结合，充当工作流的“守门人”。
+
+- **场景：**  `pre-commit` 检查。
+- **机制：**  配置一个 Hook，在用户尝试提交代码时自动触发 `security-audit` Skill。
+- **流程：**  该 Skill 运行 `trufflehog` 或自定义 Python 脚本扫描敏感信息。如果发现密钥泄露，Skill 会指示 Claude 终止操作并向用户发出警告。
+- **洞察：**  这种模式将 AI 从“被动助手”升级为“主动合规官”，在代码进入仓库前就拦截潜在风险 <sup>22</sup>。
+
+---
+
+## 6. MCP 集成策略：构建连接万物的神经网络
+
+虽然 Skill 在本地环境中表现出色，但要构建真正的企业级 Agent，必须连接到 Jira、Salesforce、GitHub 或生产数据库。这正是 **MCP (Model Context Protocol)**  发挥作用的地方。
+
+### 6.1 Skill 作为 MCP 的编排者
+
+专家级开发者应将 Skill 视为**逻辑层**，将 MCP 视为**数据层**。Skill 的作用是“教”模型如何正确地使用 MCP 工具。
+
+实战案例：Jira 故障修复工作流
+
+如果没有 Skill，用户需要手动提示 Claude：“先查 Jira，再查代码，然后修 Bug”。
+
+有了 fix-jira-issue Skill，流程如下：
+
+1. **触发：**  用户输入 `/fix ENG-4521`。
+2. **Skill 激活：**  `fix-jira-issue` 被加载。
+3. **MCP 调用 1：**  Skill 指令：“使用 `jira-mcp` 服务器的 `get_issue` 工具获取 ENG-4521 的详情。”
+4. **逻辑推理：**  Claude 阅读 Jira 返回的 JSON，理解这是一个空指针异常。
+5. **MCP 调用 2：**  Skill 指令：“使用 `github-mcp` 工具基于 `main` 分支创建新分支 `fix/ENG-4521`。”
+6. **本地执行：**  Skill 指令：“读取堆栈跟踪中的文件，定位问题并修复。”
+
+**洞察：**  Skill 实际上固化了使用 MCP 工具的“最佳实践”。它屏蔽了底层 API 的复杂性，即使用户不知道如何操作 Jira API，也能通过 Skill 完成任务 <sup>23</sup>。
+
+### 6.2 解决“上下文过载”问题
+
+直接连接 MCP 服务器的一个常见副作用是**元数据爆炸**。例如，连接一个企业级 Postgres 数据库的 MCP Server 可能会立即向上下文注入 500 个表的 Schema 定义，瞬间挤占所有的推理空间 <sup>3</sup>。
+
+基于 Skill 的渐进式披露（Progressive Disclosure）：
+
+我们可以编写一个 database-explorer Skill 来缓解这个问题：
+
+1. **第一步：**  仅查询数据库的表名列表（Table Names），而非完整 Schema。
+2. **第二步：**  让模型根据用户问题（如“查询用户信息”），推断出可能相关的表（如 `users`, `profiles`）。
+3. 第三步： 仅针对这几个相关表，调用 MCP 工具获取详细 Schema。
+   通过这种应用层面的渐进式加载，Skill 充当了一个智能过滤器，确保上下文窗口始终只包含当前任务所需的最少信息量。这是大规模系统集成的核心优化手段。
+
+---
+
+## 7. 战略工程：最佳实践与性能优化
+
+编写一个能跑的 Skill 很容易，但编写一个健壮、高效且安全的 Skill 需要遵循严格的工程纪律。
+
+### 7.1 渐进式披露与 Token 经济学
+
+“上下文窗口是一种公共资源（Public Good）” <sup>9</sup>。每一个被 Skill 定义消耗的 Token，都在挤占对话历史和代码文件的空间。
+
+- **策略：**  保持 `SKILL.md` 极其精简（建议 500 行以内）。
+- **技术：**  如果 Skill 需要参考一份 50 页的 API 文档，**绝对不要**将其直接粘贴在 `SKILL.md` 中。
+- **实现：**  将文档放入 `docs/api_spec.md`。在 `SKILL.md` 中写入：“如果且仅当你需要查询特定 API 参数时，读取 `docs/api_spec.md`。”
+- **效果：**  这种\*\*按需读取（Read-on-Demand）\*\*机制确保了在 Skill 激活的初始阶段只消耗极少的 Token，只有在深层任务执行时才动态加载重型知识库 <sup>6</sup>。
+
+### 7.2 确定性解析 vs. 概率性猜测
+
+不要让 LLM 去做正则引擎该做的事。
+
+- *弱模式：*  提示模型“查看输入字符串 `user:admin role:editor` 并提取用户名”。LLM 可能会在边缘情况（如用户名包含冒号）下出错。
+- 强模式： 将字符串传递给 scripts/parser.py，脚本使用严格的正则表达式提取数据并返回 JSON。
+  原则： 使用 LLM 处理意图（Intent）和非结构化数据，使用脚本处理语法（Syntax）和结构化数据。
+
+### 7.3 安全性：最小权限原则
+
+在企业环境中，Skill 本质上是拥有 Shell 访问权的自动化脚本，风险极大。
+
+- **权限管控：**  必须在 YAML Frontmatter 中严格限制 `allowed-tools`。如果一个 Skill 只需要读取日志，决不能给它 `Write` 或 `Bash` 的权限 。
+- **代码审查：**  将 `.claude/skills` 目录纳入最严格的 Code Review 流程。任何对 `SKILL.md` 或关联脚本的修改都应被视为对生产代码的修改。
+
+### 7.4 调试 Agent Skills
+
+调试一个“黑盒”模型的思维过程极具挑战性。
+
+- **会话隔离：**  利用 `${CLAUDE_SESSION_ID}` 变量。在脚本中将日志输出到 `/tmp/logs/${CLAUDE_SESSION_ID}.log`。这样可以将特定会话的脚本执行轨迹与并行运行的其他会话区分开来 <sup>6</sup>。
+- **显式回显（Verbose Echoing）：**  脚本不应默默失败。如果脚本遇到错误（如文件未找到），应打印明确的错误信息到 `stdout`。Claude 能够读取这些输出并进行**自我修正（Self-Correction）** 。例如，看到“FileNotFoundError”，模型通常会尝试查找正确的文件路径并重试。
+
+---
+
+## 8. 详细实现案例
+
+### 8.1 案例一：“智能重构” Skill（AST 语法树集成）
+
+此 Skill 展示了如何利用 Python 脚本进行抽象语法树（AST）分析，确保模型生成的重构代码在语法上是合法的，从而避免“代码写完跑不通”的尴尬。
+
+**文件路径：**  `.claude/skills/refactor/SKILL.md`
+
+---
+
+## name: smart-refactor description: Safely refactors Python functions using AST validation. Use when the user wants to rename functions or extract methods. allowed-tools: Bash, Read, Write
+
+# Smart Refactor Skill
+
+## Context
+
+You are a Python Refactoring Specialist. You prioritize code stability and correctness.
+
+## Workflow
+
+1. **Analyze Request:**  Identify the target file and function from `$ARGUMENTS`.
+2. **Pre-Computation Validation:**
+
+    - Execute the AST validator script:
+      python {baseDir}/scripts/validate\_ast.py check "\$ARGUMENTS"
+    - If the script returns an error, **STOP** immediately and report the syntax error to the user.
+3. **Plan &amp; Edit:**  Propose the refactoring plan and use the `Edit` tool to apply changes.
+4. **Post-Computation Verification:**
+
+    - Run the validator script again on the modified file.
+    - If the script reports syntax errors, **Revert** the changes using `git checkout` and inform the user of the failure.
+
+**配套脚本：**  `.claude/skills/refactor/scripts/validate_ast.py`
+
+Python
+
+```
+import ast
+import sys
+
+def check_syntax(file_path):
+    try:
+        with open(file_path, 'r') as f:
+            source = f.read()
+        ast.parse(source)
+        print(f"SUCCESS: {file_path} contains valid Python syntax.")
+        sys.exit(0)
+    except SyntaxError as e:
+        print(f"ERROR: Syntax error in {file_path}: {e}")
+        sys.exit(1)
+    except Exception as e:
+        print(f"ERROR: Could not read file: {e}")
+        sys.exit(1)
+
+if __name__ == "__main__":
+    if len(sys.argv) < 3:
+        print("Usage: validate_ast.py check <file_path>")
+        sys.exit(1)
+    check_syntax(sys.argv)
+```
+
+**分析：**  这个 Skill 注入了一个**确定性护栏**。它不再盲目信任模型的输出，而是利用 AST 解析器作为客观的裁判。这体现了 Agent Engineering 的核心思想：**Trust, but Verify（信任，但要验证）** 。
+
+### 8.2 案例二：强制 TDD 开发循环
+
+此 Skill 并不执行复杂代码，而是通过 Prompt 强制执行一种行为约束，即“测试驱动开发（TDD）”。
+
+**文件路径：**  `.claude/skills/tdd-cycle/SKILL.md`
+
+---
+
+## name: tdd-cycle description: Implements features using strict Test-Driven Development protocol. Use when asked to "implement feature X" or "add functionality". model: claude-3-opus-20240229
+
+# TDD Enforcement Protocol
+
+## Core Directive
+
+You are FORBIDDEN from writing any implementation code until you have witnessed a specific test failure.
+
+## Execution Steps
+
+1. **Phase 1: RED (Write Test)**
+
+    - Analyze the requirement.
+    - Create a new test file in `tests/` asserting the desired behavior.
+    - Run the test command: `npm test`
+    - **Checkpoint:**  Verify the output shows a specific assertion error matching the new feature. If the test passes or fails for the wrong reason, refine the test.
+2. **Phase 2: GREEN (Make it Pass)**
+
+    - Write the *minimum* implementation code required to satisfy the test.
+    - Do NOT optimize or add extra features yet.
+    - Run `npm test` again to confirm all tests pass.
+3. **Phase 3: REFACTOR (Clean Up)**
+
+    - Review the code for duplication or clarity issues.
+    - Refactor if necessary, ensuring tests remain green.
+
+**分析：**  这个 Skill 充当了**行为约束器（Behavioral Constraint）** 。它为智能体植入了一个“超我（Super-ego）”，抑制了 LLM 倾向于直接给出最终代码（往往带有 Bug）的冲动。通过强制执行 Red-Green-Refactor 循环，Skill 显著提高了生成代码的质量和可靠性。
+
+---
+
+## 9. 结论：Agentic Workflows 的未来展望
+
+Claude Code Agent Skills 的出现，标志着我们正在从**指令式交互（Instructional Interfacing）迈向环境工程（Environmental Engineering）** 。作为专家级的开发者，我们的工作重心正从“如何写出完美的提示词”转移到“如何构建完美的智能体运行环境”。
+
+掌握 `SKILL.md` 的架构、策略性地使用 `{baseDir}` 脚本封装复杂逻辑、以及精细编排 MCP 数据流，是构建下一代半自主工程师（Semi-autonomous Engineers）的关键。未来，软件工程团队的核心资产将不仅仅是业务代码，还包括随代码库一同演进的、高度专业化的 Agent Skills 库。这些 Skill 将不仅包含代码的知识，更包含团队的工程文化、架构规范和最佳实践，真正实现“代码即知识，环境即智能”。