| 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』这一件事。 |
Component Skill Author
1. 定位
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 的原型即从它提炼。
2. 触发边界
2.1 适合
- 开发者指着一个现有模块/目录，说"把它做成 skill / 固化它的约定让 AI 遵守"。
- 组件有稳定的架构边界和约定，值得让 AI 每次复用。
2.2 不适合 / 转交
- 从零创建任意 skill、优化 description、跑 eval →
skill-creator（通用元能力）。
- 只想补一篇模块说明文档，不做 skill →
doc-maintenance-sync。
- 组件还在剧烈变动、边界没定型 → 先稳定代码再来抽象，否则 skill 一写就过期。
3. 产出物：组件 skill 五要素
每份组件 skill 必须覆盖这五块（顺序固定，缺一补一）：
| 要素 | 回答什么问题 | 来源 |
|---|
| ① 架构定位 | 这个组件在系统里是什么、统一入口在哪、AI 应优先调谁而不是绕过去 | 读入口文件 / 工厂 / service 层 |
| ② 职责边界 | 每个文件/子目录负责什么（贴真实路径） | 遍历组件目录 |
| ③ 已落地清单 | 现有的消息/阶段/接口/适配器逐条列出（AI 据此知道"已经有啥"） | 扫描具体实现文件 |
| ④ 扩展点 | 要新增一个同类东西，按什么步骤、放哪、改哪 | 读现有同类实现的模式 |
| ⑤ 红线 | 哪些写法是反模式、明确不要做 | 读注释/约定，或与开发者确认 |
frontmatter 额外带一个 tracks: 字段，声明本 skill 描述的组件对应哪些代码路径——用于将来代码改动时提醒"组件变了，回来更新这份 skill"（呼应 §6 的防过期）。
4. 工作步骤
步骤 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。
- 在 .ai/skills/README.md 注册表对应类别加一行（职责 + 边界/转交）。
- 跑
python scripts/quality/check_skills.py，确保 0 error（会校验 frontmatter、死路径引用、技术栈一致性）。
- 若项目结构树需同步，转
agents-tree-sync。
5. 组件 skill 原型模板
照填即可（<...> 替换成真实内容）：
---
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>
6. 质量门禁（不满足就重做）
- 路径真实：职责边界/清单里的
src/ scripts/ migrations/ 路径必须存在（check_skills.py 会扫死链报错）。
- 清单可核对：每条已落地项对应一个真实文件/符号，不列已删除或想象的东西（避免重蹈"引用已删文件"的坑）。
- 红线明确：至少给出该组件的关键反模式，否则 AI 仍会自由发挥。
- tracks 准确：声明的代码路径就是该组件的真实目录，将来才能据此提醒同步。
- 只写组件专属：通用方法论不要塞进来（那是套件托管 skill 的事）；本 skill 只装"这个组件特有的边界和约定"。
7. 与其他 skill 衔接
- 通用创建 / description 优化 / eval →
skill-creator
- 抽象完组件后要补模块说明文档 →
doc-maintenance-sync
- 新增 skill 后同步项目结构树 →
agents-tree-sync
