PROJECT KNOWLEDGE BASE

AI 铁律

1. 人与 AI 要实事求是、相互信任、精诚合作 — 人如实描述问题与约束，AI 如实报告发现与局限；双方基于事实共同决策，不猜测、不迎合、不隐瞒。
2. 数据脱敏 — Skill 中不得包含任何内部平台名称、内部域名、内部项目标识等非公开信息。示例和模板必须使用通用占位（如 example.com、my-project），不使用真实内部信息。提交前自查：URL、平台名、项目名、路径段、Jira ID、commit SHA 是否暴露内部信息。本铁律已机器化:npm run lint:deid 全量扫描 / pre-commit --staged / CI --base 拦截"新增"内部标识符(denylist 含 netease/ynote/YNOTR 等,见 scripts/lint-skill-deidentification.mjs);存量清理见 issue #267。
3. Skill 正文用英文书写，触发词必须包含中文 — Skill body（正文、reference.md、description 中的说明文字）是给 LLM 读的指令，英文书写可获得更高的理解精度与执行准确度（主流 LLM 的训练语料以英文为主）；同时英文 skill 面向全球用户，传播面更广。触发词必须包含中文——用户以自然语言唤起 skill，中文用户说中文（如「提交代码」「分析问题」），因此即使 skill 正文全英文，description 和 Triggers 区段也必须列出中文触发词，可同时附带英文等价词（如 「提交代码」 / "commit code"）。中文专属 skill（如 article-writer）为整体例外，正文也用中文。新增 skill 适用此规则；存量中文 skill 在重构时逐步迁移，不做一次性批量翻译。
4. 创建 Skill 必须走 /skill-creator 工作流 — 新建 skill 或大幅重写已有 skill 时，先 /skill-creator 唤起 skill-creator（捕获意图 → 写草稿 → 测试用例 → 评估迭代 → 描述优化），而非凭经验直接手写 SKILL.md。skill-creator 提供渐进式披露（SKILL.md <500 行 + reference 详表）、frontmatter 规范、触发词 eval 优化等工程化约束，能显著提升触发准确率与执行质量。仅在以下情况可跳过完整流程直接编辑：① skill 内容极简（纯指令、无测试需求）；② 维护已有 skill 的小修小补（改触发词、修正文）。
5. Skill 变更走 /opsx-solve-workflow 沉淀 — 新增、改进或修复 skill 时，用 /opsx-solve-workflow 将需求、根因、行为变化、方案、计划、验证与归档沉淀到 openspec/ artifacts（proposal/specs/design/tasks，归档后并入主 specs/），形成可追溯的行为契约。临时小修（改触发词、修正文）可直接编辑；涉及行为契约、多人评审或需长期追溯的变更走 opsx 规范化沉淀。skill 的写作质量仍遵循铁律 4（skill-creator）；opsx 管「做什么、为什么、归档」，skill-creator 管「怎么写得准」，两者互补。
6. Skill 正文描述意图，让 Agent 自选工具（平台无关） — Skill 跨平台运行（Claude Code / Cursor / OpenCode 等），正文不得把某平台专属工具（如 Claude Code 的 AskUserQuestion、某平台专属 MCP/CLI）作为必需或首选，也不得枚举「X 平台用 A 工具，Y 平台用 B」——枚举仍是硬编码，且武断假设其他平台只有兜底能力。正确做法：描述「要达成什么」（意图，如「结构化单选提问」），由运行该 skill 的 Agent 用其原生能力实现；无对应能力时退回通用格式（如 prose）。提交前自查：正文是否硬编码了平台/工具枚举。
7. Skill description ≤1024 字符，只写触发路由四要素 — frontmatter description 的职责是让 Agent 路由触发，不是文档：只写「做什么 / 何时用 / 触发词（含中文，见铁律 3）/ Do NOT use 反向边界」，方法论细节、环节枚举、格式清单一律归入 SKILL.md 正文或 reference.md。硬上限 1024 字符（Agent Skills 规范，超限平台加载器会报警），软目标 ≤950（留统计口径余量）。修改 description 后运行 npm run lint:skill-description 校验；pre-commit 已内置该校验，超限将阻断提交。
8. 能力断言必须实证 — 凡涉及「某工具/Skill 能做什么、不能做什么」「某能力市场上无竞品」等能力断言，写入文档或 Skill 前必须经一手实证：本地源码实证（目标 skill 的 SKILL.md / API 文档）+ 外部官方数据（GitHub、官方文档），不接受二手转述或「看起来合理」的推断。能力对比类文档需在文首标注核验日期与来源，便于后续刷新。
9. 改契约必须反查「提及它的需求」 — 修改一条 OpenSpec 需求（MODIFIED / RENAMED）时，清单不能只列「行为需要变的需求」，必须加上所有提及被改项的其他需求并一并同步。描述性引用——如清单式枚举、branch isolation 这类措辞、consumption order 这类术语、场景里的逐项列举——不会被编号 grep 捕获，只能人工遍历。自查：grep 被改项的关键措辞与旧需求名，命中处逐一判定是否需同步；openspec validate 通过不代表一致（它只查格式，不查语义引用）。判定口径：需求名、术语、枚举三项与人改项相关的，视同需同步。
10. 门禁与默认解锁的输入必须可核验 — 设计任何门禁、放行条件，或「满足即自动放行」的默认值时，其判定输入必须是可独立核验的事实（文件/符号存在性、分支拓扑、路径集、字段值），不得是 AI 的自由判断（preference）。若门禁吃的是判断，则门禁本身不被任何下游实证覆盖——这是最隐蔽的护栏泄漏：看起来有门，实则无门。自查：写下门禁条件后逐条问「这个输入能否被一条命令或一次 grep 证实？」任一为否，即须把该判断拆成可核验信号（如把「难度档」拆成可逆性/既有证据/影响半径/依赖形态四项），或把门禁降级为「须人确认」。
11. 任何开发推进都在 Git worktree 中进行 — 本仓库会有多个 AI 进程同时推进开发。凡会写入仓库的推进（文档或代码），先开独立 Git worktree，在其中创建 feature 分支再写；主检出只做只读查阅，避免并行进程改同一工作区、互相覆盖或产生冲突。创建 worktree 失败时停下来报告原因，不退回主检出继续写。本仓声明 worktree-gate: always，由 git-worktree-discipline 在首个非平凡持久化写入之前创建或复用隔离工作区。

合并偏好（merge-discipline Part C / Part R）

coverage-gate: never

pr-review-gate: non-code-light

worktree-gate: always

本仓库为 Markdown skills 库，合并前不默认跑 test-coverage-analyzer。其他工程可在 AGENTS.md / CLAUDE.md 声明 coverage-gate: always | never | ask（未声明 ≡ 每次合并询问）。

pr-review-gate：always（全量 pr-code-review）| never（跳过 Part R，须留痕）| ask（每次询问 full/light/skip）| non-code-light（非应用代码表面用 light 深度，否则 full）| auto（内容匹配深度：surface 分类 + 大 diff/破坏性信号/fail 重提升级）。未声明 ≡ auto（merge-discipline v1.7.0 起；升级信号任一命中仍 full，仅「非应用代码且无升级信号」走 light —— 非未分类一刀切）。本仓默认 non-code-light：docs/skills/openspec 等表面走轻量双轴审查；含 workflows / scripts/ / 运行时源码扩展则仍 full。

本仓库 worktree-gate: always（铁律 11）：多个 AI 进程会同时推进开发，首个非平凡持久化写入（文档或代码）之前由 git-worktree-discipline 创建或复用 Git worktree，不再询问。取值仍是 always | never | ask；其他工程未声明时 ≡ ask，ask 下先按仓库状态给出适合度推荐再询问是否创建隔离工作区。

Skill 调用分层（User- vs Model-invoked）

新增 skill 时按上表选型；user-invocable: false 的 skill 必须被其他 skill 引用，否则视为死 skill。本仓库不分发斜杠命令文件；用户靠 skill 名与触发词唤起。贡献者本仓 OpenSpec 入口在 .claude/commands/opsx/。

本文件为 Claude Code 等 AI 在本仓库工作时的项目知识库。文首若出现历史生成日期或分支名，仅作存档；以当前仓库 main 与目录结构为准。

概述

AI 编码助手的开放 Skills 库。对外只分发 SKILL.md（npx skills / scripts/install-skills.mjs），适用于 Claude Code、Cursor、OpenCode 及其他支持 skills CLI 的助手。见根目录 README.md § 安装。

结构

open-skills/
├── skills/                 # 核心：Skill 定义（每个子目录 = 一个 skill）
│   └── <name>/SKILL.md     # 必需文件，含 frontmatter 元数据
├── docs/                   # 安装指南、实现文档（含 generated/ 自动生成索引）
├── scripts/                # gen-skill-docs.mjs：由 skills 生成 docs/generated/skills-index.md；lint-skill-description.mjs：description ≤1024 校验（见铁律 7）；lint-skill-deidentification.mjs：内部标识符脱敏门禁（见铁律 2）
├── openspec/               # OpenSpec 规范治理（changes/ 变更提案、specs/ 主行为契约；opsx 沉淀落点，见铁律 5）
├── .claude/                # 本仓工程级配置（不分发）：OpenSpec OPSX skills（openspec-*）、opsx/* 快捷命令、agents/（角色定义与契约）
└── .github/workflows/      # CI：版本递增（release.yml）、skills 索引校验（docs-skills-verify.yml）

在哪找什么

Skill 清单

名称、版本、user-invocable、描述（触发条件） 以自动生成的 docs/generated/skills-index.md 为准（node scripts/gen-skill-docs.mjs）。下表仅保留 类别与依赖，供快速扫一眼关系。

💕 AI 编码陪伴（coding-fangirl）已迁移至独立工程 oh-my-fangirl。

钩子机制

Hooks 已随 coding-fangirl 迁移至 oh-my-fangirl，本仓库不再包含 hooks，也不再提供 OpenCode 插件作为安装面。

代码规范

SKILL.md 格式（必须遵循）

---
name: skill-name
version: "1.0.0"
user-invocable: true
description: 触发条件和用途说明（必须包含触发词）
dependencies:  # 可选，数组形式，声明强依赖的其他 skill
  - other-skill
---

# Skill 标题

Skill 内容...

dependencies 字段（可选）：数组形式，声明本 skill 强依赖的其他 skill。声明后，skill 必须在启动时做前置检查（扫描可用 skill 列表），缺失任一依赖立即中止流程并提示安装命令，不得静默降级。被依赖的 skill 不需要反向声明——不得把「Integrated by / Strongly depended on by」主机名清单当作行为契约维护；至多用角色句（如「Referenced by PDCA hosts via frontmatter dependencies」）。强依赖权威来源是引用方 frontmatter 与本文「Skill 清单」依赖列。

触发词设计：支持两种形式——单独触发词（如「分析问题」）或带冒号形式（如「分析问题： xxx」）；冒号和空格不限制中英文。在 description 中列出所有触发词，必须包含中文触发词，可同时列英文等价词（如 「提交代码」 / "commit code"）；工作流 skill 的阶段名即为触发词（如「分析问题」触发 solve-workflow 的阶段 1）。

frontmatter YAML 陷阱

description 裸值含英文 : （冒号+空格，如 Triggers: 发版）会触发 YAML Nested mappings are not allowed 错误，导致 npx skills 安装/更新报 No valid skills found。值含 : 时必须加双引号或用 | 块标量。中文冒号「：」不受影响。

⚠️ 本仓库额外约束（与 gen-skill-docs.mjs 冲突）：| 块标量和多行 description 虽能通过 npx skills 的真 YAML 解析，但本仓库 scripts/gen-skill-docs.mjs 用简易行解析器（按行首个 : 切分、不识别缩进块），会把 | 当成 description 的字面值（解析为 "|"），导致 docs/generated/skills-index.md 中该 skill 的描述列变成 |。因此本仓库的 description 一律用单行双引号字符串，禁用 | 块标量和多行 description。

新增 Skill 检查清单

1. 目录名 kebab-case
2. SKILL.md frontmatter 完整（name、version、description 含触发词；如声明了 dependencies，需实现前置检查）
3. 确认 docs/generated/skills-index.md 已更新并纳入提交（commit 时 pre-commit hook 自动处理；未安装 hook 则手动运行 node scripts/gen-skill-docs.mjs 后再提交）
4. 确认正文正向描述流程（检查是否有「不得 XXX」/「❌ 反例」堆砌——正向流程讲清楚后反例即冗余）
5. 确认正文无版本标记等历史包袱（无「v1→v2」「（v2 新增）」等变更日志——变更历史由 git/archive 承载）
6. 确认 SKILL.md 摘要不重复 reference.md 完整规范（SKILL.md 是摘要 + 指向 reference.md，不是复制）

Skill 精简原则

• 规则只写一次：参考表/速览表不应重复阶段详情中已有的规则
• Pitfall 只记非直觉陷阱：不看规则就容易犯的错误才值得记，规则本身的重复罗列是 token 浪费
• 输出模板超过 5 行抽 reference.md：SKILL.md 用 输出格式见 reference.md 一句引用
• 共享 skill 的契约标识两侧一致：共享 skill 的参数化占位符（如 {root-cause step}）是共享方与引用方之间的契约标识，必须两侧逐字一致；提交前 grep 两侧核对（含中英文差异）
• 共享抽取后须薄引用验收：从多工作流抽取共享 skill 后，引用方 SKILL.md 只保留「加载 + 占位符映射（号+名）+ 工作流特有编排/有意分歧」；不得复述共享正文的方法论段落。同步检查各工作流 reference.md：补依赖说明与指向，不把方法论再抄进 reference。验收可用残留 grep（旧标题/「严格只读」等与共享门控矛盾的表述须为零）
• 跨 skill 引用用名称、不用对方编号：引用其他 skill 的阶段/步骤时写名称（如「分析阶段」、runtime-evidence-debug 的逃生出口），不写对方编号（stage 1.2、步骤 3.6 等）——对方重编号时数字引用会 silently 悬空且难察觉（曾有「逃生出口 5.5」指向不存在步骤的实例）；编号仅允许出现在引用方自己声明的契约映射行，且须「号+名」
• 正文正向描述流程，不堆砌反例：Skill 正文（SKILL.md + reference.md）正向描述「什么时候做什么、怎么做」；AI 理解正向流程后自然不会犯错，反例堆砌（「不得 XXX」/「❌ 反例」）降低信噪比且暗示 AI 不够聪明。反模式只需在事件复盘文档和 git history 留存，不侵入 Skill 正文
• 正文不携带历史包袱：Skill 正文只描述「当前怎么做」，不写「v1→v2 变更」「（v2 新增）」等版本标记或变更日志。变更历史由 git commit history 和 OpenSpec archive 承载；Skill 运行时应轻盈、活在当下
• 薄引用不夹带 changelog / 相对旧版旁白：宿主工作流同步下游 skill 行为变更时，只保留层名枚举 +「加载并按其标准」；不得复述下游的新权重、新默认深度，或写「相对旧版变严了」「非平凡默认充分」等演进叙事。现行规则只写在权威 skill；宿主 skill 不需要知道历史上该 skill 是什么样的。自查：这句是现行契约，还是相对旧基线的变更说明？
• 同一规则用不同措辞重复表述是冗余，不是加强：若「触发时机」已说清「即将执行 X 时启动」，再独立写一段「X 前置检查（强制）：调用 X 前自问是否已做 Y」就是同一件事的重复——换个说法再强调一遍不增加信息量，只降低信噪比
• 有序列表的书写顺序与执行/产生顺序一致：输出项、步骤、检查项等有序列表，其书写顺序应与实际执行或产生的先后顺序一致——AI 读列表时按列表顺序理解执行顺序，顺序不一致会产生认知映射开销且容易出错

JSON

• 2 空格缩进，camelCase 属性名，无尾空行

命名约定

Skill 角色命名（语义）

完整契约见 openspec/specs/skill-naming/spec.md。摘要：

• 原生 OpenSpec CLI skill（.claude/skills/openspec-new-change 等）保持 openspec-*，由 opsx-workspace-gate 校验精确名。
• 禁止新建 pdca-* 项目 skill id；改名一律硬切（无兼容别名目录）。

Git 工作流

• 执行计划前先开 Git worktree：开始修改文档或代码前，按铁律 11 创建隔离 worktree，并在其中创建 feature 分支
• 禁止直接推送 main：必须先创建 feature 分支
• 合并 PR 时：默认使用「Create a merge commit」。是否 Squash 由 merge-discipline Part D 合并前 squash 决策按 MR commit 质量给推荐并经用户确认（决策空间收敛时不发问：恰好一个 commit 或平台仅允许一种合并方式时，直接给出结论与理由执行）：琐碎堆积（fixup/typo/wip/CI 重试）的 MR 可 Squash；将续开发的分支避免 Squash——Squash 会切断 main 与 feature 分支的提交图，后续在同一分支继续开发再合并 main 时易产生冲突。
• PR 合并后同步主分支：合并 PR 后，本地工作区按 merge-discipline Part D 的 post-merge workspace sync 行为契约切回目标分支并快进（目标分支以 MR base 为准，不必然是 main/master；即「Merge PR 与发布流程」第 4 步的机器可执行版）。
• PR 合并后继续开发：若上游已用 Squash 合并过，在本地继续提交前必须先 git merge origin/main 或 git pull origin main，再开发。
• 长周期变更双点同步检查：跨天/跨阶段的变更，在动手前（制定计划时）和执行中期（如 opsx 阶段 5 执行前）各做一次 git fetch origin main 并查看 git log HEAD..origin/main --oneline，尽早感知并行合并的 PR；发现 main 已动到自己在改的区域时，提前小步同步（rebase/merge），把冲突消解在早期而非攒到最后一次 rebase 爆发
• PR 前：git fetch origin main && git rebase origin/main
• PR 仅含本次变更 commits
• Commit 前缀：feat: 新功能、fix: 修复、docs: 文档、chore: 杂项

Merge PR 与发布流程

1. 合并 PR：gh pr merge <编号> --merge
2. 检查版本发布：等待 CI 完成（约 15–20 秒），gh release list -L 3 确认新版本
3. 更新本地安装：在仓库根执行 node scripts/install-skills.mjs（内部为 npx skills add … -g -y --skill '*' --agent claude-code cursor opencode，排除无全局目录的 PromptScript/Eve，避免 ✗ 噪音）。需要更多 agent 时设 OPEN_SKILLS_AGENTS。全量安装后自动 prune 陈旧副本：skills add 只增不删，本脚本按 .open-skills-manifest.json 归因，仅删除本仓库曾安装且已从仓库移除的 skill 目录（外来 skill 不受影响；部分安装 --skill <name> 与 --no-prune 均跳过）。根因是上游 CLI 无 sync 删除语义（见 vercel-labs/skills#1352 同仓相关），不是本仓库某些 skill「不支持全局安装」。裸命令 npx skills add FuDesign2008/open-skills -g 会进入交互式多选（AI/CI 无法应答），不要用于自动化。
4. 工作区同步：git checkout main && git pull origin main

版本管理

• 版本号在根目录 package.json 的 version 字段
• 禁止手动修改：CI（.github/workflows/release.yml）自动递增
• 规则：feat: → MINOR、fix: → PATCH、BREAKING CHANGE → MAJOR
• 触发条件：skills/ 有变更时（或手动 workflow_dispatch）
• 受保护 main：release workflow 在 main 上直接提交版本号变更（git push origin HEAD:main，提交标题带 [skip ci] 避免再次触发）、打 tag、发 Release。不再走 version-bump PR——bot 用 GITHUB_TOKEN 开的 PR 触发的 verify workflow 会被 GitHub 标记为 action_required（防 workflow 自注入），导致 branch policy 永远拒绝 gh pr merge。

安装面

对外只提供 通用安装（SKILL.md，npx skills / scripts/install-skills.mjs）。Claude Code、Cursor、OpenCode 均走同一条 skill 分发；不提供 Marketplace 插件、斜杠命令或 OpenCode 仓库 clone 安装。详见根目录 README.md § 安装与 docs/INSTALL.md。

反模式（禁止）

• ❌ 手动修改版本号
• ❌ 直接推送 main 分支
• ❌ 在主检出直接改文档或代码推进开发（见 AI 铁律 11，须先开 Git worktree）
• ❌ SKILL.md 缺少 frontmatter 或遗漏触发词
• ❌ Skill 正文把某一 Agent 专属工具作为必需/首选，或枚举「X 平台用 A、Y 平台用 B」（仍硬编码 + 武断假设其他平台能力）。应描述意图（要达成什么），让各 Agent 用原生能力实现，无对应能力时退回通用格式（如 prose）
• ❌ 英文 skill 的触发词只有英文，缺失中文触发词（中文用户无法自然唤起）
• ❌ 目录名与 frontmatter name 不一致
• ❌ user-invocable: false 但无其他 skill 引用它
• ❌ 工作流 skill 跳过阶段（分析阶段禁止 Edit/Write）
• ❌ 支持文件（如 reference.md）未在 SKILL.md 中引用
• ❌ 参考表/速览表重复已有阶段详情（token 膨胀）
• ❌ Red Flags/Pitfall 重复上方已写明的规则（Pitfall 只记非直觉陷阱）
• ❌ PDCA 对应表等元认知框架（对 AI 无执行指导价值；人类可读内容放 reference.md）
• ❌ description 裸值含英文 : 未加引号，破坏 YAML 解析导致 npx skills 安装失败（见 frontmatter YAML 陷阱）
• ❌ description 用 | 块标量或多行字符串，被 gen-skill-docs.mjs 简易解析器解析成 "|"，导致 skills-index 描述列变 |（见 frontmatter YAML 陷阱）
• ❌ 新建 skill 不走 /skill-creator 直接手写（见 AI 铁律 4）
• ❌ 声明了 frontmatter dependencies 却不做前置检查，或缺失依赖时静默降级而不提示安装（强依赖必须中止流程并给出安装命令）
• ❌ 中文内容混用英文标点
• ❌ Skill 正文堆砌「不得 XXX」/「❌ 反例」等否定式（应正向描述流程——AI 理解正向流程后自然不会犯错，反例堆砌降低信噪比）
• ❌ Skill 正文写「v1→v2」「（v2 新增）」等版本标记或变更日志（变更历史由 git/archive 承载，Skill 正文活在当下）

验证命令

# package.json
node -e "JSON.parse(require('fs').readFileSync('package.json'))"

# OpenSpec 规范校验（等同 openspec-verify workflow；strict 把 Purpose 过短等警告也视为失败）
openspec validate --strict --all

# SKILL.md frontmatter
grep -r "^---$" skills/*/SKILL.md

# Skills 索引生成脚本语法
node --check scripts/gen-skill-docs.mjs

# Skills 索引与 CI 一致（等同 docs-skills-verify workflow）
node scripts/gen-skill-docs.mjs
git diff --exit-code docs/generated/skills-index.md

# 脱敏门禁（铁律 2）：全量扫描存量 / --staged 拦暂存新增 / CI 用 --base origin/main 拦 PR 新增
node scripts/lint-skill-deidentification.mjs            # 全量（清理存量；当前因 issue #267 存量会 exit 1）
node scripts/lint-skill-deidentification.mjs --staged   # pre-commit

# 重命名/重编号类变更收尾：全库双语残留清扫（模式按本次旧标识调整，含中英文），须零命中
grep -rn -iE '阶段 ?1\.[12]|stage ?1\.[12]|0\.5|3\.6' skills/
# 阶段内容变更收尾：SKILL.md 中散布的表格（模式速查、快速参考、工具约束、能力映射等）在阶段内容变更后须逐表核对，不限于编号残留——描述性引用（如「Jira 状态回写」文本）不会被编号 grep 捕获，须人工遍历
# 契约变更收尾（铁律 9）：反查「提及被改项」的其他需求——grep 被改项的措辞、术语与旧需求名（含场景内的逐项枚举），命中处逐一判定是否需同步；openspec validate 只查格式、不查语义引用
grep -rn '<被改项关键措辞>\|<旧需求名>' openspec/specs/ skills/
# 整文件重写后：删除侧 diff 逐行核对，确认删除行全部对应预期改动、无意外内容丢失
git diff -U0 <改动文件> | grep '^-' | grep -v '^---'

首次 clone 后执行 npm install 以启用 Husky pre-commit（修改 skills/*/SKILL.md 时自动 regenerate 并 stage docs/generated/skills-index.md）。

子目录知识库

• docs/SKILL_DISTRIBUTION.md — 分发 skill vs 本仓 .claude/skills/openspec-* 工程级配置