AGENTS.md / CLAUDE.md / GEMINI.md as well as .claude/(skills / agents / commands / hooks / settings.json)design advisor—it reviews whether these files themselves are well written and whether their structure is reasonable; it is not responsible for whether they are in sync with the project's current state. Three modes: ① review existing configuration (diagnosis) ② draft a configuration skeleton for a new project (drafting) ③ best practice Q&A.
Positioning and boundaries
Boundary with soia-dev-doc-sync
The two skills are often triggered by the same sentence, but their focus is completely different and must be clearly distinguished:
| This skill (soia-dev-agent-md-advisor) | soia-dev-doc-sync | |
|---|---|---|
| Focus | AGENTS.md / CLAUDE.md / GEMINI.md / .claude/ configurationfiles themselves |
docs/、README*、CHANGELOG.md, proposal main document,board.md |
| Core question | Is this configuration filewell written, how should it be designed, should it be split | Are these documents consistent with thesource of truth(code / board / VERSION / proposal) |
| Typical triggers | "This AGENTS.md is too long" "How to split CLAUDE.md" "How to manage multiple entries" | "Has docs and proposal documents drifted" "Should docs be backfilled after release" |
| Output | Design quality diagnosis + rewrite suggestions, or a new skeleton draft | State drift list + backfill order |
| Whether to do cross-document state reconciliation | No—the "timeliness" dimension only checks whether the paths/commands referenced by the configuration fileitselfstill exist now; it is a one-time snapshot check | Yes, specifically—cross-check whether state, version, and naming are consistent across documents according to a fixed source-of-truth priority |
Decision rule: if the user is asking "is this AI instruction file well written / how should it be organized", use this skill; if the user is asking "do the documents match the actual progress/version", hand off to soia-dev-doc-sync. When both match, first use this skill to diagnose configuration file design issues, and hand off state alignment issues to soia-dev-doc-sync; do not do it on behalf of that skill within this skill.
Overview of the three modes
| Mode | Trigger scenario | Input | Output |
|---|---|---|---|
| ① Review (diagnosis) | The user already has AGENTS.md/CLAUDE.md/GEMINI.md/.claude configuration and wants to evaluate its quality |
Target file path or full text | Issue list (file:line/dimension/symptom/suggested fix) + rewrite suggestions + conclusion level;by default only diagnose, do not modify |
| ② Drafting | The new project does not yet have configuration, or wants to start over | Project type/directory structure/number of collaborating AIs | Skeleton file draft (streamlined root file + nearby subdirectories), marking placeholders to be confirmed |
| ③ Q&A | The user asks about best practices such as format, structure, what to include/exclude, without involving specific files | A single question | Conclusion + Recommended structure + Notes |
Mode determination is performed automatically by the Agent based on the input; when unsure, first ask the user "do you want to review an existing one, draft one from scratch, or simply ask a best-practice question".
Customer-readable description
What this skill can do
Covers three working modes for AGENTS.md/CLAUDE.md/GEMINI.md and .claude/ configuration: diagnosing the design quality of existing configurations, drafting a configuration skeleton for new projects, and answering best-practice questions. This skill does not call external APIs, does not read accounts or credentials, and in review mode by default does not write files—it is purely text-based diagnosis and output.
| What the customer wants | What the skill will do | What the customer can see |
|---|---|---|
| Review an existing configuration (Mode ①) | Diagnose item by item across six dimensions, pinpointing specific file:line, and only diagnose without making changes | Issue list (file:line/dimension/symptom/suggested fix/priority) + rewrite suggestions + conclusion level |
| Draft a configuration for a new project (Mode ②) | First ask about project type/directory structure/number of collaborating AIs, then produce a skeleton based on the principle of "concise root file + nearest subdirectory" | A draft skeleton file that can be used directly (placeholders explicitly marked) + an explanation of why each field is designed this way |
| Best-practice Q&A (Mode ③) | Directly provide the conclusion, recommended structure, and notes | A concise Q&A-style reply |
| Insufficient input information | Do not guess, do not hard-code; first ask the minimum necessary questions | A specific list of clarifying questions |
| Request to "help me change/optimize/execute" (Mode ① only) | After diagnosis is complete and the customer has explicitly confirmed, change only the parts where problems were diagnosed | Before-and-after comparison of changes + item-by-item change explanations |
How customers use it
- State the request and provide the necessary input: for review mode, give the target file path or full text; for drafting mode, give the project type, directory structure, and number of collaborating AIs; for Q&A mode, ask directly.
- The Agent determines which mode is matched; if it cannot determine, ask first, do not hard-guess.
- Review mode by default only diagnoses and does not modify files—whether this is a diagnostic request or a change request must be clearly distinguished; before the customer explicitly says "help me change/optimize/execute", deliver only the diagnostic report.
- In drafting mode, if any of project type/directory structure/number of collaborating AIs is unclear, first provide a clarifying checklist that asks everything at once, and do not fabricate output.
- The final reply must include: mode determination, the full diagnosis or output, and item-by-item explanations; Mode ① also needs to give a conclusion level and a clear status of "whether changes have been implemented".
Dependencies and installation
Install this skill (single skill):
npx skills add soia-team/soia-open-dev-coding-skills -g -a '*' -s soia-dev-agent-md-advisor -y
Configuration conventions:
~/.config/soia-skills/soia-dev-agent-md-advisor/config.yml
SOIA_DEV_AGENT_MD_ADVISOR_CONFIG_FILE=<custom-config-path>
- Current version of this skilldoes not needCreate
config.yml: the diagnostic dimensions, processes, and templates for the three modes are all written directly in thisSKILL.md, with no private state that needs to be externalized. The above paths are reserved for future optional enhancements such as "customer-defined diagnostic dimension weights / length budget thresholds", and are not required items. - This skill does not need, and should not read, any API key, cookie, session, or account credentials—diagnosis and output only process thetext files provided by the customerand the configuration files that can be read publicly within the project.
soia-dev-doc-syncis a division-of-labor neighbor, not a dependency: this skill does not call it, nor does it perform the cross-document state reconciliation it is responsible for; for the boundary, see "The boundary with soia-dev-doc-sync" above.
Logs and completion receipts
Every execution must let the customer see the judgment, diagnosis/output, and verification process. Minimum receipt format:
完成：<一句话说明本次模式（①审查/②起草/③问答）与结果>。
日志摘要：
- 模式判定：<①/②/③，以及判定依据>
- 澄清记录：<本次问了哪些澄清问题及客户答复摘要；输入已足够时写"未追问，输入已足够">
- 诊断/产出：<模式①写六维度诊断结论与结论等级；模式②写骨架产出摘要；模式③写"不适用（问答）">
文件变化：
- <绝对路径或"未改动文件（本次仅输出诊断/建议/骨架草稿）">
问题与下一步：
- <需要客户确认的事实、占位项，或"是否要现在落地修改"；没有则写"无，可直接使用产出">
Diagnostic dimensions (core assets)
The six dimensions cover the entire inspection surface of configuration file design quality; go through them item by item, not nitpick word by word:
| # | Dimension | Inspection question | Common symptoms | Suggested fix |
|---|---|---|---|---|
| 1 | Length budget | Every line enters the context; if this item were deleted, would the AI's behavior change? | Long background stories, repeated reminders about the same thing, dispensable polite phrases, files continuously expanding to hundreds of lines | Apply the "would deleting it change anything" test line by line: delete anything that would not change; move long processes to skill/subdirectory files, leaving only routing in the root file |
| 2 | Rule enforceability | Can the AI self-check and verify this rule, or is it just empty words? | Unverifiable adjectives such as "write high-quality code", "stay professional", "follow standards"; rules that linters/formatters can enforce deterministically written as long passages of natural language | Replace with verifiable specific commands/paths/thresholds; hand what tools can judge to tools, and do not put empty slogans into the configuration file |
| 3 | Section routing | Are the responsibilities of the root file and subdirectory AGENTS.md/CLAUDE.md clearly divided? Are the rules closest to the code placed nearby in the subdirectory? | The root file is stuffed with details only one submodule needs; a monorepo has only one giant root file, or conversely subdirectory rules and the root file heavily duplicate each other | The root file should contain only global routing + key constraints; module-specific rules sink into that directory's own AGENTS.md/CLAUDE.md, with the root file pointing to it in one line |
| 4 | Duplication and contradiction | Is the same rule repeated in multiple places? Do any two instructions conflict with each other? | The same constraint is written once in the root file and once in a subdirectory; "be as detailed as possible" and "keep within X lines" appear at the same time; old and new rules coexist without deleting the old one | Deduplicate and keep it only in the one place whose responsibility fits best; contradictory instructions must either choose one or explicitly define priority, and must not let the AI guess whose to follow |
| 5 | Entry-point consistency | CLAUDE.md、AGENTS.md、GEMINI.md Are the contents of multiple entry points such as this consistent? Have they drifted apart over time? |
The same project rule is expressed differently or even contradictorily in different entry files; only one entry was updated while the others are still the old version | Choose one entry point as the source of truth (usually AGENTS.md), and change the remaining entry points to concise pointers or references, without maintaining multiple copies of the main text |
| 6 | Timeliness | Do the paths, commands, and tools referenced in the file still exist now? | Pointing to deleted/renamed directories; referencing offline command-line tools or deprecated scripts; version numbers and dependency names were updated long ago but the file did not keep up | Check item by item: anything that can be verified with ls/grep must be verified; for paths that cannot be verified, mark them as "unverified, needs customer confirmation", and do not assert existence from memory |
Diagnosis only reports problematic dimensions; dimensions that pass are mentioned in one sentence; if all six pass, truthfully state "design quality is good, no changes needed for now" and do not manufacture work.
Mode ① Review (Diagnosis) Process
- Identify scope: which files to read——
AGENTS.md、CLAUDE.md、CLAUDE.local.md、GEMINI.md、.claude/settings.json、.claude/skills/*/SKILL.md、.claude/agents/*.md、.claude/commands/*.md、.claude/hooks/. Only read files relevant to this judgment; do not scan the entire repository for diagnosis. - Diagnose the six dimensions one by one: check item by item against the table above; for each problematic dimension, locate the specific file and line number, and quote the original text.
- Determine conclusion level：
- Excellent——all six dimensions meet the standard
- Basically usable——1-2 items have P2-level issues (length, style type, not directly causing errors)
- Needs streamlining——issues are concentrated in length budget/repetition and contradiction
- Needs refactoring——3 or more items have P1-level issues (will cause the agent to repeatedly make the same type of error), or the partition routing is misaligned overall
- Relatively high risk——P0-level issues exist (missing security boundaries, self-contradictory rules leading to unpredictable behavior)
- Output issue list + rewrite suggestions, format see template below.By default, only diagnose; do not modify files——this is a diagnosis request, not a change request.
- Only when the client explicitly says "help me modify/optimize/rewrite/execute" do you enter implementation editing; when editing, only change the parts diagnosed as problematic, keep content that is not problematic, and do not do unrelated stylistic rewriting.
Output template
# AGENTS.md / CLAUDE.md 设计诊断
结论：优秀 / 基本可用 / 需要精简 / 需要重构 / 风险较高
## 问题清单
| 文件:行 | 维度 | 症状 | 建议改法 | 优先级 |
|---|---|---|---|---|
| `<path>:<line>` | <六维度之一> | <具体症状，引用原文> | <改法> | P0/P1/P2 |
## 做得好的地方
- ...
## 改写建议（默认不落地，等待客户确认）
- 保留：...
- 删除：...
- 拆分到子目录：...
- 合并入口：...
## 是否落地修改
- 客户尚未确认，本次仅诊断 / 客户已确认，按以下顺序修改：...
Mode ② Drafting Process
- Ask three things first; if uncertain, ask; do not make things up：
- Project type: what kind of project it is, tech stack, single repository or monorepo
- Directory structure: whether there are multiple independent subprojects/subpackages, and what they are
- Number of collaborating AIs: only Claude Code, or also multiple AIs such as Codex/Gemini/Cursor collaborating
- Determine entry file：
- Only Claude Code →
CLAUDE.mdas the sole entry point - Cross-tool collaboration (multiple AIs such as Codex/Gemini/Cursor) →
AGENTS.mdas the source of truth,CLAUDE.md/GEMINI.mddepending on tool support, make a streamlined pointer or soft link; do not maintain multiple copies of the main text - Monorepo/multiple subprojects → the root file only contains shared rules; place a copy of
AGENTS.md/CLAUDE.mdunder each subproject's own directory nearby to carry its exclusive rules
- Only Claude Code →
- Produce the skeleton according to "streamlined root file + nearby subdirectories"：
- The root file only contains: one-sentence project positioning/tech stack/common commands/directory map and "where new code goes" rules/key MUST-MUST NOT/test and completion criteria/security boundaries
- Subdirectory files only contain rules specific to that directory and not needed by the root file
- Output the full skeleton text, marking which fields are placeholders and need client confirmation.Do not invent commands out of thin air——commands must come from files provided by the client or verifiable in the project (
package.json/pyproject.toml/Makefile/CI workflow, etc.); if they cannot be verified, write<占位符，待确认>and explain.
Skeleton template (single repository)
# AGENTS.md
## 项目
<一句话：这是什么项目，给谁用，主技术栈>
## 常用命令
- 安装：`<command>`
- 测试：`<command>`
- 构建：`<command>`
## 目录地图
- `<path>/` - <职责>
- 新增 <类型> 代码放在 `<path>/`
## 关键规则
- MUST <关键约束>
- MUST NOT <禁止动作>
## 测试与完成标准
- <完成的验证方式>
## 安全边界
- 涉及删除/覆盖/发送/发布前先确认
Monorepo mode
<repo>/
AGENTS.md # 共享规则与路由
<subproject-a>/AGENTS.md # 子项目专属规则
<subproject-b>/AGENTS.md # 子项目专属规则
Mode ③ Q&A Process
Answer directly in concise Chinese, without preamble:
结论：...
推荐结构：
- ...
注意事项：
- ...
.claude/ Configuration responsibility quick reference
Use this table when deciding whether to add a certain .claude/ sub-mechanism, rather than adding everything by default:
| Mechanism | Applicable signal | Over-engineering signal (not recommended to add) |
|---|---|---|
CLAUDE.md/AGENTS.md |
Every project should have it; it carries global rules and the command entry point | — |
.claude/commands/ |
The same prompt is repeatedly typed by hand and is worth solidifying into a template | A temporary prompt used only once |
.claude/skills/ |
A certain type of task has a stable, reusable specialized process or domain knowledge | The content is essentially just a few sentences and is not worth encapsulating separately as a skill |
.claude/agents/ |
Clear role division requiring independent context/independent tool permissions (reviewer/debugger, etc.) | The project is simple and can be handled in one main conversation |
.claude/hooks/ |
The action is deterministic (formatting/validation/logging) and does not depend on subjective judgment | Processes requiring judgment should be given to a skill/agent rather than a hook |
Judgment principle: having many directories does not mean maturity; it may just be over-engineering. Missing directories are not a problem, as long as they are truly not needed at present.
Boundaries and limitations
- This skill does not execute code, run tests, or modify business logic; it only handles the design quality of the AI instruction configuration files themselves.
- Review mode is read-only by default and does not make changes; only when the client explicitly says "optimize/rewrite/execute/change directly" does it make edits, and it only changes the parts diagnosed as problematic.
- Do not invent commands or paths out of thin air; commands must come from verifiable project sources (
package.json/pyproject.toml/Makefile/CI, etc.) or be provided by the client. If they cannot be verified, mark them as "unverified, needs client confirmation". - Do not by default recommend rolling out the complex
.claude/agents+ hooks + skills full package; first judge whether the project really needs it, referring to the quick reference table above. - Does not overlap with
soia-dev-doc-sync: discovering that a path/command referenced by the configuration is already outdated (timeliness dimension) is only a one-time diagnosis that "this file itself should be updated", and does not perform cross-document status reconciliation; work such as true-source conflict judgment, release backfilling, and proposal status alignment is handed over tosoia-dev-doc-sync, and this skill does not do it on its behalf. - This skill only handles files provided by the client or configuration files that can be publicly read within the project, and does not read the client's accounts, vault, or unrelated local files.
Completion receipt
After execution,mustoutput to the user (do not silently finish):
- What was done — a one-sentence summary of this mode (①review/②drafting/③Q&A), clarification situation, and result; mode ① must also state the conclusion level and whether modifications have been made.
- File changes — mode ① defaults to "no files changed (this time only a diagnostic report is output)", unless the client has confirmed and requested implementation; mode ② is fixed as "no files changed (this time only a skeleton draft is output, for the client to create by themselves after confirmation)"; mode ③ is fixed as "no files changed (this skill only outputs Q&A text)".
- Next step — mode ① reminds the client "the diagnosis has been given; do you need to implement the modifications now"; mode ② reminds the client to check whether the placeholders and commands in the skeleton are real, and after confirmation then implement them into files; mode ③ reminds the client that if they want to review existing files or draft new configurations, they can switch to the corresponding mode.