Claude Code 实践：如何用 Skill 让 Agent 行为稳定可靠

如果你发现自己反复向 AI 解释同一件事，那么这件事就需要写成 Skill。

---

一、从"聊天"到"行动"：Agent 与 Skill 的关系

当大多数人说"AI"的时候，脑海里浮现的是一个聊天框——你问，它答。这是 AI 最广为人知的形态，但不是最强大的形态。

真正让 AI 产生生产力的，是 Agent（智能体）。

Agent 不只是回答问题，它能主动使用工具、执行操作、完成任务。它可以读写文件、调用 API、操作本地应用、执行代码……它不是在"聊天"，而是在"干活"。

没有 Skill，Agent 也能干活——大模型本身就有足够的通用能力应对大多数场景。但问题在于：每次的行为是否一致？

没有 Skill 时，Agent 面对同一类任务，可能每次走不同的路径，可能重新踩已经踩过的坑，可能忘记上次学到的经验，可能在某个关键细节上做出不同的判断。结果是：你无法信任它，每次都要盯着看。

Skill 解决的正是这个问题——它让 Agent 的行为变得稳定、可预期、可信赖。

一个 Skill 封装了完成某类任务所需的一切：领域知识、操作流程、工具调用方式、已知的坑和约束。Agent 被触发后加载对应的 Skill，每次都以同样的专家状态工作，不会因为上下文不同而产生随机行为。

这也是为什么 Skill 成为当前 Agent 技术体系中最核心的概念之一：一个 Agent 是否可靠，很大程度上取决于它的 Skill 写得好不好。

下图展示了四者之间的关系：

判断是否需要写成 Skill

如果你发现自己反复向 AI 解释同一件事，那么这件事就需要写成 Skill。

这种重复本身就是信号。每次开新对话都要重新解释背景、说明限制、提醒注意事项——这些知识没有被沉淀，Agent 每次都从零开始，你的时间在做无效的重复劳动。

Skill 适合封装什么

适合写成 Skill	不适合写成 Skill
有固定流程的重复性任务	一次性临时任务
需要特定领域知识的场景	纯创意类工作
有已知 Bug 和 Workaround 的场景	简单的单步操作
多个工具协作的复杂自动化	已有成熟工具直接覆盖的任务

Skill 和 Memory（CLAUDE.md）有什么区别

很多人在搭建 Agent 时会遇到一个困惑：这个信息该写进 CLAUDE.md，还是写成 Skill？

先说明一点：CLAUDE.md 并不只是"全局"配置。它可以放在用户根目录（对所有项目生效），也可以放在具体项目目录下（只对该项目生效）。无论哪种形式，它的共同特点是：只要在作用范围内，每次对话都会自动加载。

因此两者的核心区别只有一条：是否每次都需要？

	CLAUDE.md	Skill
加载时机	每次对话都自动加载	仅在触发相关任务时加载
适合放什么	始终生效的标准、约束、偏好设置	特定任务的专项知识和操作流程
典型内容	“永远不要修改数据库 Schema”	如何操作某个具体工具或系统
	代码风格和框架偏好	只在特定场景才用到的领域知识
	用户身份和基本信息	会让每次对话都变得臃肿的详细流程

一个判断方法：如果某段知识放进 CLAUDE.md，会让所有对话的上下文都变得更重，但大多数对话根本用不到它——那它就应该是 Skill，而不是 Memory。

Claude Code 五个核心概念，各司其职

理解了 Skill 和 CLAUDE.md 的区别之后，再放到更大的视野里看。Claude Code 提供了五种机制，每种都有自己适合的场景，不要把所有需求都塞进 Skill：

机制	触发方式	适合的场景
CLAUDE.md	每次对话自动加载	始终生效的标准与约束（可全局，也可按项目配置）
Skill	话题匹配时按需加载	特定任务的专项知识，只在相关场景才需要的操作流程
Hook	事件驱动自动触发	在特定操作前后自动执行的动作，如提交前检查、操作后通知
Subagent	主动委托执行	需要隔离上下文独立运行的子任务，避免污染主对话
MCP Server	工具调用时接入	对接外部系统和服务，如数据库、API、第三方平台

一个典型的完整配置会是这样的组合：

• CLAUDE.md 定义项目规范和编码风格
• Skill 封装发邮件、查数据库、生成报告等专项能力
• Hook 在每次文件保存后自动运行格式检查
• Subagent 处理需要独立执行的耗时任务
• MCP Server 连接 Jira、Slack、数据库等外部工具

这五个机制可以同时使用，互相配合。选择时只问一个问题：这件事的触发条件是什么？ 始终需要 → CLAUDE.md；话题相关时 → Skill；事件触发 → Hook；需要隔离 → Subagent；外部系统 → MCP。

---

二、为什么 Skill 需要优化：渐进式披露

Skill 写久了会变胖。最初你把所有东西都塞进一个文件：说明文字、脚本代码、示例、注意事项……随着迭代，文件越来越长，最终变成一个几百行的"大杂烩"。

这带来几个问题：

• 上下文浪费：每次调用 Skill，几百行全部进入上下文，但当次可能只用到其中一小部分
• 维护困难：文档和代码混在一起，更新一处要同步多处
• 可读性差：AI 和人都很难快速定位需要的信息

实践建议：如果你的 SKILL.md 超过 500 行，这就是需要优化的信号。 此时应该停下来审视一下——哪些内容是每次调用都必须加载的，哪些只是偶尔用到的细节？把后者移出去。

解决方案是渐进式披露（Progressive Disclosure）：主文件只保留高层摘要，让 AI 知道"有什么、怎么用"；细节（脚本、模板、工具）放在独立文件里，用到时才读取。

实践方式

skill-name/
├── SKILL.md          ← 精简的主文件：操作说明、调用命令、Key Lessons
├── tool.py           ← 独立的可执行工具
└── scripts/
    ├── template_a.applescript   ← 模板脚本，带占位符
    └── template_b.py

SKILL.md 只放：

• 操作级别说明（每级一两句话）
• 脚本文件索引表（文件名 + 用途）
• 调用命令示例
• Key Lessons（踩坑经验）
• 操作流程和判断逻辑
• Hard Rules（硬性约束）

**脚本文件独立存放：**完整代码、带占位符的模板、可复用的工具脚本。

---

三、如何与 AI 协作优化 Skill

第一步：让 AI 诊断

把你的 Skill 文件给 AI 看，让它分析哪里需要优化：

“看一下这个 SKILL.md，有没有可以精简的地方？脚本是不是应该剥离出去？”

AI 会识别出内嵌脚本、冗余说明、可以外移的内容，并给出建议。

第二步：明确目标，让 AI 执行

对 AI 的建议给出明确指令，比如：

“把所有脚本都剥离到 scripts/ 目录，SKILL.md 里只保留调用说明和引用”

AI 会自动完成拆分、重命名、更新引用，你只需要确认结果。

第三步：验证效果

重构完成后，让 AI 统计行数，对比前后变化，确认 SKILL.md 确实变精简了，同时检查内容没有丢失。

---

四、如何与 AI 协作测试 Skill

优化之后要测试，确保重构没有破坏功能，也确保 Skill 的每个功能真正可用。让 AI 帮你设计并执行测试用例，是最高效的方式。

第一步：让 AI 设计测试矩阵

告诉 AI：“帮我设计这个 Skill 的测试用例，并说明每个测试需要我做什么配合。”

AI 会分析每个功能的依赖条件，把测试分类：

类型	特点	处理方式
全自动测试	无外部依赖，输出可程序化验证	AI 直接执行，自动判断 pass/fail
半自动测试	依赖外部系统（如本地应用）	AI 执行，检查输出格式和内容
人工确认测试	涉及 UI 交互、草稿、消息发送	AI 执行，用户肉眼验收

第二步：先跑全自动测试

无需任何配合，让 AI 直接跑全自动测试，快速建立基线信心。这些测试往往能覆盖 Skill 里最核心的逻辑。

第三步：逐步引入人工确认测试

AI 执行操作后，给出结构化的验收清单：

TC-XX 验收清单：
- [ ] 预期窗口是否打开？
- [ ] 字段 A 是否正确？
- [ ] 字段 B 是否正确？
- [ ] 操作是否未自动触发不可逆行为？

你只需要对照截图逐条确认，反馈"通过"或"有问题"。

第四步：测试驱动发现 Bug

测试过程中往往会发现你自己没注意到的 Bug。AI 会逐层分析失败原因，通常遵循以下路径：

1. 复现问题（确认不是偶发）
2. 缩小范围（哪一层出了问题）
3. 读源码找根因
4. 修复并回归验证

重要原则： 不是所有问题都值得修复。有些限制是结构性的（比如某 API 本身的约束），把它记录到 ## Known Limitations 里，比强行绕过更合理。

---

五、Skill 的关键 Frontmatter 属性

一个 Skill 文件的开头是 YAML frontmatter，支持以下关键属性：

---
name: my-skill
description: 触发条件和能力描述
model: opus
allowed-tools: Read, Write, Bash
---

description：决定何时触发

description 是最重要的属性，决定 AI 在什么情况下自动调用这个 Skill。

写好 description 的关键：

• 列举触发关键词：把用户可能说的词都覆盖到
• 说清楚能做什么：让 AI 知道这个 Skill 的能力边界
• 用 “Always trigger when…” 句式：明确触发条件

# 不够好
description: 处理 Outlook 邮件相关任务。

# 更好
description: Use this skill for ANY Outlook-related tasks, including reading
  emails, searching history, drafting replies, and creating new drafts.
  Always trigger when user mentions Outlook, emails, inbox, or drafts.

model：为不同复杂度指定模型

model: opus    # 最强推理能力，适合复杂分析和高质量生成
model: sonnet  # 默认，平衡性能与速度
model: haiku   # 最快，适合简单、高频任务

使用建议：

Skill 类型	推荐模型
复杂内容分析、多步骤决策	opus
常规代码生成、文件操作	sonnet（默认）
简单查询、格式转换、高频调用	haiku

对于涉及复杂判断或高质量输出要求的 Skill（比如邮件回复、文档分析），指定 model: opus 可以明显提升结果质量。

allowed-tools：限制工具范围

默认情况下 AI 可以使用所有工具。通过 allowed-tools 可以限制 Skill 的工具边界，值为逗号分隔的工具列表：

# 只读型 Skill（查询、分析类）
allowed-tools: Read, Bash

# 文件操作型 Skill
allowed-tools: Read, Write, Edit, Bash

# 系统自动化型 Skill
allowed-tools: Bash, Read, Write

限制工具范围的好处：

• 防止 AI "越界"操作（比如邮件 Skill 不应该能修改代码库）
• 降低误操作风险，提高可预期性
• 让 Skill 的行为边界对用户更透明

---

六、Skill 的优化正循环

Skill 不是一次性写好就完事的。每一轮使用都会暴露新的问题、积累新的经验，推动 Skill 进入下一轮优化——这是一个持续向好的正循环。

---

基于 openclaw + Claude Code 实践整理，2026-03-20

---

参考资料

• 部分内容参考：Introduction to Agent Skills - Anthropic