主题
Skills（技能）
Skills 是用 SKILL.md 文件给 Claude 扩展能力的方式：写一份指令，Claude 在相关时自动调用、或你用 /skill-name 直接触发，且正文只在用到时才加载，几乎不占常驻 context。
你的真实配置
你装了 ~50 个个人技能（~/.claude/skills/ 下）加上插件自带的命名空间技能，是个重度 skills 用户。分三类看：
| 类型 | 你实际有的（举例） | 命令名 |
|---|---|---|
个人技能（~/.claude/skills/<name>/SKILL.md） | gstack 全家桶：qa、cso、investigate、browse、health、retro、learn、design-review、plan-eng-review、make-pdf … | /qa、/cso、/investigate … |
插件命名空间技能（<plugin>:<skill>） | superpowers:brainstorming、code-review:code-review、commit-commands:commit、pr-review-toolkit:review-pr、figma:figma-generate-design、skill-creator:skill-creator | /code-review、/commit … |
| 内置 bundled | /loop、/run、/verify、/init、/security-review | 直接敲 |
你的 gstack 技能在
~/.claude/skills/是个人 scope（所有项目可用）；插件技能带plugin:前缀避免冲突。要看每个技能的真身：cat ~/.claude/skills/qa/SKILL.md。
去真实体验（在你自己的 Claude Code 里）
| 想验证什么 | 这样做 |
|---|---|
| 列出当前能用的全部技能 | 输入 /help（或在 / 菜单里翻） |
| 看某技能的 SKILL.md 真身 | cat ~/.claude/skills/investigate/SKILL.md |
| **model-invoked（Claude 自动调）**实测 | 跟 Claude 说「这个接口报 500，帮我查」——它会自动触发 investigate（其 description 写了报错就用） |
| **user-invoked（你手动 /）**实测 | 直接敲 /qa 测前端、/cso 跑安全审计、/retro 看本周提交 |
| 自己造一个技能 | 敲 /skill-creator，或 mkdir -p ~/.claude/skills/my-skill && $EDITOR ~/.claude/skills/my-skill/SKILL.md |
| 看技能列表是否超预算（占 context） | /doctor |
真实案例 1：把"反复粘的流程"变成技能
你 CLAUDE.md 里写了一套固定约束（中文回复、Edit 优先、用 Explore 探索…）。事实型规则适合放 CLAUDE.md；但如果某段已经膨胀成多步流程（比如「联调前端和 SpringBlade：起 dev → 查 proxy → 验鉴权头 → 跑登录」），就该抽成一个 /lian-tiao 技能——正文只在你调用时才加载，平时零上下文。
yaml
---
description: 前后端联调自检流程。当用户说"联调""对接后端"时使用。
disable-model-invocation: false # 允许 Claude 在相关时自动调
---
## 当前后端状态
!`curl -s -o /dev/null -w "%{http_code}" http://localhost:15800/blade-auth/token || echo "Gateway 没起"`
## 步骤
1. 确认前端 :8000 proxy 指向 :15800
2. 用 Tenant-Id: 000000 + Bearer token 试一个接口
...!`命令` 会在发给 Claude 前先执行、把输出填进去——所以 Claude 一上来就知道 Gateway 起没起。
真实案例 2：有副作用的技能要禁自动调
像 commit-commands:commit、/ship 这种会改 git/发东西的，官方建议设 disable-model-invocation: true，这样只有你敲 /commit 才触发，Claude 不会自作主张提交。你装的 commit-commands 插件正是这个思路。
与你其它配置的关系
- 技能 vs CLAUDE.md：事实/约定 → CLAUDE.md；多步流程 → 技能。你的
AGENTS.md子目录路由（docs/ kj-frontend/ 各有约束）是"事实"，留在 md 里对；但"文档整改全流程"这种就适合做成技能。 - 技能 vs subagent：技能在主对话里跑（共享上下文）；要隔离、不污染主上下文的研究，用
context: fork让技能在子代理里跑（见 Subagents 一节）。
官方文档要点
以下为按官方文档整理的系统性参考。
是什么
Skills（技能）是扩展 Claude Code 能力的机制。你创建一个 SKILL.md 文件写入指令，Claude 就把它加入自己的工具箱：当对话相关时 Claude 自动调用，或你输入 /skill-name 直接调用。和 CLAUDE.md 不同，技能的正文（body）只在被调用时才加载，因此再长的参考资料在没用到前几乎不消耗 context。Claude Code 的 skills 遵循 Agent Skills 开放标准（agentskills.io），可跨多个 AI 工具使用；Claude Code 在标准之上扩展了 invocation control（调用控制）、subagent execution（子代理执行）、dynamic context injection（动态上下文注入）等特性。官方明确：自定义命令（custom commands）已合并进 skills——.claude/commands/deploy.md 与 .claude/skills/deploy/SKILL.md 都会生成 /deploy 且行为一致，旧的 .claude/commands/ 文件继续可用。
怎么工作
- 每个技能是一个目录，以 SKILL.md 为入口（entrypoint），SKILL.md 必需，其他文件（template.md / examples/ / scripts/）可选。
- SKILL.md 由两部分组成：
---之间的 YAML frontmatter（告诉 Claude 何时用）+ 后面的 markdown 正文（被调用时 Claude 执行的指令）。 - 渐进式披露（progressive disclosure）：常规会话中，技能的 description 始终加载进 context 让 Claude 知道有哪些技能可用，但完整正文只在被调用时才加载。
- 调用控制由两个 frontmatter 字段决定：默认你和 Claude 都能调用；
disable-model-invocation: true只允许你手动调用（description 不进 context）；user-invocable: false只允许 Claude 调用（从 / 菜单隐藏）。 - 动态上下文注入（dynamic context injection）：正文里的
!`command`在发送给 Claude 之前先由 Claude Code 执行 shell 命令，用输出替换占位符，所以 Claude 收到的是真实数据而非命令本身。这是预处理，Claude 看不到命令执行过程。 - 替换只对原文件扫描一次，命令输出作为纯文本插入、不再被二次扫描；inline 形式仅当
!位于行首或紧跟空白时才识别。 - 子代理执行：frontmatter 加
context: fork时，技能正文成为驱动子代理的 prompt，在隔离的 context 里运行，看不到你的对话历史；用agent字段指定子代理类型。 - 技能内容生命周期：被调用时，渲染后的 SKILL.md 作为单条 message 进入对话并在整个 session 保留；Claude Code 不会在后续回合重新读取技能文件，所以应写成贯穿任务的常驻指令而非一次性步骤。
- 命令名来源：
~/.claude/skills/或.claude/skills/下取目录名；.claude/commands/下取去扩展名的文件名；plugin 的skills/子目录取目录名并加 plugin 命名空间；plugin 根目录的 SKILL.md 取 frontmattername（无则回退到 plugin 目录名）。 - 同名覆盖优先级：enterprise > personal > project；skill 与同名 command 冲突时 skill 优先；plugin 技能用
plugin-name:skill-name命名空间，不会与其他层级冲突。
怎么配置 / 用法
技能存放位置（决定谁能用）：Personal ~/.claude/skills/<skill-name>/SKILL.md（所有项目可用）；Project .claude/skills/<skill-name>/SKILL.md（仅本项目）；Plugin <plugin>/skills/<skill-name>/SKILL.md；Enterprise 通过 managed settings 部署。
最小 SKILL.md：
yaml
---
description: Summarizes uncommitted changes and flags anything risky. Use when the user asks what changed...
---
## Current changes
!`git diff HEAD`
## Instructions
Summarize the changes above in two or three bullet points...创建示例：mkdir -p ~/.claude/skills/summarize-changes，写入 SKILL.md，然后用 /summarize-changes 或自然语言触发。
常用 frontmatter 字段：name、description、when_to_use、argument-hint、arguments、disable-model-invocation、user-invocable、allowed-tools、disallowed-tools、model、effort、context、agent、hooks、paths、shell。所有字段都可选，仅 description 推荐。
字符串替换：$ARGUMENTS、$ARGUMENTS[N]、$N、$name、${CLAUDE_SESSION_ID}、${CLAUDE_EFFORT}、${CLAUDE_SKILL_DIR}。
子代理执行：frontmatter 加 context: fork + agent: Explore（或 Plan / general-purpose / 自定义）。
多行命令注入用 ```! 围栏代码块。
settings 相关：skillOverrides（控制可见性，写入 .claude/settings.local.json）、disableSkillShellExecution、skillListingBudgetFraction、maxSkillDescriptionChars。权限：在 /permissions 用 Skill（禁全部）/ Skill(commit)（精确）/ Skill(review-pr *)（前缀）。
什么时候用
- 何时建技能：当你反复把同一套指令/清单/多步流程粘进对话；或 CLAUDE.md 里某段已经从『事实』膨胀成了『流程』。
- Reference content（参考类，如 API 约定、风格指南、领域知识）：inline 运行，Claude 在当前工作旁边参考使用。
- Task content（任务类，如部署、提交、代码生成）：常希望用
/skill-name直接调用；加disable-model-invocation: true防止 Claude 自动触发（尤其是有副作用的 /commit、/deploy、/send-slack-message）。 - 背景知识但不该作为命令被用户直接触发：用
user-invocable: false从 / 菜单隐藏（如 legacy-system-context）。 - 需要隔离、独立 context 的研究/分析任务：用
context: fork——但仅适合含明确指令的技能，纯指南类（无任务）forked 后子代理拿不到可执行 prompt，会空跑无输出。 - 正文要保持简洁：技能一旦加载就在整个 session 占 token，按 CLAUDE.md 的简洁标准写，说『做什么』而非『怎么做/为什么』。
限制 / 坑
- description + when_to_use 合并文本在技能列表中被截断到 1,536 字符（上限可用 maxSkillDescriptionChars 配置）；要把关键用例放最前面。
- 技能列表预算默认按模型 context window 的 1%（skillListingBudgetFraction，例 0.02=2%）；溢出时优先丢弃最少用技能的 description（仅 description 被砍，技能名始终保留），可能砍掉 Claude 匹配所需的关键词。用
/doctor看预算是否溢出。 - 自动压缩（auto-compaction）后：每个技能最近一次调用被重新附加，仅保留前 5,000 tokens；所有重新附加的技能共享 25,000 tokens 预算，从最近调用的开始填，调用过多时较早的技能可能被整个丢弃；必要时压缩后重新调用以恢复完整内容。
- Claude Code 不会在后续回合重新读取技能文件——写一次性步骤会失效，应写常驻指令。
context: fork的 Explore/Plan agent 会跳过 CLAUDE.md 和 git status。allowed-tools只是免审批授权、不限制可用工具；要封禁工具需在 permission settings 加 deny 规则。项目.claude/skills/的 allowed-tools 需先接受 workspace trust 对话框才生效——信任仓库前要先审查项目技能，因为技能能给自己授很宽的工具权限。--add-dir//add-dir会加载其中的.claude/skills/，但permissions.additionalDirectories设置只给文件访问、不加载技能；subagents、commands、output styles 也不从附加目录加载。- 会话启动后新建一个之前不存在的顶层 skills 目录，需要重启 Claude Code 才能被监听（已存在目录内的增删改可在当前会话即时生效）。
user-invocable: false只控制 / 菜单可见性，不阻止 Skill tool 程序化调用；要彻底屏蔽用disable-model-invocation: true。shell: powershell需要环境变量CLAUDE_CODE_USE_POWERSHELL_TOOL=1。disableSkillShellExecution: true会把每条 shell 命令替换为[shell command execution disabled by policy]；bundled 与 managed 技能不受影响。- 部分内置命令（/init、/review、/security-review）可通过 Skill tool 调用，但 /compact 等不行。
硬事实速查（29 条）
- 技能目录入口文件必须叫
SKILL.md，其他文件（template.md、examples/、scripts/）可选。 - Personal 路径：
~/.claude/skills/<skill-name>/SKILL.md（所有项目）。 - Project 路径：
.claude/skills/<skill-name>/SKILL.md（仅本项目，提交 VCS 即共享）。 - Plugin 路径：
<plugin>/skills/<skill-name>/SKILL.md，命令名加命名空间如/my-plugin:review。 - 同名覆盖优先级：enterprise > personal > project；skill 与同名 command 冲突 skill 优先。
- frontmatter 字段全集：name、description、when_to_use、argument-hint、arguments、disable-model-invocation、user-invocable、allowed-tools、disallowed-tools、model、effort、context、agent、hooks、paths、shell。所有字段可选，仅 description 推荐。
description缺省时取 markdown 正文第一段；description+when_to_use 列表中合并截断在 1,536 字符。disable-model-invocation默认 false；user-invocable默认 true。effort选项：low、medium、high、xhigh、max（实际可用取决于模型）；${CLAUDE_EFFORT}取值 low/medium/high/xhigh/max——ultracode 不是独立等级，上报为xhigh。context: fork在 forked 子代理 context 运行；agent缺省用 general-purpose，可选 Explore、Plan、general-purpose 或.claude/agents/自定义。shell接受 bash（默认）或 powershell；powershell 需CLAUDE_CODE_USE_POWERSHELL_TOOL=1。paths用 glob 限制激活时机，格式同 path-specific rules。- 字符串替换变量：$ARGUMENTS、$ARGUMENTS[N]（0-based）、$N（如 $0、$1）、$name（按 arguments 列表位置映射）、${CLAUDE_SESSION_ID}、${CLAUDE_EFFORT}、${CLAUDE_SKILL_DIR}。
- 调用带参数但正文无 $ARGUMENTS 时，Claude Code 在正文末尾追加
ARGUMENTS: <your input>。 - 索引参数用 shell 风格引号：
/my-skill "hello world" second使 $0=hello world、$1=second。 - 动态注入 inline 形式
!`command`：仅当!在行首或紧跟空白时识别；KEY=!cmd`` 这类被当字面文本不执行。多行用```!围栏块。 - 替换只对原文件扫描一次，命令输出不被二次扫描。
- 建议 SKILL.md 控制在 500 行以内，详细参考资料拆到单独文件。
- 自动压缩后每个技能保留前 5,000 tokens，重新附加技能共享 25,000 tokens 预算。
- 技能列表预算默认模型 context window 的 1%；用 skillListingBudgetFraction（如 0.02=2%）或 SLASH_COMMAND_TOOL_CHAR_BUDGET（固定字符数）调整；用 maxSkillDescriptionChars 配置 1,536 字符上限。
- /run、/verify、/run-skill-generator 需 Claude Code v2.1.145 或更高；/run-skill-generator 把启动配方提交为
.claude/skills/run-<name>/。 - skillOverrides 四种值：on（名+描述，列出且在/菜单）、name-only（仅名）、user-invocable-only（对 Claude 隐藏但在/菜单）、off（全隐藏）；缺省视为 on；写入
.claude/settings.local.json；plugin 技能不受 skillOverrides 影响（用 /plugin 管理）。 - 权限语法：
Skill(name)精确匹配，Skill(name *)前缀匹配；deny 规则加Skill可禁全部。 - Bundled skills 示例：/code-review、/batch、/debug、/loop、/claude-api，每个 session 都可用，在 commands reference 中标记为 Skill。
- Live change detection：监听
~/.claude/skills/、项目.claude/skills/、--add-dir目录内.claude/skills/的增删改，当前会话即时生效；新建顶层目录需重启。仅覆盖SKILL.md文本——若该 skill 文件夹同时是 plugin，其hooks/、.mcp.json、agents/、output-styles/改动需/reload-plugins才生效。 - Skills-directory plugins：往 skill 文件夹放一个
.claude-plugin/plugin.json，它会作为名为<name>@skills-dir的 plugin 加载，从而可顺带打包 agents/hooks/MCP server；项目.claude/skills/下需先通过 workspace trust 对话框。 - monorepo：项目技能从启动目录到仓库根逐级父目录加载，工作于子目录文件时按需发现嵌套
.claude/skills/（如packages/frontend/.claude/skills/）。 - CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 用于加载 --add-dir 目录的 CLAUDE.md（默认不加载）。
- 正文含
ultrathink可请求更深推理；用/doctor诊断技能列表预算溢出。