一、为什么今天必须关心 Agent Skills？
过去半年，AI 编程工具从“聊天框”进化成“可插拔同事”。
Claude Code 的 Agent Skills 就是这场进化的“插件标准”——它把 Prompt 从一次性对话变成了可版本化、可复用、可分发的能力模块。
一句话总结：
Skill = 把 Prompt 封装成函数，让 Claude 在合适场景自动调用。
二、Agent Skills 到底是什么？
官方定义
“A Skill is a markdown file that teaches Claude how to do something specific.”
拆成白话：
| 概念 | 类比 | 作用 |
|---|---|---|
| Skill 文件 | 一个 .py 文件 | 定义“函数体” |
| description 字段 | 函数名 + docstring | 让 Claude 知道“何时调我” |
| 目录层级 | Python 包路径 | 解决作用域与优先级 |
| 支持文件 | 同目录资源 | 实现“渐进披露”，省 token |
调用链路（简版）
用户输入 → 语义匹配 description → Claude 自动加载 SKILL.md → 按指令执行 → 返回结果
三、30 秒看懂生命周期
-
Discovery
启动时只加载所有 Skill 的name + description，O(1) 时间复杂度，毫秒级。 -
Activation
用户请求与 description 做向量相似度 ≥ 阈值时，Claude 弹出确认框：“是否使用 xxx Skill？” -
Execution
把整份 SKILL.md 塞进上下文，按 Markdown 指令执行；支持调用脚本、读取同目录文件，但只在需要时载入，防止爆窗。
四、写第一个 Skill——“图解代码解释器”
1. 创建目录
mkdir -p ~/.claude/skills/explain-with-diagram
cd ~/.claude/skills/explain-with-diagram
2. 新建 SKILL.md
---
name: explain-with-diagram
description: 用 ASCII 图和类比解释代码。当用户问“这段代码怎么工作”时自动触发。
---
## 指令
1. 先给生活化类比
2. 画 ASCII 流程图
3. 逐行讲解
4. 指出一个易错点
5. 保持口语化
3. 重启 Claude Code
# 退出当前会话重新进
claude
4. 验证
What Skills are available?
能看到 explain-with-diagram 即成功。
5. 实战
打开任意源文件，输入
“How does this work?”
Claude 会弹出确认框，随后输出带图、带类比、带踩坑提示的解读。
五、4 个核心设计技巧
| 技巧 | 反面教材 | 正面示例 |
|---|---|---|
| description 写满关键词 | “Handle PDFs” | “Extract text/tables, fill forms, merge PDFs. Use when user mentions PDF, forms, document extraction.” |
| 渐进披露 | 把 2000 行 API 文档全贴进 SKILL.md | 主文件 <500 行，详细文档放同目录，用时再读 |
| allowed-tools 白名单 | 让 Claude 自己猜能不能写文件 | allowed-tools: [Read, Grep] 明确只读 |
| 作用域隔离 | 在根目录放个人 Skill | 项目级放 .claude/skills/，团队共享；个人放 ~/.claude/skills/，跨项目生效 |
六、Skills vs 其他扩展方式速查表
| 方式 | 触发方式 | 典型场景 | 是否自动 |
|---|---|---|---|
| Skills | 语义匹配 | 教 Claude 业务规则、编码规范 | ✅ |
| Slash Commands | 手动 /cmd | 一键部署、快捷指令 | ❌ |
| CLAUDE.md | 每次对话加载 | 项目级全局指令 | ✅ |
| Subagents | 委托子会话 | 隔离敏感操作 | 半自动 |
| Hooks | 事件监听 | 保存即 lint | ✅ |
| MCP Servers | 提供工具 | 给 Claude 新 API | ✅ |
七、常见问题 60 秒排查
| 症状 | 90% 原因 | 一行命令 |
|---|---|---|
| Skill 不触发 | description 太泛 | 加具体动词+关键词 |
| 加载失败 | YAML frontmatter 语法错 | 在线 YAML linter |
| 脚本权限拒 | 没执行权 | chmod +x scripts/*.py |
| 插件 Skill 消失 | 缓存未刷新 | rm -rf ~/.claude/plugins/cache |
八、下一步：把 Skill 推到生产
-
团队级共享
把.claude/skills/目录 commit 进仓库，CI 里加claude --validate-skills做 PR 检查。 -
企业级下发
管理员通过 Managed Settings 推送 Skill 到全员，路径见官方 IAM 文档。 -
商业化
打包成插件上传到 Marketplace，一次编写，多仓库复用。
九、一句话总结
Agent Skills 让 Prompt 从“对话”升级为“可安装软件”。
今天写 10 行 YAML，明天你就拥有一位随叫随到、永不遗忘、可版本回滚的“资深同事”。
附录
官方深度架构解读：Equipping agents for the real world with Agent Skills
最佳实践白皮书：Authoring best practices
