Day 07 写了一个最小 Skill——三行 frontmatter + 一段 prompt。 生产级 Skill 的 frontmatter 远不止这些。下面这张表把所有可用字段 列清楚，每一个都对应一种行为控制能力。

frontmatter 字段全表

生产级 Skill 模板

# .claude/skills/pr-review/SKILL.md
---
name: pr-review
description: 对当前 PR 做一轮自动评审——查 diff、读相关文件、给出建议
argument-hint: [severity: blocker | nit | optional]
model: sonnet
context: fork
allowed-tools:
  - Bash
  - Read
  - Grep
  - Edit
disable-model-invocation: false
---

请对当前 PR 做一轮代码评审：

1. 分析变更：
   - 运行 !`git diff origin/main...HEAD --stat`
   - 列出改动的文件和大致目的

2. 读取关键文件：使用 Read 工具读取改动量最大的 3 个文件

3. 评审输出：按以下格式给出建议
   - 🔴 BLOCKER: 必须修复才能合并
   - 🟡 NIT: 风格 / 命名 / 小问题
   - 🟢 OPTIONAL: 改进建议

4. 严重程度过滤：用户传入了 $ARGUMENTS——
   只展示 ≥ 该级别的问题（blocker > nit > optional）

触发模式三选一

硬编码的 Skill 只能做一件事——/deploy 永远只能部署到 staging。 用参数化把同一个 Skill 变成一族命令—— /deploy staging、/deploy production、 /deploy preview --skip-tests。

三种参数语法

$ARGUMENTS 实战

# .claude/skills/explain/SKILL.md
---
name: explain
description: 用大白话解释一个函数 / 概念 / 报错
argument-hint: <函数路径 | 概念名 | 报错信息>
---

用户想知道：$ARGUMENTS

请按以下方式回答：
1. 一句话总结：先用一句口语化的话讲清楚
2. 展开：分 3-5 个要点详细说明
3. 实例：给一个最小可运行的代码示例
4. 类比：用一个生活中的类比帮助理解

如果 $ARGUMENTS 看起来是文件路径，请先用 Read 读取该文件。

位置参数 + 动态注入

# .claude/skills/deploy/SKILL.md
---
name: deploy
description: 部署到指定环境(staging / production)
argument-hint: <env> [--skip-tests] [--dry-run]
allowed-tools: [Bash, Read]
disable-model-invocation: true   # 部署是破坏性操作,仅手动
---

## 部署到 $1 环境

当前状态：
- 分支：!`git branch --show-current`
- 最近 commit：!`git log -1 --format='%h %s'`
- 已修改文件：!`git status --short | wc -l`

部署目标：$1
额外参数：$2 $3

请按以下流程执行：

1. 前置检查：
   - 确认 $1 是 staging 或 production
   - 如果 $1 == production，要求用户二次确认
   - 检查所有测试是否通过（除非传了 --skip-tests）

2. 构建：运行 npm run build

3. 部署：
   - staging → npm run deploy:staging
   - production → npm run deploy:prod

4. 验证：等 30 秒后 curl 健康检查端点

参数验证与默认值

# .claude/skills/test-coverage/SKILL.md
---
name: test-coverage
description: 检查指定模块的测试覆盖率
argument-hint: [模块路径,默认 src/]
---

# 如果用户没传参,默认为 src/
module=${1:-src/}

请检查 $module 的测试覆盖率：

1. 运行 !`npx vitest run --coverage $module 2>&1 | tail -30`
2. 列出覆盖率 < 80% 的文件
3. 对前 3 个文件给出补充测试建议

复杂的 Skill 不只是一个 SKILL.md—— 它可以是一整个资源目录： 模板文件、辅助脚本、参考示例、README 文档。 Claude 在执行时可以引用这些资源，让 Skill 变成可携带的"工程包"。

典型目录结构

# .claude/skills/scaffold-component/
scaffold-component/
├── SKILL.md              # 主入口（必需）
├── README.md             # 给人看的使用说明
├── VERSION               # 版本号(可选,便于追踪)
├── templates/            # 模板文件
│   ├── Component.tsx.tpl
│   ├── Component.test.tsx.tpl
│   └── Component.stories.tsx.tpl
├── scripts/              # 辅助脚本
│   ├── render.sh         # 渲染模板
│   └── validate-name.sh  # 校验组件名
├── examples/             # 输入输出示例
│   ├── input.md
│   └── output/
└── docs/                 # Skill 内部参考文档
    └── conventions.md

资源引用方式

引用规则

scaffold-component 完整示例

# .claude/skills/scaffold-component/SKILL.md
---
name: scaffold-component
description: 根据组件名生成 React 组件 + 测试 + Storybook 三件套
argument-hint: <ComponentName> [--with-story]
allowed-tools: [Read, Write, Bash]
---

请为组件 $1 生成三件套：

1. 校验组件名：
   !`./scripts/validate-name.sh $1`

2. 读取三个模板：
   - Read templates/Component.tsx.tpl
   - Read templates/Component.test.tsx.tpl
   - Read templates/Component.stories.tsx.tpl

3. 替换占位符：把 __NAME__ 替换成 $1，
   __name__ 替换成 camelCase 形式

4. 写入文件：
   - src/components/$1/$1.tsx
   - src/components/$1/$1.test.tsx
   - src/components/$1/$1.stories.tsx（仅当参数含 --with-story）

5. 参考：examples/Card/ 是一个完整的输出样例,可以对照风格

Skill 的真正价值在复用—— 你写的 /pr-review 应该所有项目都能用、整个团队都能用、 甚至社区其他人也能用。Claude Code 提供了三层分发位置 + 三种分发方式，覆盖从个人到企业的所有场景。

三层位置（优先级从高到低）

三种分发方式

Git Submodule 模式

# 组织内有一个共享 skills 仓库:
#   github.com/acme/claude-skills
# 包含 /pr-review, /deploy, /security-check 等

# 在新项目中引入:
$ git submodule add git@github.com:acme/claude-skills.git \
    .claude/skills/shared

# 项目内同时保留特有 skill:
#   .claude/skills/shared/    ← submodule(团队共享)
#   .claude/skills/my-deploy/ ← 项目特有

# 升级共享 skill:
$ cd .claude/skills/shared && git pull && cd -
$ git add .claude/skills/shared
$ git commit -m "升级共享 skills 到 v2.3"

版本管理

Skill 不只是"命令"——配合 context fork、agent 隔离、与 Hook 组合， 可以构建出复杂的工程系统。下面是几个最有效的高级模式。

Pattern A · context: fork 子代理隔离

默认 Skill 在主会话里执行，会消耗主会话的上下文窗口。 对于"长任务"（如全项目重构、深度搜索）应该用 context: fork—— 在独立子会话里执行，只把最终摘要返回主会话。

---
name: deep-search
description: 在大型代码库里深度搜索某个 API 的所有用法
context: fork   # ← 关键
model: haiku    # 子代理用便宜模型
---

请深度搜索 $ARGUMENTS 这个 API：

1. 用 Grep / Glob 找出所有调用点
2. 对每个调用点读 5 行上下文
3. 分类：测试 / 生产 / 文档 / deprecated

最终只返回 markdown 表格摘要，不要返回完整列表。

Pattern B · Skill 调用 Skill

# .claude/skills/release/SKILL.md
---
name: release
description: 完整发版流程
---

请按以下步骤发版：

1. 先调用 /pr-review 做一轮自检
2. 如果无 BLOCKER:
   - 运行 npm version $1
   - 调用 /deploy production
3. 最后调用 /changelog 生成发布说明

Pattern C · Hook + Skill 共生

调试与热重载

# 列出所有可用 Skill 及其位置:
$ ls .claude/skills/ ~/.claude/skills/

# Skill 修改后立即生效 —— 无需重启会话
# 但 frontmatter 改了需要重新执行命令才会读取新值

# 在 Claude Code 内查看 skill 加载详情:
$ claude --debug
> /pr-review blocker
# stderr 会打印: 加载 .claude/skills/pr-review/SKILL.md, frontmatter 解析结果...

# 手动测试 Skill prompt 渲染结果:
$ claude -p --bare "/explain useState" --dry-run
# 输出 Skill 渲染后的完整 prompt,不真正调用 LLM

四个递进的动手实验——从带参数的基础 Skill 到完整资源包。 预计 45 分钟，每个 Lab 完成后用 /skill-name <参数> 实际跑一次。

1. 请列出至少 6 个 Skill frontmatter 字段，并说明各自的作用。
2. $ARGUMENTS 与 $1 $2 的区别是什么？分别在什么场景下首选？
3. Skill 资源目录中 templates/ / scripts/ / examples/ 三种子目录分别如何被引用？
4. 跨项目复用 Skill 的三种方式（git / submodule / plugin）各有什么权衡？
5. context: fork 解决了什么问题？什么场景下不应该用？