soia-dev-agent-md-advisorlisted

# 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/` 配置的三种工作模式：诊断已有配置的设计质量、为新项目起草配置骨架、回答最佳实践问题。本技能不调