第 13 章 Skills——可复用的能力单元
...
❓ 引导问题：什么是 Agent Skills？渐进式披露机制如何工作？如何创建和管理自定义 Skill？
📖 13.1 什么是 Agent Skills
Agent Skills（智能体技能）是将专业知识、工作流规范固化为可复用资产的核心工具。本质上是一个模块化的 Markdown 文件，教会 AI 工具在特定场景下按你的方式做事。
Skill = 行为规范 + 专业知识 + 使用时机的组合
Skills 解决了什么问题？
| 问题 | Skills 的解决方案 |
|---|---|
| 团队有自己的代码规范，AI 每次都要手动提醒 | 自动触发：AI 根据任务自动加载相关技能 |
| AI 处理复杂流程时不知道最佳实践 | 知识固化：操作手册一次编写，永久生效 |
| 每次都要写长 Prompt | 一次创建，全团队复用，支持 Git 版本控制 |
| 长 Prompt 占用大量上下文 | 渐进式披露：只加载需要的部分，不浪费上下文 |
| 不同工具（Claude/Copilot/Cursor）各自为战 | 跨平台：同一 Skill 可在多个工具中使用 |
💡 Skills 的核心创新不是"让 AI 变聪明"，而是把提示词 + 资源打包成可复用、可共享的技能包，从临时口头交代变成持久化知识。
📖 13.2 渐进式披露——Skill 如何高效工作
Skills 的关键是渐进式披露（Progressive Disclosure），分三层加载，避免上下文溢出：
| 层级 | 加载时机 | 内容 | 占用 |
|---|---|---|---|
| 层级 1：技能发现 | 始终在系统提示中 | 所有 Skill 的元数据（name + description） | 极小 |
| 层级 2：核心指令 | 判定相关后自动读取 | SKILL.md 正文内容 | 中等 |
| 层级 3：资源文件 | 只在需要时读取或执行 | 附属文件、脚本、示例 | 按需 |
执行流程：用户指令 → Skill 意图识别 → 加载 SKILL.md → 建立工具权限与行为边界 → 结合上下文推理 → 仅在需要时调用外部工具 → 约束整合后输出
📖 13.3 Skill 的最小结构
基本文件结构
my-skill/
└── SKILL.md （唯一必需）
SKILL.md 模板
---
name: your-skill-name
description: What it does and when Claude should use it
allowed-tools: Read, Grep, Glob
argument-hint: [目标文件或目录]
model: claude-sonnet-4-6
---
# Skill Title
## Instructions
Clear, concrete, actionable rules.
## Examples
- Example usage 1
- Example usage 2
## Guidelines
- Guideline 1
- Guideline 2
元数据字段全表
| 字段 | 必填 | 说明 |
|---|---|---|
name | 否 | Skill 名称，默认用目录名，仅小写字母、数字、短横线（最长64字符） |
description | 推荐 | 技能用途及使用场景，Claude 据此判断是否自动触发 |
argument-hint | 否 | 自动补全时显示的参数提示，如 [issue-number] |
allowed-tools | 否 | Skill 激活时无需授权的工具列表 |
model | 否 | Skill 激活时强制使用的模型 |
context | 否 | 设为 fork 时在独立子代理上下文中运行 |
agent | 否 | 子代理类型（配合 context: fork） |
disable-model-invocation | 否 | 设为 true 禁止 Claude 自动触发，仅能手动 /name 调用 |
user-invocable | 否 | 设为 false 从 / 菜单隐藏，仅作为后台增强能力 |
hooks | 否 | 技能生命周期钩子配置 |
动态变量
Skills 支持在内容中使用动态变量：
| 变量 | 说明 |
|---|---|
$ARGUMENTS | 调用时传入的所有参数 |
$ARGUMENTS[N] | 按索引访问参数，如 $ARGUMENTS[0] |
$N | 简写方式，如 $1 表示第一个参数 |
${CLAUDE_SESSION_ID} | 当前会话 ID |
📖 13.4 创建你的第一个 Skill
步骤 1：创建目录
mkdir -p .claude/skills/python-naming-standard
步骤 2：编写 SKILL.md
---
name: python-naming-standard
description: 当用户要求重构、审查或编写 Python 代码时，自动参考此规范
allowed-tools: Read, Grep, Glob
---
## 指令
1. 所有的内部辅助函数必须以 `_internal_` 前缀命名
2. 如果发现不符合此规则的代码，请自动提出修改建议
3. 在执行 `claude commit` 前，必须检查此规范
## 参考示例
- 正确：`def _internal_calculate_risk():`
- 错误：`def _calculate_risk():`
步骤 3：使用
启动 Claude Code 后，直接输入任务：
帮我写一个计算用户折扣的函数
Claude 会自动扫描已安装的 Skills，发现你的请求涉及 Python 代码编写，匹配 python-naming-standard，然后按规范生成 def _internal_get_discount(user_score):。
📖 13.5 多文件 Skill（进阶结构）
为避免上下文膨胀，推荐按职责拆分：
my-skill/
├── SKILL.md # 核心规则
├── reference.md # 详细资料
├── examples/
│ └── good-commit.txt # 示例文件
└── scripts/
└── helper.py # 可执行脚本（不加载，通过工具执行）
在 SKILL.md 中引用资源文件：
查看示例 commit：./examples/good-commit.txt
运行脚本：使用工具执行 ./scripts/process.py
📖 13.6 Skills vs Commands（旧格式）
两种格式均可使用，但新项目推荐 Skills：
| 特性 | Skills（推荐） | Commands（旧格式） |
|---|---|---|
| 存储路径 | .claude/skills/<名称>/SKILL.md | .claude/commands/<名称>.md |
| 触发方式 | 手动 /名称 或 Claude 根据 description 自动触发 | 仅手动 /名称 |
| 多文件支持 | 支持附带模板、示例、脚本 | 单文件 |
| 自动触发 | Claude 根据 description 智能判断 | ❌ 不支持 |
| 跨工具共享 | 符合 Agent Skills 开放标准 | 仅 Claude Code |
📖 13.7 官方市场与资源
注册插件市场
/plugin marketplace add anthropics/skills
安装官方 Skills
/plugin install document-skills@anthropic-agent-skills
/plugin install example-skills@anthropic-agent-skills
手动安装 Skill
npx skills add <owner/repo>
安装后在指令中提及技能名称即可调用，例如 使用 PDF 技能提取表单字段。
相关资源
| 资源 | 地址 |
|---|---|
| Skill 聚合入口 | skills.sh |
| Skills 市场（中文） | skillsmp.com/zh |
| Agent Skills 标准站点 | agentskills.io |
| Anthropic 官方 Skills 仓库 | github.com/anthropics/skills |
| 精选列表 | github.com/ComposioHQ/awesome-claude-skills |
| 自动生成 Skill 的 Skill | github.com/anthropics/skills/tree/main/skills/skill-creator |
📖 13.8 用 skill-creator 创建 Skill
skill-creator 是 Anthropic 官方提供的 Skill 开发助手，提供完整的创建、优化和打包工具链。
安装
npx skills add https://github.com/anthropics/skills --skill skill-creator
安装后输入 /skill-creator 即可启动。
创建流程
想清楚需求
↓
起草 SKILL.md
↓
设计测试用例
↓
运行测试（有 Skill vs 没有 Skill，对比效果）
↓
评估结果（看报告 + 打分）
↓
根据反馈修改 SKILL.md
↓
重复，直到满意
↓
打包成 .skill 文件
典型交互
Claude：这个 Skill 具体做什么？
你：把会议录音的文字稿整理成结构化的会议纪要
Claude：纪要里需要包含哪些内容？
你：会议主题、时间、参与人、讨论要点、决议事项、下一步行动（含负责人和截止日期）
Claude：输出格式是 Word 文档、Markdown，还是直接在对话里回复？
你：输出 Word 文档，有模板，我来上传
回答完问题后，skill-creator 会自动生成 SKILL.md、创建参考文件、验证结构、打包输出。
💡 Skill 是团队知识沉淀的最佳方式。把团队的最佳实践、审查清单、部署流程等写成 Skill，新成员也能获得资深工程师的指导质量。
📖 13.XX 要点总结
- Skills 本质：把提示词 + 资源打包成可复用、可共享的技能包，从临时交代变成持久知识
- 渐进式披露三层：元数据始终加载（极小）→ 核心指令按需加载（中等）→ 资源文件仅在需要时读取
- SKILL.md 结构：YAML frontmatter（name/description/allowed-tools 等）+ Markdown 正文（指令/示例/指南）
- Skills 推荐格式优于旧 Commands 格式——支持自动触发、多文件组织、跨工具共享
- skill-creator 提供完整创建工具链：需求梳理 → 起草 → 测试 → 评估 → 打包，一键生成标准化 Skill
