Claude Code Skills

Skills 用于封装专门流程，让 Claude Code 不必每次都从提示词重新加载完整步骤，也能按已知流程执行任务。

最近核验: 2026/7/19
适用版本: Claude Code 2.1.x。本机使用 2.1.198 核对 CLI 拼写；官方文档可能描述更新的 2.1.x 行为。
核验方式: 核对当前 skill layout、invocation control、dynamic context、tool preapproval 和 command migration；未把 skill 加载到真实项目或调用模型。
官方来源: Skills Commands reference Changelog

可复现实践

创建 Read-only Skill 并验证 Discovery 边界

以明确调用和 least-privilege tools 封装重复的 repository-status procedure。

准备

唯一临时仓库。
重复出现且比 durable fact 更长的 procedure。
不含不可信 command substitution 或秘密 fixture。

执行步骤

创建 skill fixture

使用 project scope，并在评估期间禁用自动 model invocation。

步骤 1

SKILL_LAB=$(mktemp -d "${TMPDIR:-/tmp}/claude-skill.XXXXXX")
printf '%s\n' "$SKILL_LAB"
cd "$SKILL_LAB" && git init -q
mkdir -p .claude/skills/status-audit
printf '%s\n' '---' 'description: Summarize repository status without editing.' 'disable-model-invocation: true' 'allowed-tools: Bash(git status --short)' '---' '' 'Run git status --short and report only observed changes.' > .claude/skills/status-audit/SKILL.md

检查静态结构
启动 Claude 前确认 frontmatter、filename 和 command name。
步骤 2
```
sed -n '1,12p' .claude/skills/status-audit/SKILL.md
git status --short
```
检查 discovery
打开 `/help` 确认 `/status-audit`；本次未测试交互行为。
验证两种调用路径
先显式调用；只有自然语言 prompt 能可靠且安全选中 skill 后才允许 model invocation。

预期结果

Skill 可按目录名发现、可显式调用，评估期间没有 edit tool 或自动 invocation。

验证

确认 allowed tool 与实际 command 完全匹配。
调用前后比较 `git status --short`。
允许自动调用前用不匹配 prompt 检查 over-triggering。

失败处理

Skill 未显示

检查 workspace trust、scope、`SKILL.md`、YAML 和 description 长度。

Skill 触发过多

收窄 description 或保留 `disable-model-invocation: true`。

清理或回退

返回原目录，只删除打印出的 SKILL_LAB 路径。
通过 reviewed commit 删除 project skill，不广泛删除 personal skills。

边界与不适用场景

Dynamic context command 在 Claude 读取 skill 前执行，应按代码审查其输入。
Allowed tools 降低暴露面，但不能单独使不可信 instructions 安全。

什么时候使用 Skill

当流程会重复出现时适合写 Skill，例如代码审查、发布说明、迁移检查、事故分析、设计实现或仓库特定任务处理。

Skill 应包含什么

有用的 Skill 会说明触发时机、要收集的证据、要运行的命令、要检查的文件和期望输出格式，避免空泛风格建议。

Skills 和项目记忆

项目记忆保存稳定仓库事实；Skills 保存可复用流程。把二者分开，维护成本更低。

Skill 质量

好的 Skill 足够短、足够具体，并能通过真实任务检验。如果需要大量无关引用，应拆成更窄的 Skills。

最小 SKILL.md frontmatter

---
name: release-notes
description: Draft release notes from merged PRs and changelog entries.
---

# Release notes

1. Read CHANGELOG.md and recent git history.
2. Group changes by user impact.
3. Output a concise release summary.