skill-create

Codex 兼容性说明：

• 在 Codex 中使用 $skill-name 调用仓库技能；此镜像副本会改写旧版 Claude /skill-name 引用。
• 任务跟踪要求：执行任何工作流或技能步骤之前，先创建／更新所有步骤的任务跟踪，并随着进度变化保持同步。
• 用户问题提示表示要在 Codex 中直接询问用户。
• 忽略出现的 Claude 专属模式切换指令。
• 严格执行约定：用户明确调用某项技能时，必须按原样执行该技能协议。
• 子 Agent 授权：用户调用或 AI 检测到某项技能，且其协议要求使用子 Agent 时，该技能的激活即授权为该任务使用所需的 spawn_agent 子 Agent。
• 除非用户事先明确批准偏离，否则不得跳过、重排或合并协议步骤。
• 对于工作流技能，必须明确执行列出的每个子技能步骤，并逐步报告证据。
• 如果此环境无法运行必需的步骤／工具，请停止并询问用户，然后再调整方案。

Codex 项目参考资料加载（无钩子）

Codex 不会接收基于 Claude 钩子的文档注入。 编码、规划、调试、测试或审查时，请按以下路由显式打开项目文档。

始终阅读：

• docs/project-config.json（项目专属路径、命令、模块和工作流／测试设置）
• docs/project-reference/docs-index-reference.md（指向完整的 docs/project-reference/* 目录）
• docs/project-reference/lessons.md（始终适用的防护规则和反模式）

按情况阅读文档：

• 后端／CQRS／API／领域／实体变更：backend-patterns-reference.md、domain-entities-reference.md、project-structure-reference.md
• 前端／UI／样式／设计系统：frontend-patterns-reference.md、scss-styling-guide.md、design-system/README.md
• 规格／测试用例规划或 TC 映射：feature-docs-reference.md
• 集成测试实现／审查：integration-test-reference.md
• E2E 测试实现／审查：e2e-test-reference.md
• 代码审查／审计工作：code-review-rules.md，以及根据变更文件选择的领域文档

不要不加区分地阅读所有文档。先从 docs-index-reference.md 开始，然后只打开与任务相关的文件。

快速摘要

目标： 创建结构规范的新 Claude Code 技能，或扫描／修复目录中无效的技能标头。

工作流：

1. 澄清 — 通过直接询问用户，了解用途、触发关键词和所需工具
2. 检查现有内容 — 使用 Glob 查找类似技能，避免重复
3. 搭建框架 — 创建目录和包含 frontmatter 与快速摘要的 SKILL.md
4. 添加 SYNC 块 — 纳入 sync-inline-versions.md 中相关的协议检查清单
5. 验证 — 运行 frontmatter 和标头验证
6. 增强 — 对新建的 SKILL.md 调用 $prompt-enhance，提升注意力锚定质量

关键规则：

• 每个 SKILL.md 都必须将 ## Quick Summary 放在前 30 行内，其中包含目标／工作流／关键规则
• description 必须为单行，以 [Category] 为前缀，并包含触发关键词
• SKILL.md 不得超过 500 行；详细内容使用 references/
• 共享协议必须通过 `` 块内联，绝不能使用文件引用
• 必须在新建／更新的技能上调用 $prompt-enhance，作为最终质量检查

模式

模式	触发条件	操作
创建	$ARGUMENTS 描述一项新技能	按照下方工作流创建技能
扫描与修复	$ARGUMENTS 提及扫描、修复、验证或无效	对所有技能运行验证

SKILL.md 架构参考

Frontmatter 字段（均为可选）

---
name: my-skill # Lowercase, hyphens. Max 64 chars. Default: directory name.
description: '[Category] What it does. Triggers on: keyword1, keyword2.' # MUST ATTENTION be single-line
argument-hint: '[issue-number]' # Autocomplete hint for arguments
disable-model-invocation: false # true = user-only (/name), Claude cannot auto-invoke
user-invocable: true # false = hidden from / menu, Claude-only auto-invoke
context: inline # inline (default) or fork (isolated subagent)
agent: general-purpose # Subagent type when context: fork
model: inherit-4-5 # Model override. Default: session model
version: 1.0.0 # Project convention (non-official)
---

调用控制矩阵

设置	用户调用	Claude 调用	描述
默认	是	是	在上下文中提供描述；调用时加载
disable-model-invocation: true	是	否	仅限用户调用。调用前不会加载到上下文中
user-invocable: false	否	是	在菜单中隐藏。Claude 会自动调用

变量替换

变量	描述
$ARGUMENTS	传递给技能的所有参数
$ARGUMENTS[N] / $N	按从 0 开始的索引指定参数
${CLAUDE_SESSION_ID}	当前会话 ID
!`command`	在技能运行前执行 shell 命令

关键规则

• description 必须为单行（多行 YAML 会导致目录解析失败）
• 在描述中加入触发关键词，以便自动激活
• 使用 [Category] 前缀（例如 [Frontend]、[Planning]、[AI & Tools]）
• SKILL.md 少于 500 行；详细内容放在 references/ 中
• 描述会以上下文窗口的 2% 加载（约 16,000 个字符）
• 在技能内容中加入“ultrathink”，以启用扩展思考模式

模式 1：创建技能

工作流

1. 澄清 — 如果需求不明确，请直接向用户提问，了解：用途、自动调用还是用户调用、触发关键词、所需工具
2. 检查现有技能 — 使用 Glob 查找 .claude/skills/*/SKILL.md 中的类似技能。避免重复。
3. 创建目录 — .claude/skills/{skill-name}/SKILL.md
4. 编写 Frontmatter — 遵循上方 ## SKILL.md Schema Reference 部分中的架构
5. 编写说明 — 简洁、可操作，并采用渐进式披露
6. 添加 SYNC 区块 — 确定适用于此技能的共享协议。读取 .claude/skills/shared/sync-inline-versions.md，并将相关的 `` 区块复制到技能中。常见协议：understand-code-first、evidence-based-reasoning、output-quality-principles
7. 添加结尾提醒 — 在底部使用 :reminder SYNC 区块重申顶层规则，以便强化记忆
8. 添加参考资料 — 如果内容超过 200 行，将详细文档移至 references/ 目录
9. 添加脚本 — 如有需要，创建 scripts/ 目录存放可执行辅助脚本
10. 验证 — 运行 Frontmatter 验证（参见模式 2 的单文件检查）
11. 增强 — 对已完成的 SKILL.md 调用 $prompt-enhance，提升 AI 注意力锚定质量

Frontmatter 模板

---
name: { kebab-case-name }
description: '[Category] What it does. Triggers on: keyword1, keyword2.'
---

技能注意力结构（必须遵循）

[Frontmatter]
[SYNC protocol blocks — top attention zone]
[## Quick Summary — Goal/Workflow/Key Rules]
[Detailed instructions — middle zone]
[## Closing Reminders — bottom attention zone with :reminder SYNC blocks]

原因： AI 在顶部和底部的注意力最强（首因-近因效应）。请在这两个位置放置关键规则。研究支持的原则请参见 $prompt-enhance。

新技能的 SYNC 标签协议

1. 读取 .claude/skills/shared/sync-inline-versions.md — 所有协议检查清单的权威来源
2. 确定技能需要哪些协议（例如，调查类技能需要 understand-code-first + evidence-based-reasoning）
3. 将 `` 开始/结束标签之间的检查清单内容复制到技能顶部
4. 在结尾提醒部分的底部添加 1 行的 :reminder 版本
5. 切勿使用 MUST ATTENTION READ shared/ 文件引用 — 始终将内容内联

规则

• SKILL.md 是说明，不是文档。要教 Claude 如何完成任务。
• description 必须为单行（多行 YAML 会导致目录解析失败）
• 描述必须包含用于自动激活的触发关键词
• 在描述中使用 [Category] 前缀（例如 [Frontend]、[Planning]、[AI & Tools]）
• SKILL.md 少于 500 行；详细内容放在 references/ 中
• 渐进式披露：Frontmatter → SKILL.md 摘要 → 参考文件
• 提高 Token 效率：每一行都必须物尽其用

模式 2：扫描并修复无效技能

验证内容

检查项	规则	严重级别
存在 Frontmatter	必须有 --- 分隔符	错误
描述为单行	描述值中不能有字面换行	错误
描述非空	必须有描述以便于发现	警告
名称格式	小写字母、连字符，最多 64 个字符	错误
无未知官方字段	标记不在官方架构中的字段	信息
描述包含类别	应以 [Category] 开头	警告
文件大小	SKILL.md 应少于 500 行	警告
存在快速摘要	前 30 行中必须有 ## Quick Summary	警告
SYNC 标签配对	每个开始标签都必须有对应的结束标签	错误

扫描工作流

1. 发现 — 使用 Glob .claude/skills/*/SKILL.md 查找所有技能
2. 解析 — 读取每个文件的前 20 行，提取 Frontmatter
3. 验证 — 检查上述每条规则
4. 报告 — 按严重级别分组列出问题（错误 > 警告 > 信息）
5. 修复 — 如果用户确认，自动修复错误级别的问题

验证脚本

node .claude/skills/skill-create/scripts/validate-skills.cjs          # Report only
node .claude/skills/skill-create/scripts/validate-skills.cjs --fix    # Report + auto-fix

要求

$ARGUMENTS

---

[重要] 使用任务跟踪，在开始前将所有工作拆分为小任务。

批判性思维模式 — 运用批判性思维和顺序思维。每项声明都需要可追溯的证据，只有置信度 >80% 才采取行动。 反幻觉： 绝不把猜测说成事实——每项声明都要引用来源，坦诚承认不确定性，自行检查输出是否有误，独立交叉核对，对自己的置信度保持怀疑——没有证据的确定性是所有幻觉的根源。

共享协议重复策略 — 技能中的内联协议内容（包裹在 `` 中）是有意重复的。不要提取、去重或替换为文件引用。将协议放在文件读取间接引用后面，会显著降低 AI 的遵循度。更新时：先编辑 .claude/skills/shared/sync-inline-versions.md，然后搜索 SYNC:protocol-name 并更新所有匹配项。

输出质量 — 在不牺牲质量的前提下提高 Token 效率。

1. 不列清单或数量——AI 可以用 grep | wc -l 获取。数量转眼就会过时
2. 不提供目录树——AI 可以用 glob/ls 获取。使用单行路径约定
3. 不提供目录——AI 会线性阅读。目录浪费 Token
4. 不要用重复规则的示例——只有在不易理解时才提供一个示例
5. 先给答案，不讲推理。省略填充词和开场白
6. 报告中可牺牲语法完整性以追求简洁
7. 如有未解决的问题，放在末尾 AI 错误预防 — 每项任务都要避免的失败模式：

删除前检查下游引用。 删除组件会导致文档和代码级联过时。移除前，先梳理所有引用该组件的文件。 根据实际代码核实 AI 生成的内容。 AI 会幻觉出 API、类名和方法签名。记录或引用之前，务必通过 grep 确认它们确实存在。 编辑后追踪完整依赖链。 更改定义时，可能会漏掉由此派生的下游变量和使用方。务必追踪完整链路。 验证正确性时追踪所有代码路径。 确认代码存在，不代表它会执行。务必追踪提前退出、错误分支和条件跳过，不要只看正常路径。 调试时，先问“这是谁的职责？”，再修复。 追踪问题是在调用方（数据错误）还是被调用方（处理错误）。在责任所在层修复，绝不要只修补症状出现的位置。 假定现有值是有意设置的——更改前先问原因。 更改任何常量、限制、标志或模式之前：先阅读注释、检查 git blame，并查看周边代码。 核实所有受影响的输出，而不只是第一个。 涉及多个技术栈的更改，必须核实每一个输出。一个检查通过，不代表所有检查都通过。 整体优先的调试方式——警惕注意力被最近的问题吸引。 调查任何故障时，先列出所有前置条件（配置、环境变量、数据库名称、端点、DI 注册、数据前置条件），然后逐一依据证据核实，再提出任何代码层面的假设。 精准修改——应用差异测试。 修复 Bug：每一行更改都必须能直接追溯到该 Bug。不要顺手重设相邻代码的样式或改进它。增强任务：实施改进并明确说明。 编码前明确歧义——不要默默选择。 如果请求有多种解释，应列出每种解释及其工作量估算并询问。绝不要擅自假定要处理所有记录、采用基于文件的方案或更复杂的路径。

重要，务必注意 遵循重复内容策略：内联协议是有意为之，绝不要提取到文件引用中

重要，务必注意 遵循输出质量原则：节省 token，答案优先，不说废话

务必注意 运用批判性思维——每项主张都必须有可追溯的证据，只有信心超过 80% 才采取行动。防止幻觉：绝不要把猜测当作事实陈述。

务必注意 落实 AI 错误预防——整体优先的调试方式、在责任所在层修复、编码前明确歧义、压缩上下文后重新阅读文件。

结束提醒

重要，务必注意 开始前先使用任务跟踪，将工作拆解为小型待办任务 重要，务必注意 使用 `` 块内联共享协议——绝不要使用 MUST ATTENTION READ shared/ 文件引用 重要，务必注意 对新建或更新的技能调用 $prompt-enhance，将其作为最终的注意力锚定质量检查 重要，务必注意 在每个 SKILL.md 的前 30 行内加入 ## Quick Summary 重要，务必注意 在每个技能末尾添加包含 :reminder SYNC 块的结束提醒部分 重要，务必注意 遵循 SKILL.md Schema Reference（已在上文内联），使用正式的 frontmatter 字段

[TASK-PLANNING] 行动前，分析任务范围，并使用任务跟踪系统地将其拆解为小型待办任务和子任务。

无钩子提示词协议镜像（自动同步）

来源：.claude/hooks/lib/prompt-injections.cjs + .claude/.ck.json

[WORKFLOW-EXECUTION-PROTOCOL] [BLOCKING] 工作流执行协议 — 强制、重要、必须、关键。无论出于何种原因，都不得跳过。

通用可移植性边界： 可复用的技能和协议文本应与项目无关；从 docs/project-config.json 和 docs/project-reference/ 中查找项目特定约定。应用 shared/sdd-artifact-contract.md 中的共享 AI-SDD。阅读 docs/project-config.json 和 docs/project-reference/docs-index-reference.md，然后打开其中列出的项目参考文档。只要具备此共享上下文和本地文档，任何受支持的 AI 工具都可以执行。

1. 检测： 将提示词与工作流目录进行匹配
2. 分析： 找出最匹配的工作流，并评估自定义步骤组合是否更合适
3. 询问（必需格式）： 直接向用户提问，采用以下结构；除非用户明确调用了某个工作流／技能，且本地协议将明确调用视为确认：
   • 问题："你想启用哪个工作流？"
   • 选项 1："启用 [最佳匹配工作流]（推荐）"
   • 选项 2："启用自定义工作流：[步骤 1 → 步骤 2 → ...]"（附上一句话说明理由）
4. 启用（确认后）： 标准工作流调用 $workflow-start <workflowId>；自定义步骤按顺序手动执行
5. 创建任务： 跟踪工作流的所有步骤
6. 执行： 按顺序遵循每个步骤 [CRITICAL-THINKING-MINDSET] 运用批判性思维和顺序思维。每项声明都必须有可追溯的证据；置信度超过 80% 才能采取行动。 反幻觉原则： 切勿将猜测当作事实；每项声明都要引用来源；坦率承认不确定性；自行检查输出是否有误；独立交叉核对；对自己的判断保持怀疑——没有证据的确信是所有幻觉的根源。 AI 注意力原则（首因－近因效应）： 对于较长的提示词／协议，将最关键的 3 条规则同时放在开头和结尾，以确保指令在较长上下文窗口中仍能得到遵循。 目标驱动执行： 先定义成功标准，循环执行直至验证通过，并且只有在可观察的检查均通过后才停止。 测试验证意图： 测试必须保护业务规则／不变量，并在受保护的意图被破坏时失败，而不能只照搬当前行为。

[LESSON-LEARNED-REMINDER] [BLOCKING] 任务规划与持续改进 — 强制执行。不得跳过。

开始前将工作拆分为小任务并进行跟踪。添加最终任务："分析 AI 错误与经验教训"。

提取经验教训——仅限根本原因，不处理表面症状：

1. 指明失败模式（推理／假设失误），而非症状——例如“未阅读源代码就假设 API 存在”，而不是“使用了错误的枚举值”。
2. 通用性测试：此失败模式是否适用于 ≥3 种情境／代码库？如果不适用，就再抽象一层。
3. 将其写成通用规则——去除项目特定的名称／路径／类。该规则应适用于任何代码库。
4. 合并：多个错误若有相同的失败模式 → 总结为一条经验教训。
5. 重复发生检查：“如果没有这条提醒，未来会话中还会发生这种情况吗？”——不会 → 跳过 $learn。
6. 自动修复检查：“$code-review／$code-simplifier／$security／$lint 能否发现此问题？”——能 → 改进相应的审查技能。
7. 两项检查均通过 → 请用户运行 $learn。 [TASK-PLANNING] [MANDATORY] 在执行任何工作流或技能步骤之前，先为所有计划步骤创建／更新任务跟踪；然后随着每个步骤开始／完成，持续同步任务状态。