Skills
解决 Prompt 不可复用、经验无法沉淀、团队能力难以传承的问题，把个人技巧变成可组合的工程资产,本质上是一种按需加载的认知结构,可操作知识,智能体它通过 description 告诉模型：在什么情况下应该加载这项能力,可人为/智能体 都可触发。
触发模式
同一个 Skill 既可以作为斜杠命令使用，也可以让 Claude 自动判断何时需要。
- 人工触发：/skill-name
- 智能体读取：Claude 读取 description, 语意启动后自动加载
设计
导航页 + 详情页
SKILL.md ← 导航页：概述 + 引用（< 500 行）
├── reference.md ← 详情页：具体内容
├── examples.md ← 详情页：使用示例
└── scripts/make.sh ← 工具：可执行脚本
内容书写
Skills Frontmatter 字段详解
Frontmatter 是 SKILL.md 顶部的 YAML 块，配置技能怎么运行（权限、触发方式）；正文 Markdown 告诉 Claude 做什么。
字段一览
| 字段 | 必需 | 类型 | 说明 |
|---|---|---|---|
name | 否 | 字符串 | 技能标识符，也是 /slash-command 名称，默认取目录名 |
description | 推荐 | 字符串 | 告诉 Claude 何时加载此技能，是自动触发的核心依据 |
disable-model-invocation | 否 | 布尔 | 设为 true 禁止 Claude 自动触发，只能用户手动 /name 调用 |
user-invocable | 否 | 布尔 | 设为 false 则用户不可调用，只作为 Claude 的背景知识 |
allowed-tools | 否 | 字符串列表 | 限制技能激活时可使用的工具，形成安全屏障 |
argument-hint | 否 | 字符串 | 自动补全提示，如 [issue-number] |
context | 否 | 字符串 | 设为 fork 时技能在子代理中隔离运行，无主对话上下文 |
agent | 否 | 字符串 | context: fork 时指定子代理类型，如 Explore |
hooks | 否 | 对象 | 技能级别的生命周期钩子，在特定工具调用前后执行脚本 |
paths | 否 | 字符串/列表 | Glob 模式，限制技能仅在匹配文件上自动激活 |
shell | 否 | 字符串 | !command`` 块使用的 shell，bash（默认）或 powershell |
mode | 否 | 布尔 | 设为 true 标记为"模式命令"，修改 Claude 的行为或上下文 |
所有字段均可选，但强烈建议写
description。
description — 技能的灵魂
description 不是给人看的文档，而是给 Claude 看的语义触发器。
写作公式：[做什么] + [怎么做] + [什么时候用]
description: 审查代码质量、安全性和最佳实践。检查 bug、性能问题和风格违规。用于用户请求代码审查、希望获得代码反馈、提到审查更改或询问代码质量时。
disable-model-invocation — 控制谁能触发
适用于有副作用的操作（部署、发消息、提交），防止 Claude 自作主张：
disable-model-invocation: true # 仅用户可通过 /deploy 手动触发
user-invocable — 控制用户可见性
适用于不应作为命令暴露的背景知识（如遗留系统说明）：
user-invocable: false # 用户菜单隐藏，Claude 自动按需加载
allowed-tools — 工具安全屏障
限制技能激活时 Claude 可使用的工具集：
# 只读分析型技能
allowed-tools: Read Grep Glob
# 需要执行命令的部署型技能
allowed-tools: Bash
context: fork — 隔离执行
技能在独立子代理中运行，无法访问主对话历史，适合自包含工作流：
context: fork
agent — 指定子代理类型
与 context: fork 搭配使用，指定隔离运行时的代理类型：
context: fork
agent: Explore # 使用 Explore 代理，擅长代码库探索和调研
主代理只收到子代理的摘要结果，保持主上下文窗口精简。
hooks — 技能级生命周期钩子
在技能激活期间，特定工具调用前后自动执行脚本（安全检查、代码格式化等）：
hooks:
PreToolUse:
- matcher: Bash
command: ./scripts/security-check.sh
PostToolUse:
- matcher: "Write|Edit"
command: ./scripts/lint-fix.sh
paths — 文件范围限定
限制技能仅在操作匹配的文件时自动激活，避免不相关场景加载：
paths: "src/api/**/*.ts"
# 或多个模式
paths:
- "src/api/**/*.ts"
- "src/models/**/*.ts"
完整示例
---
name: code-review
description: 审查代码变更的质量和安全性。用于用户请求审查、提到 review 或询问代码质量时。
disable-model-invocation: false
allowed-tools: Read Grep Glob
---
# Code Review Skill
## 审查步骤
1. 读取变更文件
2. 检查安全漏洞、性能问题
3. 输出审查报告
类型
不同类型的技能在设计上有不同侧重点，以下是主要的两大类型：
参考型： 参考形主要特点如下
---
name: git-commit-guidelines
description: "提供 Git 提交信息规范和示例，适合用于检查提交信息格式、生成标准化提交说明。"
---
# Git Commit Guidelines
一个参考型 Skill，用于给出 Git 提交信息的规范和最佳实践，不要求生成固定输出格式。
## 何时使用
当用户需要：
- "帮我写一条符合规范的提交信息"
- "Git commit message 应该怎么写"
- "提交信息格式规范是什么"
- "检查一下这条提交说明是否合理"
## 参考内容
....
### 提交信息格式
....
- 没有执行步骤：不是先做 A 再做 B，而是"遵循这些规范"。
- 没有输出模板：不要求 Claude 输出固定格式的报告
- 没有设disable-model-invocation(是否禁止智能体自动读取)：Claude 可以自动判断何时需要
- 只读工具：allowed-tools 限制为 Read/Grep/Glob，限制它为只读
任务型
和参考型 相反需要执行步奏，具体的输出模版，给于足够的执行文件权限。
- 常规执行任务型 通过/skill-name 触发，或者智能体自动判断触发时机，执行具体的步骤，输出结构化结果。
---
name: repo-refactor
description: 自动执行代码重构、格式化和提交建议。用于用户请求“帮我修复代码风格”、“重构这个模块”或“请生成可执行的修复步骤”时。
disable-model-invocation: true
allowed-tools:
- Read
- Grep
- Bash
---
# Repo Refactor Skill
## 任务说明
1. 阅读变更文件和代码段
2. 自动检查风格/重构问题
3. 生成修复命令或补丁
4. 返回结构化执行结果
## 输出模板
- status: success|failure
- summary: 简要说明
- steps:
- description: 步骤说明
command: 具体命令或修复建议
command 类型
command 的目录是 .claude/commands/，本质是带参数的提示词模板，必须由用户通过 /command-name 手动触发，不会被智能体自动执行。
与 Skill 的核心区别：
| 对比项 | Skill（SKILL.md） | Command（.claude/commands/） |
|---|---|---|
| 触发方式 | 用户手动 + 智能体自动 | 仅用户手动 /name |
| 有 description | 是（语义触发器） | 否 |
| 有 frontmatter | 是（完整配置） | 否（纯 Markdown） |
| 适用场景 | 可复用的认知能力 | 一次性的参数化任务 |
示例：翻译文件
文件路径：.claude/commands/translate.md
将指定文件翻译为目标语言。
步骤：
1. 读取需要翻译的文件
2. 保持原有格式（Markdown 标记、代码块、链接等不变）
3. 翻译后写入同目录下的新文件，文件名添加语言后缀（如 README.en.md）
目标语言和文件路径：$ARGUMENTS
使用方式：/translate en README.md
skill+command 结合使用
command 虽然能人工执行，我们可以通过hook 的方式去去执行，也可以为单独的skill 配置 command 如：
---
name: api-migration
description: api/ 下已存在的 App API 函数，并完成返回数据映射适配。
argument-hint: "[接口地址] 要改为的新 App API 接口地址，如 /img/list"
license: MIT
metadata:
author: libokaifa
version: "1.0"
hooks:
PostToolUse:
- matcher: "Edit|Write"
hooks:
- type: command
command: "test -f .claude/.migration-active && cat .claude/skills/api-migration/review-checklist.md || true"
timeout: 5000
statusMessage: "API 迁移代码审查中..."
---
**前置操作**：技能开始时，必须先执行 `touch .claude/.migration-active` 创建标记文件，以激活 PostToolUse 审查 hook。
**最后执行**： `rm -f .claude/.migration-active` 移除标记文件**，关闭
聪明的你发现示例中配置了前置条件和最后执行，因为hook 在 setting.json 的配置
"hooks": {
"PostToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{
"type": "command",
"command": "test -f .claude/.migration-active && cat .claude/skills/api-migration/review-checklist.md || true",
"timeout": 5000
}
]
}
]
}
在执行任务型的skill 后都会触发，这里是为了某个command为某一个或多个 skill 服务，通过标记的方式来触发执行单独的执行特定command。当然你也可以单独添加执行步奏在skill内，但这样就做不到command的单一性，可复用性和范围性。
总结
skill 的使用，和代码的封装逻辑类似，对于主Agent 来说，子Agent 是个黑盒执行，只分析结果。 另外还可以跨会话拿上下文，在对应的skill 放置 参数 ${CLAUDE_SESSION_ID} 。
CLAUDE_SESSION_ID: 位置Session ID = UUID v4，对话启动时自动生成， 日志位置 = ~/.claude/projects/{project-hash}/{session-id}.jsonl，子代理日志在同名目录的 subagents/ 下。
同时opus 4.7 已经发布 更擅长跨会话,可不用单独配置 CLAUDE_SESSION_ID
opus 4.7+ 当你和Claude进行跨越多个会话的长期协作时，它能够更好地保持上下文的连续性。这在大型软件开发项目、长期研究任务等场景中非常实用
