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 reasonably structured, and is not responsible for whether they are in sync with the project's current state. Three modes: ① review existing configuration (diagnose) ② draft a configuration skeleton for a new project (draft) ③ 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 this 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 | This configuration fileis it well 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 should CLAUDE.md be split" "How to manage multiple entry points" | "Has the docs and proposal documents drifted" "Should documents be backfilled after release" |
| Output | Design quality diagnosis + rewriting suggestions, or a new skeleton draft | State drift list + backfill order |
| Whether cross-document state reconciliation is done | No—the "timeliness" dimension only checks whether the paths/commands referenced by the configuration fileitselfstill exist now, as a one-time snapshot check | Yes, specifically—checks across documents whether state, version, and naming are consistent 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 them on its behalf in this skill.
Overview of the Three Modes
| Mode | Trigger scenario | Input | Output |
|---|---|---|---|
| ① Review (diagnose) | The user already has AGENTS.md/CLAUDE.md/GEMINI.md/.claude configuration and wants to assess its quality |
Target file path or full text | Issue list (file:line/dimension/symptom/suggested fix) + rewriting suggestions + conclusion level;by default only diagnoses, does not modify |
| ② Draft | A new project has no configuration yet, or wants to scrap it and start over | Project type/directory structure/number of collaborating AIs | Skeleton file draft (streamlined root file + nearby subdirectories), with placeholders marked as to be confirmed |
| ③ Q&A | The user asks about best practices such as format, structure, what to include/exclude, without involving specific files | One question | Conclusion + recommended structure + caveats |
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 from scratch, or just ask a best-practice question".
Customer-readable description
What this skill can do
Covers AGENTS.md/CLAUDE.md/GEMINI.md and .claude/ three working modes of configuration: diagnosing the design quality of existing configuration, drafting a configuration skeleton for a new project, and answering best-practice questions. This skill does not call external APIs, does not read accounts or credentials, and in review mode does not write files by default—pure text diagnosis and output.
| What the customer wants | What the skill will do | What the customer can see |
|---|---|---|
| Review existing configuration (Mode ①) | Diagnose item by item across six dimensions, pinpointing specific file:line, only diagnosing without making changes | Issue list (file:line/dimension/symptom/suggested fix/priority) + rewrite suggestions + conclusion level |
| Draft configuration for a new project (Mode ②) | First ask about project type/directory structure/number of collaborating AIs, then produce a skeleton following the principle of "concise root file + nearby subdirectories" | A draft of a directly usable skeleton file (placeholders explicitly marked) + an explanation of why each field is designed this way |
| Best-practice Q&A (Mode ③) | Directly give the conclusion, recommended structure, and caveats | A concise Q&A-style reply |
| Insufficient input information | Do not guess, do not hardcode; first ask the minimum necessary questions | A specific list of clarifying questions |
| Request to "help me modify/optimize/execute" (Mode ① only) | After diagnosis is complete and the customer has explicitly confirmed, only modify the parts diagnosed as problematic | Before-and-after comparison of changes + item-by-item explanation of changes |
How the customer uses 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, just ask the question directly.
- The Agent determines which mode is hit; if it cannot determine, ask first, do not guess.
- Review mode only diagnoses by default, without modifying files—whether this is a diagnosis request or a modification request must be clearly distinguished; before the customer explicitly says "help me modify/optimize/execute", only deliver the diagnosis report.
- In drafting mode, when any of the 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 requires a conclusion level and a clear status of "whether modifications have been implemented".
Dependencies and installation
Install this skill (single skill):
npx skills add soia-team/soia-open-skills -g -a '*' -s soia-dev-agent-md-advisor -y
Configuration conventions:
~/.config/soia-skills/soia-open-skills/soia-dev/soia-dev-agent-md-advisor/config.yml
SOIA_DEV_AGENT_MD_ADVISOR_CONFIG_FILE=<custom-config-path>
- Current version of this skillNot requiredCreate
config.yml: the diagnostic dimensions, processes, and templates for the three modes are all written directly in thisSKILL.md; there is no private state that needs to be externalized. The above path is reserved for future optional enhancements such as "customer-defined diagnostic dimension weights / length budget thresholds", and is not required. - This skill does not need to and should not read any API key, cookie, session, or account credentials—diagnosis and output only process the customer-providedtext filesand configuration files that can be publicly read 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 "Boundary with soia-dev-doc-sync" above.
Logging and Completion Receipts
Every execution must let the client 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 line were deleted, would the AI's behavior change? | Long stretches of backstory, repeated reminders about the same thing, dispensable polite phrasing, files continuously bloating to hundreds of lines | Apply the "would it change if deleted" test line by line: delete outright anything that wouldn't change; move long processes to skill/subdirectory files, keeping only routing in the root file |
| 2 | Rule Executability | Can the AI self-check and verify this rule, or is it just empty words? | Unverifiable adjectives like "write high-quality code," "stay professional," "pay attention to standards"; rules that a linter/formatter can execute deterministically written as long stretches of natural language | Replace with verifiable concrete commands/paths/thresholds; hand off to tools whatever tools can judge, instead of writing 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 heavily duplicate the root file | Put only global routing + key constraints in the root file; push module-specific rules down to 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 written once in the root file and once in a subdirectory; "be as detailed as possible" and "keep within X lines" appearing at the same time; old and new rules coexisting without deleting the old ones | Deduplicate, keeping it only in the one place where responsibility fits best; contradictory instructions must be reduced to one of the two or have an explicit priority, and the AI must not be left to guess whose to follow |
| 5 | Entry Point Consistency | CLAUDE.md、AGENTS.md、GEMINI.md Are the contents of multiple entry points such as consistent? Have they drifted apart over time? |
The same project rule is phrased differently or even contradicts itself across different entry files; only one entry point was updated while the others remain on 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, not maintaining multiple copies of the body text |
| 6 | Currency | Do the paths, commands, and tools referenced in the file still exist now? | Pointing to deleted/renamed directories; referencing command-line tools that have been taken offline or deprecated scripts; version numbers and dependency names were updated long ago but the file hasn't kept up | Check item by item: anything that can be verified with ls/grep must be verified; for paths that cannot be verified, mark "unverified, needs client confirmation" rather than asserting existence from memory |
Diagnosis reports only the 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/. Read only 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, pinpoint 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 overall misaligned
- Relatively high risk—P0-level issues exist (missing security boundaries, self-contradictory rules leading to unpredictable behavior)
- Output issue list + rewrite suggestions, format as in the 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 change/optimize/rewrite/execute" do you enter implementation editing; when editing, change only the parts diagnosed as problematic, preserve content that is fine, and do not perform unrelated stylistic rewrites.
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 multiple AIs such as Codex/Gemini/Cursor collaborating at the same time
- Determine the 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 contains only shared rules; place a copy of
AGENTS.md/CLAUDE.mdin each subproject's own directory nearby to carry its specific rules
- Only Claude Code →
- Produce the skeleton according to "streamlined root file + nearby subdirectories"：
- The root file contains only: 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 contain only rules specific to that directory that the root file does not need
- 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 them all by default:
| Mechanism | Applicable signals | Over-design signals (not recommended to add) |
|---|---|---|
CLAUDE.md/AGENTS.md |
Every project should have it, carrying global rules and the command entry point | — |
.claude/commands/ |
The same prompt is repeatedly typed by hand, worth solidifying into a template | A one-off temporary prompt used only once |
.claude/skills/ |
A certain type of task has a stable, reusable specialized workflow or domain knowledge | The content is essentially just a few sentences, not worth packaging separately into a skill |
.claude/agents/ |
Clear role division requiring independent context/independent tool permissions (reviewer/debugger, etc.) | The project is simple, and a single main conversation can handle it |
.claude/hooks/ |
The action is deterministic (formatting/validation/logging) and does not depend on subjective judgment | Processes requiring judgment should be handed to a skill/agent rather than a hook |
Judgment principle: many directories do not mean maturity—it may just be over-design; 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.
- In review mode, only read by default without modifying; only when the client explicitly says "optimize/rewrite/execute/directly modify" will edits be made, and only the parts diagnosed with problems will be changed.
- Do not invent commands or paths out of thin air; commands must come from project-verifiable 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 launching the complex
.claude/agents+ hooks + skills full package; first determine whether the project really needs it, referring to the quick reference table above. - Does not overlap with
soia-dev-doc-sync: discovering that paths/commands referenced in the configuration are already outdated (timeliness dimension) is only a one-off diagnosis that "this file itself should be updated", not 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 their behalf. - This skill only processes files provided by the client or configuration files that can be publicly read in the project; it does not read the client's accounts, vault, or unrelated local files.
Receipt after completion
After executionmustoutput to the user (do not silently finish):
- What was done — a one-sentence summary of this session's mode (①review/②draft/③Q&A), clarifications, and results; mode ① should also state the conclusion level and whether edits have been made.
- File changes — mode ① defaults to "no files changed (this session only outputs a diagnostic report)", unless the client has confirmed and requested edits; mode ② is fixed as "no files changed (this session only outputs a skeleton draft, for the client to create themselves after confirmation)"; mode ③ is fixed as "no files changed (this skill only outputs Q&A text)".
- Next steps — mode ① reminds the client, "the diagnosis has been provided; do you need to make the edits now?"; mode ② reminds the client to check whether the placeholders and commands in the skeleton are real, and after confirmation, turn it into a file; mode ③ reminds the client that if they want to review existing files or draft new configurations, they can switch to the corresponding mode.