skill-architecture

技能架构

创建高效 Claude Code 技能的综合指南，遵循 Anthropic 官方标准，重点关注安全性和渐进式披露架构。

自我演进的技能：此技能会在使用过程中不断改进。如果指令有误、参数发生偏移，或需要采用变通方案，请立即修复此文件，不要拖延。

范围：Claude Code Agent Skills（~/.claude/skills/），不包括 Claude.ai API skills

自我演进协议

此技能及其创建的每个技能都必须在使用过程中主动演进。此部分置于最前，因为它约束所有其他部分。

执行期间，留意以下信号：指令造成阻碍、缺少边缘情况、发现更好的模式、反复出现的手动步骤、文档与实际情况不一致。

编写任何更改前，必须通过以下三个准入关卡：

关卡	问题	未通过 →
VALUE	这是否修复了经实际观察到的问题，而非臆测的问题？	跳过
REDUNDANCY	这是否已记录，或可从代码中显而易见？	跳过
FRESHNESS	下个月这是否仍然成立，还是仅为暂时情况？	跳过

大多数执行都应该不产生任何演进。趋于稳定是成功，而非停滞。

所有关卡均通过时：暂停当前工作 → 修复 SKILL.md 或参考文件 → 在 evolution-log.md 中记录触发原因和证据 → 恢复工作。不要拖延——下一次调用会继承你留下的内容。

绝不可通过关卡的情况：重大结构性更改（先与用户讨论）、没有实证支持的推测性改进、表面偏好。

---

何时使用此技能

在以下情况下使用此技能：

• 从头创建新的 Claude Code 技能
• 了解技能 YAML 前置元数据和结构要求
• 验证技能文件格式和可移植性
• 了解技能的渐进式披露模式

---

任务模板

开始技能相关工作前，选择合适的模板——模板包含常见工作流，可防止遗漏导致静默失败的步骤。

请参阅任务模板，了解所有模板（A-F）和质量检查清单。

模板	用途
A	创建新技能
B	更新现有技能
C	向技能添加资源
D	转换为自我演进的技能
E	排查技能未触发的问题
F	创建生命周期套件

---

更改后检查清单（自我维护）

修改此技能（skill-architecture）后：

1. 模板和 6 Steps 教程保持一致
2. 技能质量检查清单反映当前最佳实践
3. references/ 中所有引用的文件均存在
4. 将更改追加到 evolution-log.md
5. 如果触发条件发生变化，更新用户的 CLAUDE.md

---

---

关于技能

技能是模块化、独立的程序包，可通过专业知识、工作流和工具扩展 Claude 的能力。可以将它们视为特定领域的“入门指南”——为 Claude 赋予程序性知识，将通用型助手转变为专业 Agent，而这些知识是任何模型都无法完全掌握的。

技能提供的内容

1. 专业工作流 - 针对特定领域的多步骤流程
2. 工具集成 - 使用特定文件格式或 API 的说明
3. 领域专业知识 - 公司专属知识、架构、业务逻辑
4. 捆绑资源 - 用于复杂或重复任务的脚本、参考资料和素材

技能发现与优先级

技能会从多个位置发现。名称冲突时，优先级较高者生效：

1. 企业级（托管设置）——优先级最高
2. 个人级（~/.claude/skills/）
3. 项目级（仓库中的 .claude/skills/）
4. 插件级（带命名空间：plugin:skill-name）
5. 嵌套级（子目录中的 monorepo .claude/skills/——自动发现）
6. --add-dir（CLI 标志，实时更改检测）——优先级最低

管理命令：

• claude plugin enable <name> / claude plugin disable <name> ——启用或停用插件
• claude skill list ——显示所有已发现技能及其来源位置

Monorepo 支持：Claude Code 会自动发现 monorepo 内嵌套项目根目录中的 .claude/skills/ 目录。无需配置。

---

cc-skills 插件架构

本节仅适用于 cc-skills marketplace 插件结构。通用的独立技能不受影响。

规范结构

plugins/<plugin>/
└── skills/
    └── <skill-name>/
        └── SKILL.md   <- single canonical file (context AND user-invocable)

skills/<name>/SKILL.md 是唯一事实来源。单独的 commands/ 层已被移除——它要求每项技能都维护两个相同的文件，并导致 Skill() 调用返回“Unknown skill”。完整背景请参阅迁移问题。

技能如何成为斜杠命令

支持以下两种安装路径：

路径	机制	备注
自动化（主要）	moon run repo:release-full -> sync-commands-to-settings.sh 读取 skills/*/SKILL.md -> 写入 ~/.claude/commands/<plugin>:<name>.md	发布后全自动执行。绕过 Anthropic 缓存问题 #17361、#14061
官方 CLI	claude plugin install itp@cc-skills -> 从插件缓存中的 skills/ 读取	更新后缓存可能不会刷新——新版本发布后请使用 claude plugin update

Hooks

sync-hooks-to-settings.sh 直接读取 hooks/hooks.json -> 合并到 ~/.claude/settings.json。绕过路径重新展开问题 #18517。

在 cc-skills 中创建新技能

将 SKILL.md 放在 plugins/<plugin>/skills/<name>/SKILL.md 下。无需复制到 commands/。验证器（bun scripts/validate-plugins.mjs）会检查 frontmatter 是否完整。

---

技能创建流程

详细的 6 步操作指南，请参阅创建教程；带示例的完整指南，请参阅创建工作流。

快速概述：收集需求 -> 规划资源 -> 初始化 -> 编辑 SKILL.md -> 验证 -> 注册并迭代。

---

测试与迭代

优秀的技能来自测试和反馈，而不是追求一次就写出完美的初稿。编写或更新技能后，请使用贴近实际的提示词运行技能，验证其是否有效。

编写测试提示词

设计 2-3 个真实的测试提示词——就像真实用户会提出的那种。不要写抽象请求，而要写包含足够细节、能检验技能的具体任务。运行前先发给用户确认。

运行并评估

针对每个测试提示词，运行技能并检查输出：

• 技能是否触发？ 如果没有，说明描述可能需要更明确的触发语句。
• 是否遵循了工作流？ 检查指令是否得到遵循，还是被忽略。
• 输出是否有用？ 将结果与熟练的人类专家会给出的预期结果进行比较。

如果有子 Agent 可用，请并行运行使用技能和不使用技能的版本，以衡量技能的实际价值。如果没有子 Agent，请自行运行测试用例进行基本检查。

根据反馈迭代

评估结果后，改进技能并重新测试。持续迭代，直到用户满意或反馈持续积极。每次迭代都遵循以下关键原则：

1. 从具体反馈中归纳规律。 技能会用于各种提示词。避免针对测试用例中的细枝末节过度调整。如果某种问题反复出现，请尝试不同的方法或比喻，而不是不断增加约束。

2. 保持技能精简。 每个章节都必须值得占用 Token。阅读执行记录——如果技能导致模型在无效步骤上浪费时间，就删掉这些指令，看看效果如何。

3. 解释原因，而不只是说明做法。 LLM 更容易理解为什么要遵循规则，而不是接受僵硬的命令。与其写“始终执行 X”，不如解释：“执行 X，因为跳过它会导致 Y，进而造成 Z。”这样能让模型更稳健地举一反三，而不是把指令当作随意设定的限制。

4. 留意测试用例中重复的工作。 如果每次测试都独立创建相同的辅助脚本，或采用相同的多步方法，就将该脚本放入 scripts/，以免后续调用重复编写。

5. 将常见模式封装为脚本。 如果测试运行显示模型每次都会编写类似的样板代码，就将其提取为附带脚本。这样可以节省 Token 并提高可靠性。

---

技能编写原则

以下原则与 Anthropic 的官方指南一致，适用于所有技能内容：

• 使用祈使句：“运行脚本”“检查输出”——不要使用被动或间接的表述。
• 解释推理过程，而不是设定僵硬规则：如果你发现自己在用全大写字母写 MUST/NEVER/ALWAYS，就该换一种表达方式。解释原因，让模型理解并内化原则，而不是把它当成随意设定的限制。模型很聪明——帮助它理解，而不只是发号施令。
• 在触发描述中积极声明适用范围：Claude 往往不容易触发技能。描述应主动明确适用场景：“只要用户提到 X、Y 或 Z，就使用此技能，即使用户没有明确要求。”也要说明不适用的情况：“A 或 B 不要使用此技能。”
• 使用自然语言描述：描述应像人写的句子，而不是关键词列表。“只要……就使用此技能”比“触发词 - 关键词 1、关键词 2”更好。
• 不要在描述中写执行步骤：描述告诉 Claude 何时触发，技能正文则告诉 Claude 如何执行。不要混为一谈。

详见编写指南，其中包含更多说明和示例。

---

技能结构

skill-name/
├── SKILL.md                      # Required: YAML frontmatter + instructions
├── scripts/                      # Optional: Executable code (Python/Bash)
├── references/                   # Optional: Documentation loaded as needed
│   └── evolution-log.md          # Required for self-evolving: Change history
└── assets/                       # Optional: Files used in output

YAML Frontmatter（必需）

完整的字段参考、调用控制表、权限规则、描述指南和 YAML 常见问题，请参阅 YAML Frontmatter 参考。

最简示例：

---
name: my-skill
description: Does X when user mentions Y. Use for Z workflows.
---

关键规则：name 使用小写字母并以连字符分隔；description 必须是单行，最多 1024 个字符，并包含触发关键词；描述文本中不能使用冒号。

渐进式披露（3 个级别）

技能采用渐进式加载，以高效管理上下文：

1. 元数据（名称 + 描述）- 始终位于上下文中（约 100 个单词）
2. SKILL.md 正文 - 技能触发时加载（少于 5k 个单词）
3. 捆绑资源 - Claude 按需加载（无限*）

*脚本无需读入上下文即可执行。

技能描述预算

技能会根据描述的相关性加载到上下文窗口中。预算超出时，较大的技能可能会被排除：

• 预算：约占上下文窗口的 2%（备用上限为 16K 个字符）
• 检查：运行 /context，查看已加载和已排除的技能
• 覆盖：设置 SLASH_COMMAND_TOOL_CHAR_BUDGET 环境变量以增加预算
• 缓解措施：保持 SKILL.md 正文精简，将详细内容移至 references/

---

捆绑资源

技能可以包含 scripts/、references/ 和 assets/ 目录。关于何时使用这些目录，请参阅渐进式披露中的详细说明。

---

CLI 专属功能

CLI 技能支持使用 allowed-tools 授予工具访问权限，无需每次使用时都请求批准。详情请参阅安全实践。

字符串替换

技能正文支持以下替换（加载时解析）：

变量	解析为	示例
$ARGUMENTS	来自 /name arg1 arg2 的完整参数字符串	Process: $ARGUMENTS
$ARGUMENTS[N]	第 N 个参数（从 0 开始计数）	File: $ARGUMENTS[0]
$N	$ARGUMENTS[N] 的简写	$0 = 第一个参数
${CLAUDE_SESSION_ID}	当前会话 UUID	日志关联

动态上下文注入

在技能正文中使用模式 ! + `command`（感叹号后跟用反引号括起来的命令），即可在加载时注入命令输出：

Current branch: <exclamation>`git branch --show-current`
Last commit: <exclamation>`git log -1 --oneline`

（在实际使用中，将 <exclamation> 替换为 !。）

技能加载时会运行该命令，其输出将内联替换该模式。

扩展思考

在技能正文中加入关键词 ultrathink，即可为该技能的执行启用扩展思考模式。

---

结构模式

关于以下模式的详细说明，请参阅结构模式：

1. 工作流模式 - 多步骤顺序流程
2. 任务模式 - 特定且范围明确的任务
3. 参考模式 - 知识库
4. 能力模式 - 工具集成
5. 套件模式 - 多技能生命周期管理（引导、运行、诊断、配置、升级、拆除）

---

用户约定集成

此技能遵循常见的用户约定：

• 绝对路径：始终使用完整路径（兼容终端中的 Cmd+单击）
• 仅限 Unix：macOS、Linux（不支持 Windows）
• Python：使用带有 PEP 723 内联依赖项的 uv run script.py
• 规划：适用时使用 OpenAPI 3.1.1 规范

---

市场脚本

关于市场脚本的用法，请参阅脚本参考。

---

参考文档

如需了解详细信息，请参阅：

• 任务模板 - 模板 A-F 和质量检查清单
• 创建教程 - 6 步创建流程详解
• YAML Frontmatter - 字段参考、调用控制、描述指南
• 结构模式 - 5 种技能架构模式（包括 Suite Pattern）
• 工作流模式 - 工作流技能实现模式
• 渐进式披露 - 上下文管理模式
• 创建工作流 - 逐步流程与示例
• 脚本参考 - Marketplace 脚本用法
• 安全实践 - 威胁与防御（CVE 参考）
• 分阶段执行 - Preflight/Execute/Verify/Reflect/Rectify 模式及变体
• 执行后反思 - 分步技能的强制自我修正模式
• 理论：自我演进技能 - Gemini DR #70 的研究综合（6 个主题）
• 调用控制 - 技能调用模式、权限规则、旧版命令迁移
• 交互模式 - AskUserQuestion 集成模式
• 令牌效率 - 上下文优化
• 高级主题 - CLI 与 API、组合、错误
• 路径模式 - 安全/不安全路径引用（已记录已知错误）
• Bash 兼容性 - Shell 可移植性模式
• 验证参考 - 质量检查清单
• 写作指南 - 语气、基于推理的指令、描述优化
• 脚本设计 - 设计适用于 Agent 使用的脚本
• 故障排除 - 常见问题及解决方案
• SYNC-TRACKING - Marketplace 版本跟踪
• 演进日志 - 此技能的变更历史

---

执行后反思（强制要求）

本节置于最后，确保它是技能退出前处理的最后内容，以最大限度发挥近因效应。

每项技能必须包含“执行后反思”一节——工作流技能、任务技能和能力技能皆如此。这是结构性要求，而非建议。没有它，错误和偏差就会在各会话间悄然重复。任务模式技能也同样容易受到影响：脚本会更改接口、添加参数，错误消息也会与文档不一致。

此技能完成后，在结束前进行反思

0. 确认当前文件。 — 编辑前，找到此 SKILL.md 的规范路径（使用 Glob 搜索此技能的名称）。所有修正都针对此文件及其同级的 references/，绝不可修改其他文档。
1. 哪里出了问题？ — 修复导致问题的指令。如果问题可能再次发生，将其列为反模式。
2. 哪些做法比预期更有效？ — 将其提升为推荐实践，并记录原因。
3. 哪些内容出现了偏差？ — 如果脚本、参考资料或外部依赖与实际情况不再相符，现在就修复。
4. 通过准入关卡。 — 应用 Self-Evolution Protocol（本文件顶部）。所有变更都必须通过 VALUE + REDUNDANCY + FRESHNESS 检查后才能写入。
5. 记录。 — 每项变更都要在演进日志中记录触发原因、修复内容和证据。

不要推迟。下一次调用会继承你留下的一切。

模板：工作流/分步技能

适用于包含多个阶段、演进日志和 references/ 的技能：

## Post-Execution Reflection

After this skill completes, reflect before closing the task:

0. **Locate yourself.** — Find this SKILL.md's canonical path before editing.
1. **What failed?** — Fix the instruction that caused it.
2. **What worked better than expected?** — Promote to recommended practice.
3. **What drifted?** — Fix any script, reference, or dependency that no longer matches reality.
4. **Log it.** — Evolution-log entry with trigger, fix, and evidence.

Do NOT defer. The next invocation inherits whatever you leave behind.

模板：任务模式技能

对于封装 CLI 命令或脚本的单操作技能：

## Post-Execution Reflection

After this skill completes, check before closing:

1. **Did the command succeed?** — If not, fix the instruction or error table that caused the failure.
2. **Did parameters or output change?** — If the script's interface drifted, update Usage examples and Parameters table to match.
3. **Was a workaround needed?** — If you had to improvise (different flags, extra steps), update this SKILL.md so the next invocation doesn't need the same workaround.

Only update if the issue is real and reproducible — not speculative.

完整模式、验证要求和示例，请参阅执行后反思参考。