AI Agent / 系统课时
创建与使用 Skills
创建与使用 Skills
当你反复粘贴同一套检查清单、代码规范或发布步骤时,应该把它封装为 Skill。Skill 以 SKILL.md 为入口,可以附带模板、示例和脚本,并在相关任务出现时按需加载,减少重复提示和上下文占用。
学习目标
- 创建项目级 Skill 并编写有效说明
- 使用参数与工具范围控制技能行为
- 能直接调用并验证 Skill 是否被发现
Skill 的目录与加载方式
项目 Skill 位于 .claude/skills/<skill-name>/SKILL.md,只对当前项目生效;个人 Skill 位于 ~/.claude/skills/<skill-name>/SKILL.md,可用于所有项目。完整正文只在 Skill 被调用时进入上下文,描述则帮助 Claude 判断何时自动使用。:contentReference[oaicite:12]{index=12}

一个 Skill 至少需要 SKILL.md。其他文件用于承载较长模板、示例输出或验证脚本,避免把所有内容堆进入口文件。目录名决定项目 Skill 的命令名,例如 review-api 对应 /review-api。
创建一个 API 审查 Skill
创建 .claude/skills/review-api/SKILL.md:
---
name: review-api
description: 审查 REST API 变更中的兼容性、鉴权、错误码和测试覆盖;当用户要求评审接口或 API 修改时使用。
argument-hint: [文件或目录]
allowed-tools: Read Grep Glob
---
审查 $ARGUMENTS 指定的接口代码。
按以下顺序输出:
1. 识别公开路径、请求方法和输入结构。
2. 检查鉴权、参数校验与敏感数据暴露。
3. 检查响应结构、错误码和向后兼容性。
4. 检查正常、异常和权限测试。
5. 只报告有证据的问题,并引用文件路径与行号。description 应先写清“做什么、何时使用”,因为 Claude 主要依靠它判断是否自动触发。$ARGUMENTS 接收命令后的参数。allowed-tools 只在调用该 Skill 的当前回合预批准列出的工具,并不会永久扩大整个会话权限。:contentReference[oaicite:13]{index=13}
调用并验证 Skill
在 Claude Code 中直接输入:
/review-api src/api预期结果
Claude Code 加载 review-api 的完整说明,读取 src/api,并按兼容性、鉴权、错误码和测试覆盖输出审查结果。也可以用自然语言提出“评审这个 API 改动”,让 Claude 根据描述自动选择 Skill。对于发布、提交或发送消息等有副作用的流程,建议加入 disable-model-invocation: true,只允许用户显式调用,避免 Claude 自行决定执行时机。:contentReference[oaicite:14]{index=14}
设计高质量 Skill 的边界
Skill 应解决一个稳定、可重复的任务,而不是复制整份项目说明。事实性约定放 CLAUDE.md,多步骤过程放 Skill。主文件保持短小,把大模板和详细规范放到子文件,并在正文中说明何时读取。若 Skill 经常误触发,收紧描述;若从不触发,加入用户真实会说的关键词和具体场景。
不要在 Skill 中预批准宽泛的 Bash(*),也不要把真实凭据写进示例。项目 Skill 来自仓库,启用其工具授权前应先审查并确认工作区可信。