Claude Code Skill 参数化与动态上下文注入实战

flowchart LR
    A["/release-preflight v1.4.0"] --> B["1. 参数替换<br/>$ARGUMENTS / $N / 命名参数"]
    B --> C["2. 上下文注入<br/>!`command` 在 Claude 之前执行"]
    C --> D["3. 渲染后的 SKILL.md<br/>作为单条消息注入对话"]
    D --> E["Claude 按指令<br/>调用工具完成任务"]
    E --> F["结果返回主对话<br/>SKILL.md 内容常驻本会话"]

mkdir -p ~/.claude/skills/release-preflight/scripts

---
name: release-preflight
description: 发布前自检。当用户要打 tag、发版、上线前做合规与质量检查时使用。
argument-hint: [version]
arguments: [version]
disable-model-invocation: true
---

## 发布目标
即将发布版本:**$version**

## 当前仓库快照
- 当前分支:!`git rev-parse --abbrev-ref HEAD`
- 最新提交:!`git log -1 --pretty=format:'%h %s'`
- 未提交文件:!`git status --porcelain | head -20`

## 自检清单
1. 若上述"未提交文件"非空,先提示用户提交或 stash,不要自动 commit。
2. 跑测试脚本:${CLAUDE_SKILL_DIR}/scripts/check.sh
3. 检查 CHANGELOG 是否包含 $version。
4. 给出"可以打 tag $version"或"阻塞项"结论。

## 发布目标
即将发布版本:**v1.4.0**

## 当前仓库快照
- 当前分支:main
- 最新提交:a1b2c3d feat: add export api
- 未提交文件: M src/api.py

## 自检清单
1. 若上述"未提交文件"非空,先提示...
2. 跑测试脚本:/home/you/.claude/skills/release-preflight/scripts/check.sh
...

---
name: release-preflight
description: 发布前自检。
argument-hint: [version]
arguments: [version]
disable-model-invocation: true
allowed-tools:
  - Bash(${CLAUDE_SKILL_DIR}/scripts/check.sh)
  - Bash(git status *)
  - Bash(git log *)
  - Bash(git diff *)
  - Bash(git tag *)
  - Read
  - Grep
---

---
name: pr-xray
description: 对当前 PR 做穿透式评审。用户提到 review PR、看这个 PR、代码评审时使用。
context: fork
agent: Explore
allowed-tools: Bash(gh *) Bash(git *) Read Grep Glob
---

## PR 上下文(运行时注入)

### 变更概览
!`gh pr view --json title,author,additions,deletions,baseRefName,headRefName | jq -r '"标题:\(.title)\n作者:\(.author.login)\n+/-:\(.additions)/\(.deletions)\n分支:\(.baseRefName) ← \(.headRefName)"'`

### 变更文件
!`gh pr diff --name-only`

### CI 状态
!`gh pr checks 2>/dev/null | head -20 || echo "无 CI 检查"`

### 完整 diff(前 400 行)
```! 
gh pr diff | head -400

### 几个易踩的坑

1. **多行命令用代码块**。行内 `!`cmd`` 只适合单行;多行必须用 ` ```! ` 开头的围栏代码块,如上例最后一段。
2. **输出不会被二次扫描**。即一条命令的输出里如果**包含** `!`foo``,它不会被再次执行——这避免了递归注入攻击,但也意味着你不能"用命令生成命令"。
3. **`jq` 在管道里很好用**,但前提是机器装了 `jq`。生产环境建议在 Skill 里加一句 `!`command -v jq || echo "WARN: jq 未安装"`` 做软提示,而不是硬失败。
4. **`context: fork` + `agent: Explore` 的组合**:本 Skill 在一个**隔离的子 Agent** 里运行,它看不到你的对话历史,只有上面这份渲染后的内容作为唯一任务输入。`Explore`/`Plan` 这两个内置 Agent 还会**跳过 CLAUDE.md 和 git status**,所以上下文极小、成本极低,适合"只读分析"类任务。但要注意:fork 模式只适合**有明确任务**的 Skill;如果你的 Skill 只是"一些约定规范"没有任务,子 Agent 收到规范却无事可做,会直接空转返回。

---

## 五、第四步:理解 Skill 的"生命周期",别让它失效

这是最容易被忽略、却最容易导致"Skill 第一次好用、后面就不管用了"的根因。

### 加载与驻留机制

1. **启动时**:Claude Code 只把**所有 Skill 的 name + description** 装进系统提示(这就是为什么 `description` 的前几个词最关键)。完整 SKILL.md **不加载**——这是渐进披露的成本控制点。
2. **调用时**:你或 Claude 触发后,渲染后的 SKILL.md 作为**单条消息**进入对话,并**在剩余整个会话里常驻**。每一行都是**持续**的 token 成本,所以 SKILL.md 要像 `CLAUDE.md` 一样精炼。
3. **压缩时(auto-compaction)**:当上下文被摘要以腾空间时,Claude Code 会把"每个 Skill 最近一次调用"重新挂回,但**每个只保留前 5,000 token**,且所有重挂的 Skill **共享 25,000 token 总预算**,从最近调用的开始填。**结论:一个会话里调用了很多 Skill 之后,最早调用的可能被整体丢弃。**

### 实战建议

```mermaid
flowchart TD
    S1["启动:仅加载 name+description"] --> S2{"用户/Claude 调用?"}
    S2 -->|是| S3["渲染 SKILL.md 注入对话<br/>常驻整个会话"]
    S2 -->|否| S4["零成本待命"]
    S3 --> S5{"上下文触发压缩?"}
    S5 -->|是| S6["每个 Skill 留前 5000 token<br/>总计 25000 token 预算"]
    S6 --> S7["从最近向前填<br/>老的可能被丢弃"]
    S5 -->|否| S8["原样保留"]
    S7 --> S9{"行为似乎失效?"}
    S9 -->|是| S10["重新 /调用一次该 Skill<br/>恢复完整内容"]
    S9 -->|否| S11["继续工作"]

{
  "skillOverrides": {
    "legacy-context": "name-only",
    "deploy": "off"
  }
}

~/.claude/skills/release-preflight/
├── SKILL.md              # 入口:参数 + 注入 + 授权
├── scripts/
│   └── check.sh          # 可执行脚本:测试+lint+CHANGELOG校验
└── reference.md          # 详细检查规则(按需加载,常驻预算外)

#!/usr/bin/env bash
# 发布前自检脚本。退出码非0表示有阻塞项。
set -euo pipefail
VERSION="${1:?用法: check.sh <version>}"
ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
cd "$ROOT"

fail=0
echo "== 测试 =="
if [ -f package.json ]; then npm test --silent || fail=1; fi
if [ -f Makefile ] && make -n test >/dev/null 2>&1; then make test || fail=1; fi
if [ -f pytest ] || [ -d tests ]; then python3 -m pytest -q 2>/dev/null || true; fi

echo "== Lint =="
if [ -f package.json ] && grep -q '"lint"' package.json; then npm run lint --silent || fail=1; fi

echo "== CHANGELOG 校验 =="
if ! grep -q "$VERSION" CHANGELOG.md 2>/dev/null; then
  echo "WARN: CHANGELOG.md 未发现 $VERSION"
fi

echo "== 工作区 =="
if [ -n "$(git status --porcelain)" ]; then
  echo "WARN: 存在未提交改动"
fi

exit $fail

# 发布检查细则

## 阻塞项(必须修复才能发版)
- 任一测试失败
- 存在 console.log / debugger / TODO(发布前)
- 接口签名变更但未更新调用方

## 建议项(可带 warning 发版)
- CHANGELOG 未更新
- 新增依赖未在 README 说明

## 细则参考
完整阻塞/建议项判定见 [reference.md](reference.md),只在需要判定边界情况时读取。

# 1. 赋权
chmod +x ~/.claude/skills/release-preflight/scripts/check.sh

# 2. 进入任意 git 仓库
cd ~/my-project

# 3. 调用
# 在 Claude Code 里输入:
/release-preflight v1.4.0

flowchart TB
    subgraph 编写期["编写期(开发者)"]
        D1["SKILL.md<br/>frontmatter + 正文"]
        D2["scripts/*.sh<br/>可执行脚本"]
        D3["reference.md<br/>按需加载细则"]
    end
    subgraph 运行期["运行期(Claude Code)"]
        R1["/release-preflight v1.4.0"] --> R2["参数替换<br/>\$version = v1.4.0"]
        R2 --> R3["上下文注入<br/>git/gh 命令预执行"]
        R3 --> R4["allowed-tools<br/>免确认授权生效"]
        R4 --> R5["渲染结果作为<br/>单条消息注入"]
    end
    subgraph 执行期["执行期(Claude)"]
        R5 --> E1["调用 check.sh<br/>\${CLAUDE_SKILL_DIR}"]
        E1 --> E2["按需 Read reference.md"]
        E2 --> E3["输出结论"]
    end
    subgraph 生命周期["会话生命周期"]
        E3 --> L1["SKILL.md 常驻"]
        L1 --> L2{"压缩触发?"}
        L2 -->|是| L3["留前5000 token<br/>总预算25000"]
        L2 -->|否| L4["原样保留"]
    end
    D1 -.-> R1
    D2 -.-> E1
    D3 -.-> E2