메뉴
把项目里已有的内部组件（如 MQ 中台、解析 pipeline、缓存层、对象存储）抽象成一份「项目自有 skill」，让 AI 每次接入都自动复用该组件的架构边界与约定。读组件真实代码，提炼「架构定位 / 职责边界 / 已落地清单 / 扩展点 / 红线」五要素，按统一原型生成 SKILL.md，登记到 .ai/skills/README.md 注册表并跑校验。
Codex 또는 Claude로 설치 이 Prompt를 복사해 Codex, Claude 또는 다른 어시스턴트에 붙여 넣으면 Skill 페이지를 검토하고 설치를 진행할 수 있습니다.
SOC 직업 분류 기준
契约治理三件套的「值层」。核对同一个物理契约值（MQ topic/group、OSS bucket、消息字段名/别名、内部 HTTP 路径等）在 .env/.env.example/代码生效点/Java 对端多处是否逐字相等，找出配置漂移与死值，防止消息收不到/文件取不到。本 skill 只比对「同一个值在多处是否一致」，不判断结构/语义是否破坏对端（那是结构层，转 contract-guard），也不改文档。
指导 LLM 如何使用 toLink-Rag 项目的 MQ 消息中台进行消息收发、定义新消息类型以及处理多厂商适配逻辑。
当用户认为当前模块代码实现完毕，且当前分支应为 dev，需要从 dev 基于当前修改创建规范分支、提交并发起合并到 dev 的 GitHub PR 时使用；也用于发布收口，即直接创建 dev -> master 的 release PR，不新建 release 分支。适用于“从 dev 新建分支”“把当前修改提 PR”“实现完成创建 feature/refactor 分支并 PR”“发布新版本”“dev 合并 master”等交付收口场景。本 skill 是交付链终点，并在建分支/提 PR 前执行收口门槛：测试未过、契约文档失同步、acceptance 未提升者拒绝收口。
当用户要求把需求、功能、技术方案、架构改造、故障复盘、项目治理实践或实现过程写成博客/技术文章时必须使用；尤其适用于“写一篇博客”“生成技术博客”“把这个需求写成文章”“根据这个功能写博客”“把项目实现讲清楚”等请求。使用时要基于用户给出的需求和 toLink-Rag 当前仓库的真实代码、文档、契约、配置与测试证据完成分析，默认输出 Markdown 到 `.specs/blog/《博客名称》.md`。文章须采用「少量
当用户要提 issue、登记 bug、记录新需求时使用；自动识别所属项目，生成结构化 issue 内容，先在 Linear 建主记录、再在 GitHub 建镜像，并双向回链。用户说"提个 issue""记一下这个 bug""把这个需求登记一下""同步到 Linear 和 GitHub""别再依赖 Linear 自动同步"时都应触发，即使没有明确说出"Linear"或"GitHub"。
当用户提出新需求、口头想法、初步框架，或要求"写个 brief / 需求理解 / 业务分析 / 先理清楚需求"时激活；输出面向开发者的 brief.md，覆盖需求摘要、业务流程、涉及模块与影响面（含概念数据模型，但不到物理 schema 与 how）、风险、待确认问题五章；支持开发者审阅后通过对话迭代修订，直到开发者确认冻结，作为后续 acceptance.feature 生成的输入。若用户已基于 brief.md 提出修改、补充、疑问、回答待确认项，继续用本 skill 做迭代收敛。
| name | component-skill-author |
| description | 把项目里已有的内部组件（如 MQ 中台、解析 pipeline、缓存层、对象存储）抽象成一份「项目自有 skill」，让 AI 每次接入都自动复用该组件的架构边界与约定。读组件真实代码，提炼「架构定位 / 职责边界 / 已落地清单 / 扩展点 / 红线」五要素，按统一原型生成 SKILL.md，登记到 .ai/skills/README.md 注册表并跑校验。 |
| when_to_use | 当开发者想把某个现有组件/模块固化成 AI 可复用的 skill 时使用。触发示例：'把 MQ 组件做成 skill'、'给 pipeline 写个 skill'、'把这个模块的约定固化下来让 AI 每次都遵守'、'抽象现有组件加入 skill 体系'。边界：从零创建任意 skill、优化 description、跑 eval → 转 skill-creator（通用元能力）；只补模块文档不做 skill → 转 doc-maintenance-sync。本 skill 只做『把已有代码组件 → 项目自有 skill』这一件事。 |
skill 分两类：套件托管（flow-router、brief-generator 这种谁的项目都能用的通用方法论）和项目自有（mq-middleware 这种只有本项目才有的组件知识）。本 skill 专门生产后者。
它解决一个具体问题：项目里有些组件（MQ 中台、解析 pipeline、缓存层…）有自己的架构和约定，希望 AI 每次接入都遵守、复用，而不是每次重新摸索或自由发挥。办法就是把这份组件知识固化成一份 skill 放进 .ai/skills/——AI 启动会自动扫描并按 description 触发。
本 skill 不产出业务代码、不改组件本身。它只读组件代码，把"这个组件是什么、边界在哪、有哪些约定、不能怎么做"提炼成一份给 AI 看的工作指令。
黄金参照：.ai/skills/mq-middleware/SKILL.md 就是一份成熟的项目自有组件 skill，本 skill 的原型即从它提炼。
skill-creator（通用元能力）。doc-maintenance-sync。每份组件 skill 必须覆盖这五块（顺序固定，缺一补一）：
| 要素 | 回答什么问题 | 来源 |
|---|---|---|
| ① 架构定位 | 这个组件在系统里是什么、统一入口在哪、AI 应优先调谁而不是绕过去 | 读入口文件 / 工厂 / service 层 |
| ② 职责边界 | 每个文件/子目录负责什么（贴真实路径） | 遍历组件目录 |
| ③ 已落地清单 | 现有的消息/阶段/接口/适配器逐条列出（AI 据此知道"已经有啥"） | 扫描具体实现文件 |
| ④ 扩展点 | 要新增一个同类东西，按什么步骤、放哪、改哪 | 读现有同类实现的模式 |
| ⑤ 红线 | 哪些写法是反模式、明确不要做 | 读注释/约定，或与开发者确认 |
frontmatter 额外带一个 tracks: 字段，声明本 skill 描述的组件对应哪些代码路径——用于将来代码改动时提醒"组件变了，回来更新这份 skill"（呼应 §6 的防过期）。
步骤 1 — 圈定组件范围。和开发者确认要抽象的组件目录/入口（如 src/core/mq/、src/core/pipeline/parse_task/）。范围要清晰：一个组件一份 skill，不要把两个无关组件塞进一份。
步骤 2 — 读代码、提炼五要素。遍历组件目录，按 §3 的五要素逐项填。要求：
步骤 3 — 生成 SKILL.md。用 §5 原型填好 frontmatter（name = 目录名、description、when_to_use、tracks）和五要素正文。
步骤 4 — 落盘 + 登记 + 校验：
.ai/skills/<component-name>/SKILL.md。python scripts/quality/check_skills.py，确保 0 error（会校验 frontmatter、死路径引用、技术栈一致性）。agents-tree-sync。照填即可（<...> 替换成真实内容）：
---
name: <component-name>
description: <这个组件是什么 + 本 skill 让 AI 在接入时复用它的哪些边界/约定>
when_to_use: "<触发示例：'接入<组件>'、'新增<组件里的东西>'、'改<组件>'>。边界：<什么情况转给谁>。"
tracks:
- src/your_component/** # 替换成组件真实目录
---
# <组件名> Skill
## 1. 架构定位
<组件在系统里的角色；统一入口（service/factory）；AI 应优先调谁，不要绕过去直接 new 底层>
## 2. 职责边界
- `<path/to/entry.py>`：<职责>
- `<path/to/sub/>`：<职责>
（逐个文件/子目录贴真实路径）
## 3. 当前已落地清单
- `<path/to/impl_a.py>`：<名称/标识，如 Topic、阶段名、接口路径>
- `<path/to/impl_b.py>`：<...>
（逐条列现有实现，AI 据此知道已经有啥）
## 4. 扩展点：要新增一个同类的怎么做
1. <在哪建文件>
2. <继承/实现什么、注册到哪>
3. <要同步改的清单（如 __init__ 导出、工厂注册、本 skill 的已落地清单）>
## 5. 红线（不要这样做）
- <反模式 1>
- <反模式 2>
src/ scripts/ migrations/ 路径必须存在（check_skills.py 会扫死链报错）。skill-creatordoc-maintenance-syncagents-tree-sync