SKILL.md
soia-dev-agent-md-advisor
AGENTS.md / CLAUDE.md / GEMINI.md 以及 .claude/（skills / agents / commands / hooks / settings.json）的设计顾问——审查这些文件本身写得好不好、结构合不合理，不负责它们跟项目当前状态是否同步。三种模式：①审查现有配置（诊断）②为新项目起草配置骨架（起草）③最佳实践问答。
定位与边界
与 soia-dev-doc-sync 的分界
两个技能经常被同一句话触发，但关注对象完全不同，必须分清楚：
| 本技能（soia-dev-agent-md-advisor） | soia-dev-doc-sync | |
|---|---|---|
| 关注对象 | AGENTS.md / CLAUDE.md / GEMINI.md / .claude/ 配置文件本身 |
docs/、README*、CHANGELOG.md、proposal 主文档、board.md |
| 核心问题 | 这份配置文件写得好不好、该怎么设计、该不该拆分 | 这些文档跟真源（代码 / board / VERSION / proposal）是否一致 |
| 典型触发 | "这个 AGENTS.md 太长了" "怎么拆分 CLAUDE.md" "多入口怎么管" | "docs 和提案文档有没有漂移" "release 后要不要回填文档" |
| 输出 | 设计质量诊断 + 改写建议，或新骨架草稿 | 状态漂移清单 + 回填顺序 |
| 是否做跨文档状态对账 | 不做——"时效"维度只检查配置文件自身引用的路径/命令现在是否还存在，是一次性快照检查 | 专门做——按固定真源优先级跨文档核对状态、版本、命名是否一致 |
判断规则：用户在问"这份 AI 指令文件写得好不好 / 该怎么组织"，用本技能；用户在问"文档跟实际进度/版本是否对得上"，转 soia-dev-doc-sync。两者都命中时，先用本技能诊断配置文件设计问题，状态对齐问题转交 soia-dev-doc-sync，不要在本技能里代做。
三种模式总览
| 模式 | 触发场景 | 输入 | 输出 |
|---|---|---|---|
| ① 审查（诊断） | 用户已有 AGENTS.md/CLAUDE.md/GEMINI.md/.claude 配置，要评估质量 |
目标文件路径或全文 | 问题清单（文件:行/维度/症状/建议改法）+ 改写建议 + 结论等级；默认只诊断，不动手改 |
| ② 起草 | 新项目还没有配置，或想推翻重来 | 项目类型/目录结构/协作 AI 数量 | 骨架文件草稿（根文件精简 + 子目录就近），标注待确认占位项 |
| ③ 问答 | 用户问格式、结构、放什么/不放什么等最佳实践，不涉及具体文件 | 一句问题 | 结论 + 推荐结构 + 注意事项 |
模式判定由 Agent 根据输入自动进行；拿不准时先问用户"你是想审查已有的、从零起草、还是单纯问个最佳实践问题"。
客户可读说明
这个技能可以做什么
覆盖 AGENTS.md/CLAUDE.md/GEMINI.md 与 .claude/ 配置的三种工作模式：诊断已有配置的设计质量、为新项目起草配置骨架、回答最佳实践问题。本技能不调用外部 API、不读取账号或凭据、审查模式默认不写文件——纯文本诊断与产出。
| 客户想要 | 技能会做 | 客户能看到 |
|---|---|---|
| 审查现有配置（模式①） | 按六维度逐项诊断，定位到具体文件:行，只诊断不动手改 | 问题清单（文件:行/维度/症状/建议改法/优先级）+ 改写建议 + 结论等级 |
| 为新项目起草配置（模式②） | 先问项目类型/目录结构/协作 AI 数量，按"根文件精简+子目录就近"原则出骨架 | 一版可直接使用的骨架文件草稿（占位项显式标注）+ 每个字段为什么这样设计的说明 |
| 最佳实践问答（模式③） | 直接给结论、推荐结构、注意事项 | 简洁的问答式回复 |
| 输入信息不足 | 不猜、不硬编，先问最小必要问题 | 一份具体的澄清问题清单 |
| 要求"帮我改/优化/执行"（仅模式①） | 诊断完成、客户明确确认后，只改被诊断出问题的部分 | 改动前后对比 + 逐条改动说明 |
客户如何使用
- 说明诉求，并提供必要输入：审查模式给目标文件路径或全文；起草模式给项目类型、目录结构、协作 AI 数量；问答模式直接提问。
- Agent 判定命中哪种模式；判定不了先问，不硬猜。
- 审查模式默认只诊断，不动手改文件——这是诊断请求还是改动请求必须分清楚，客户没有明确说"帮我改/优化/执行"之前，只交付诊断报告。
- 起草模式在项目类型/目录结构/协作 AI 数量任一项不明确时，先给一次问全的澄清清单，不脑补产出。
- 最终回复必须包含：模式判定、诊断或产出全文、逐条说明；模式①还需给出结论等级，以及"是否已落地修改"的明确状态。
依赖与安装
安装（推荐：装整个领域插件，一次装好本仓全部技能）：
claude plugin marketplace add soia-team/soia-open-skillsclaude plugin install soia-dev@soia只要这一个技能时，可用 npx 路线。注意技能会落进共享真源 ~/.agents/skills；若同时装了插件，同一技能会出现两份索引且各自漂移，建议二选一：
npx skills add soia-team/soia-open-dev-skills -g -a '*' -s soia-dev-agent-md-advisor -y配置约定：
~/.config/soia-skills/soia-dev-agent-md-advisor/config.yml
SOIA_DEV_AGENT_MD_ADVISOR_CONFIG_FILE=<custom-config-path>- 本技能当前版本不需要创建
config.yml：三种模式的诊断维度、流程和模板都直接写在本SKILL.md内，没有需要外部化的私有状态。上述路径预留给未来"客户自定义诊断维度权重 / 长度预算阈值"这类可选增强，非必需项。 - 本技能不需要、也不应该读取任何 API key、cookie、session、账号凭据——诊断和产出只处理客户提供的文本文件和项目里可公开读取的配置文件。
soia-dev-doc-sync是分工邻居，不是依赖：本技能不调用它，也不做它负责的跨文档状态对账；边界见上方"与 soia-dev-doc-sync 的分界"。
WorkBuddy 的装载单位是角色化专家而不是插件，npx skills add -a '*' 覆盖不到它，需要单独安装，见 docs/install/workbuddy.md。
私密信息与中间数据
- 输入可能包含客户尚未公开的 AI 指令和项目结构；只读取本次范围内的文件，不扫描账号、vault 或无关目录，也不把原文复制进公共示例。
- 本技能不创建持久 state、cache 或独立日志。诊断草稿只留在当前 Agent 会话；宿主自身的会话留存由宿主配置管理。
- 默认只在回复中交付诊断或骨架。客户明确授权写文件时，只写目标项目中的指定文件；覆盖既有文件前必须先展示差异并确认。
- 普通
config.yml只允许未来保存非秘密偏好；本技能不需要凭据，也不得保存 prompt、完整客户文件或响应正文。 - 回执只摘录证明 finding 所需的最小片段，并对账号、路径或其他敏感字段做脱敏。
日志与完成回执
每次执行都要让客户看见判定、诊断/产出和验证过程。最低回执格式：
完成：<一句话说明本次模式（①审查/②起草/③问答）与结果>。
日志摘要：
- 模式判定：<①/②/③，以及判定依据>
- 澄清记录：<本次问了哪些澄清问题及客户答复摘要；输入已足够时写"未追问，输入已足够">
- 诊断/产出：<模式①写六维度诊断结论与结论等级；模式②写骨架产出摘要；模式③写"不适用（问答）">
文件变化：
- <绝对路径或"未改动文件（本次仅输出诊断/建议/骨架草稿）">
问题与下一步：
- <需要客户确认的事实、占位项，或"是否要现在落地修改"；没有则写"无，可直接使用产出">诊断维度（核心资产）
六个维度覆盖配置文件设计质量的全部检查面，逐项过，不是逐字挑刺：
| # | 维度 | 检查问题 | 常见症状 | 建议改法 |
|---|---|---|---|---|
| 1 | 长度预算 | 每一行都会进入上下文；这一条如果删掉，AI 的行为会不会变？ | 大段背景故事、重复叮嘱同一件事、可有可无的礼貌用语、文件持续膨胀到几百行 | 逐行做"删掉会不会变"检验：不变的直接删；长流程移到 skill/子目录文件，根文件只留路由 |
| 2 | 规则可执行性 | 这条规则 AI 能自查、能验证，还是只是一句空话？ | "写高质量代码""保持专业""注意规范"这类无法验证的形容词；linter/formatter 能确定性执行的规则被写成大段自然语言 | 换成可验证的具体命令/路径/阈值；能交给工具判断的交给工具，不写进配置文件里空喊口号 |
| 3 | 分区路由 | 根文件和子目录 AGENTS.md/CLAUDE.md 的职责有没有切清楚？最贴近代码的规则是不是就近放在子目录？ | 根文件塞满只有某个子模块才用得到的细节；monorepo 只有一个巨型根文件，或反过来子目录规则和根文件大量重复 | 根文件只放全局路由 + 关键约束；模块特有规则下沉到该目录自己的 AGENTS.md/CLAUDE.md，根文件用一行指向它 |
| 4 | 重复与矛盾 | 同一条规则是不是在多处重复？有没有两条指令互相打架？ | 同一约束在根文件和子目录各写一遍；"尽量详细"与"控制在 X 行内"同时出现；新旧规则并存但没删旧的 | 去重，只在职责最合适的一处保留；矛盾指令必须二选一或显式定优先级，不能让 AI 自己猜听谁的 |
| 5 | 入口一致性 | CLAUDE.md、AGENTS.md、GEMINI.md 等多入口内容是否一致？有没有随时间各自漂移？ |
同一条项目规则在不同入口文件里表述不同甚至互相矛盾；只更新了一个入口，其他入口还是旧版本 | 选定一个入口为真源（通常 AGENTS.md），其余入口改为精简指针或引用，不维护多份正文 |
| 6 | 时效 | 文件里引用的路径、命令、工具现在还存在吗？ | 指向已删除/改名的目录；引用已下线的命令行工具或废弃脚本；版本号、依赖名早就更新了但文件没跟上 | 逐条核对：能用 ls/grep 验证的必须验证，验证不了的路径标注"未核实，需客户确认"，不要凭记忆断言存在 |
诊断只报有问题的维度，通过的维度一句话带过；六项全过就如实告知"设计质量良好，暂不需要改"，不制造工作量。
模式① 审查（诊断）流程
- 识别范围：读哪些文件——
AGENTS.md、CLAUDE.md、CLAUDE.local.md、GEMINI.md、.claude/settings.json、.claude/skills//SKILL.md、.claude/agents/.md、.claude/commands/*.md、.claude/hooks/。只读与本次判断相关的文件，不为诊断而扫描整个仓库。 - 六维度逐项诊断：对照上表逐条检查，每个问题维度定位到具体文件和行号，引用原文。
- 判定结论等级：
- 优秀——六维度均达标 - 基本可用——1-2 项有 P2 级问题（篇幅、风格类，不直接致错） - 需要精简——问题集中在长度预算/重复与矛盾 - 需要重构——3 项以上有 P1 级问题（会导致 agent 反复犯同类错误），或分区路由整体错位 - 风险较高——存在 P0 级问题（安全边界缺失、规则自相矛盾导致行为不可预测）
- 输出问题清单 + 改写建议，格式见下方模板。默认只诊断，不动手改文件——这是诊断请求，不是改动请求。
- 只有客户明确说"帮我改/优化/重写/执行"，才进入落地编辑；编辑时只改被诊断出问题的部分，保留没问题的内容，不做无关的风格化重写。
输出模板
# AGENTS.md / CLAUDE.md 设计诊断
结论：优秀 / 基本可用 / 需要精简 / 需要重构 / 风险较高
## 问题清单
| 文件:行 | 维度 | 症状 | 建议改法 | 优先级 |
|---|---|---|---|---|
| `<path>:<line>` | <六维度之一> | <具体症状，引用原文> | <改法> | P0/P1/P2 |
## 做得好的地方
- ...
## 改写建议（默认不落地，等待客户确认）
- 保留：...
- 删除：...
- 拆分到子目录：...
- 合并入口：...
## 是否落地修改
- 客户尚未确认，本次仅诊断 / 客户已确认，按以下顺序修改：...模式② 起草流程
- 先问三件事，不确定就问，不脑补：
- 项目类型：是什么项目、技术栈、单仓还是 monorepo - 目录结构：有没有多个独立子项目/子包，分别是什么 - 协作 AI 数量：只用 Claude Code，还是同时有 Codex/Gemini/Cursor 等多个 AI 协作
- 决定入口文件：
- 只用 Claude Code → CLAUDE.md 作为唯一入口 - 跨工具协作（Codex/Gemini/Cursor 等多个 AI）→ AGENTS.md 作为真源，CLAUDE.md/GEMINI.md 视工具支持情况做精简指针或软链接，不维护多份正文 - Monorepo/多子项目 → 根文件只放共享规则，每个子项目自己的目录下就近放一份 AGENTS.md/CLAUDE.md 承载专属规则
- 按"根文件精简 + 子目录就近"出骨架：
- 根文件只放：项目一句话定位/技术栈/常用命令/目录地图与"新代码放哪里"规则/关键 MUST-MUST NOT/测试与完成标准/安全边界 - 子目录文件只放该目录特有、根文件用不上的规则
- 输出骨架全文，标注哪些字段是占位、需要客户确认。不凭空发明命令——命令必须来自客户提供或项目里可验证的文件（
package.json/pyproject.toml/Makefile/CI workflow 等），验证不了就写<占位符，待确认>并说明。
骨架模板（单仓）
# AGENTS.md
## 项目
<一句话：这是什么项目，给谁用，主技术栈>
## 常用命令
- 安装：`<command>`
- 测试：`<command>`
- 构建：`<command>`
## 目录地图
- `<path>/` - <职责>
- 新增 <类型> 代码放在 `<path>/`
## 关键规则
- MUST <关键约束>
- MUST NOT <禁止动作>
## 测试与完成标准
- <完成的验证方式>
## 安全边界
- 涉及删除/覆盖/发送/发布前先确认Monorepo 模式
<repo>/
AGENTS.md # 共享规则与路由
<subproject-a>/AGENTS.md # 子项目专属规则
<subproject-b>/AGENTS.md # 子项目专属规则模式③ 问答流程
用简洁中文直接回答，不铺垫：
结论：...
推荐结构：
- ...
注意事项：
- ....claude/ 配置职责速查
判断该不该新增某个 .claude/ 子机制时用这张表，而不是默认全加：
| 机制 | 适用信号 | 过度设计信号（不建议加） |
|---|---|---|
CLAUDE.md/AGENTS.md |
任何项目都该有，承载全局规则和命令入口 | — |
.claude/commands/ |
同一段提示词反复手打，值得固化成模板 | 只用过一次的临时提示 |
.claude/skills/ |
某类任务有稳定、可复用的专项流程或领域知识 | 内容本质就是几句话，不值得单独封装成 skill |
.claude/agents/ |
需要独立上下文/独立工具权限的明确角色分工（reviewer/debugger 等） | 项目简单，一个主对话就能搞定 |
.claude/hooks/ |
动作是确定性的（格式化/校验/日志记录），不依赖主观判断 | 需要判断力的流程，应该交给 skill/agent 而不是 hook |
判断原则：目录多不代表成熟，可能只是过度设计；目录缺不是问题，只要当前真的用不上。
边界与限制
- 本技能不执行代码、不跑测试、不改业务逻辑；只处理 AI 指令配置文件本身的设计质量。
- 审查模式默认只读不改；只有客户明确说"优化/重写/执行/直接改"才落地编辑，且只改诊断出问题的部分。
- 不凭空发明命令或路径；命令必须来自项目可验证来源（
package.json/pyproject.toml/Makefile/CI 等）或客户提供，验证不了就标注"未核实，需客户确认"。 - 不默认建议上马复杂
.claude/agents+ hooks + skills 全家桶；先判断项目是否真的需要，参考上方速查表。 - 与
soia-dev-doc-sync不重叠：发现配置引用的路径/命令已经过时（时效维度）只是"这份文件本身该更新了"的一次性诊断，不做跨文档状态对账；真源冲突判断、release 回填、proposal 状态对齐这类工作转给soia-dev-doc-sync，本技能不代做。 - 本技能只处理客户提供的文件或项目里可公开读取的配置文件，不读取客户的账号、vault 或无关本机文件。
完成后回执
回执包含：
- 做了什么 — 一句话总结本次模式（①审查/②起草/③问答）、澄清情况和结果；模式①还要说明结论等级和是否已落地修改。
- 文件变更 — 模式①默认"未改动文件（本次仅输出诊断报告）"，除非客户已确认并要求落地；模式②固定"未改动文件（本次仅输出骨架草稿，供客户确认后自行创建）"；模式③固定"未改动文件（本技能仅输出问答文本）"。
- 下一步 — 模式①提醒客户"诊断已给出，是否需要现在落地修改"；模式②提醒客户核对骨架里的占位项和命令是否真实，确认后再落地成文件；模式③提醒客户如果想审查现有文件或起草新配置，可以切换到对应模式。