soia-dev-agent-md-advisor

soia-dev-agent-md-advisor

AGENTS.md / CLAUDE.md / GEMINI.md as well as .claude/(skills / agents / commands / hooks / settings.json)design advisor—reviews whether these files themselves are well written and reasonably structured; 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/ configurationthe files themselves	docs/、README*、CHANGELOG.md, the proposal main document,board.md
Core question	these configuration filesare they well written, how should they be designed, should they be split	whether these documents match thesource of truth(code / board / VERSION / proposal)
Typical trigger	"this AGENTS.md is too long" "how to split CLAUDE.md" "how to manage multiple entry points"	"is there drift between docs and proposal documents" "should docs be backfilled after release"
Output	Design-quality diagnosis + rewriting 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 filesthemselvesstill exist now; it is a one-time snapshot check	Yes, specifically—reconcile across documents by fixed source-of-truth priority whether state, version, and naming are consistent

Decision rule: if the user is asking "are these AI instruction files well written / how should they be organized", use this skill; if the user is asking "do the docs match the actual progress/version", transfer to soia-dev-doc-sync. When both match, first use this skill to diagnose configuration file design issues, and transfer state-alignment issues to soia-dev-doc-sync, do not handle them on behalf of that skill in 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 quality	Target file path or full text	Issue list (file:line/dimension/symptom/suggested fix) + rewriting suggestions + conclusion level;by default, only diagnose, do not make changes
② Drafting	The new project has no configuration yet, or wants to start over	Project type/directory structure/number of collaborating AIs	Skeleton file draft (root file streamlined + subdirectories kept close by), 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 one-sentence question	Conclusion + recommended structure + notes

Mode determination is performed automatically by the Agent based on the input; when unsure, first ask the user "are you looking to review an existing one, draft one from scratch, or simply ask a best-practices question".

Customer-readable description

What this skill can do

Covers the three working modes for AGENTS.md/CLAUDE.md/GEMINI.md and .claude/ configuration: diagnosing the design quality of existing configurations, drafting configuration skeletons for new projects, and answering best-practices questions. This skill does not call external APIs, does not read accounts or credentials, and by default does not write files in review mode—it is purely text-based diagnosis and output.

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 locations, diagnosing only without making changes	Issue list (file:line/dimension/symptom/suggested fix/priority) + rewrite suggestions + conclusion rating
Draft a 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 + subdirectories kept local"	A draft of a directly usable skeleton file (placeholders explicitly marked) + an explanation of why each field is designed this way
Best-practices Q&A (Mode ③)	Directly give conclusions, recommended structures, and cautions	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
A request to "help me modify/optimize/execute" (Mode ① only)	After diagnosis is complete and the customer explicitly confirms, modify only the parts diagnosed as problematic	Before-and-after comparison of changes + item-by-item explanation of changes

How the customer uses it

1. State your 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.
2. The Agent determines which mode is matched; if it cannot determine, it asks first and does not guess.
3. Review mode only diagnoses by default and does not modify files—whether this is a diagnosis request or a change request must be clearly distinguished; before the customer explicitly says "help me modify/optimize/execute", only the diagnosis report is delivered.
4. In drafting mode, if any of project type/directory structure/number of collaborating AIs is unclear, first provide a one-time complete clarification checklist rather than making up output.
5. The final reply must include: mode determination, the full diagnosis or output, and item-by-item explanations; Mode ① also requires a conclusion rating and a clear status of "whether changes have been implemented".

Dependencies and installation

Installation (recommended: install the entire domain plugin to install all skills in this repository at once):

claude plugin marketplace add soia-team/soia-open-skills

claude plugin install soia-dev@soia

When you only want this one skill, you can use the npx route. Note that the skill will land in the shared source of truth ~/.agents/skills; if the plugin is installed at the same time, the same skill will have two indexes and each will drift, so it is recommended to choose one of the two:

npx skills add soia-team/soia-open-dev-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 skillNot requiredCreate config.yml: the diagnostic dimensions, processes, and templates for the three modes are all written directly in this SKILL.md ; there is no private state that needs to be externalized. The above paths are reserved for future optional enhancements such as "customer-customized 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 credential—diagnosis and output only process the client-providedtext filesand publicly readable configuration files in the project.
• soia-dev-doc-sync is 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 boundaries, see the above "Boundary with soia-dev-doc-sync".

WorkBuddy The loading unit of is role-based experts rather than plugins,npx skills add -a '*' cannot cover it, and it needs to be installed separately, see docs/install/workbuddy.md。

Private information and intermediate data

• Input may contain client AI instructions and project structures that have not yet been made public; only read files within the scope of this task, do not scan accounts, vaults, or unrelated directories, and do not copy the original text into public examples.
• This skill does not create persistent state, cache, or independent logs. Diagnosis drafts remain only in the current Agent session; the host's own session retention is managed by the host configuration.
• By default, deliver the diagnosis or skeleton only in the reply. When the client explicitly authorizes writing files, write only the specified file in the target project; before overwriting an existing file, you must first show the diff and confirm.
• Ordinary config.yml is only allowed to store non-secret preferences in the future; this skill does not need credentials, and must not store prompts, complete client files, or response bodies.
• Receipts excerpt only the minimum fragments needed to prove the finding, and redact accounts, paths, or other sensitive fields.

Logs and completion receipts

Each execution must let the client see the judgment, diagnosis/output, and verification process. Minimum receipt format:

完成：<一句话说明本次模式（①审查/②起草/③问答）与结果>。

日志摘要：
- 模式判定：<①/②/③，以及判定依据>
- 澄清记录：<本次问了哪些澄清问题及客户答复摘要；输入已足够时写"未追问，输入已足够">
- 诊断/产出：<模式①写六维度诊断结论与结论等级；模式②写骨架产出摘要；模式③写"不适用（问答）">

文件变化：
- <绝对路径或"未改动文件（本次仅输出诊断/建议/骨架草稿）">

问题与下一步：
- <需要客户确认的事实、占位项，或"是否要现在落地修改"；没有则写"无，可直接使用产出">

Diagnostic dimensions (core asset)

The six dimensions cover the entire inspection surface of configuration file design quality, going through each item, not nitpicking 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?	Large blocks of background story, repeated reminders about the same thing, dispensable polite language, files continuously expanding to hundreds of lines	Apply the line-by-line "would deletion change it" test: delete directly whatever 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," "pay attention to standards"; rules that linter/formatter can deterministically enforce are written as long passages of natural language	Replace with verifiable concrete commands/paths/thresholds; leave what tools can judge to tools, and do not put empty slogans in 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 subdirectories?	The root file is stuffed with details only a certain submodule needs; a monorepo has only one giant root file, or conversely the subdirectory rules and the root file overlap heavily	Put only global routing + key constraints in the root file; push module-specific rules down to that directory's own AGENTS.md/CLAUDE.md, and point to it with one line in the root file
4	Repetition and contradiction	Is the same rule repeated in multiple places? Are there two instructions that conflict with each other?	The same constraint is written once in the root file and once in a subdirectory; "as detailed as possible" and "keep within X lines" appear at the same time; old and new rules coexist but the old ones were not deleted	Deduplicate and keep it only in the one place where the responsibility fits best; contradictory instructions must be resolved by choosing one or by explicitly setting priority, and AI must not be left to guess whose instructions to follow
5	Entry-point consistency	CLAUDE.md、AGENTS.md、GEMINI.md Are the contents of multiple entry points such as these 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 are still on the old version	Choose one entry point as the source of truth (usually AGENTS.md) and change the other entry points into 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 directories that have been deleted/renamed; referencing command-line tools that have been discontinued 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 client confirmation"; do not assert existence from memory

In diagnosis, report only the dimensions with problems, and mention the dimensions that pass in one sentence; if all six pass, truthfully state "the design quality is good, no changes needed for now" and do not manufacture work.

Mode 1 Review (diagnosis) process

1. 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 the files relevant to this judgment; do not scan the entire repository just to diagnose.
2. Diagnose item by item across the six dimensions: check one by one against the table above, and for each problem dimension pinpoint the specific file and line number, quoting the original text.
3. Determine the conclusion level：
   • Excellent—all six dimensions meet the standard
   • Basically usable—1-2 items have P2-level issues (length, style, not directly causing errors)
   • Needs streamlining—problems are concentrated in length budget/duplication and contradiction
   • Needs refactoring—3 or more items have P1-level issues (which would cause the agent to repeatedly make the same kind of mistake), or the partition routing is misaligned overall
   • Relatively high risk—there are P0-level issues (missing security boundaries, self-contradictory rules leading to unpredictable behavior)
4. Output a problem list + rewriting suggestions, with the format shown in the template below.By default, only diagnose and do not modify files—this is a diagnosis request, not a change request.
5. Only when the client explicitly says "help me change/optimize/rewrite/execute" do you enter implementation editing; when editing, change only the parts where problems were diagnosed, preserve the content that is fine, and do not do unrelated stylistic rewriting.

Output template

# AGENTS.md / CLAUDE.md 设计诊断

结论：优秀 / 基本可用 / 需要精简 / 需要重构 / 风险较高

## 问题清单
| 文件:行 | 维度 | 症状 | 建议改法 | 优先级 |
|---|---|---|---|---|
| `<path>:<line>` | <六维度之一> | <具体症状，引用原文> | <改法> | P0/P1/P2 |

## 做得好的地方
- ...

## 改写建议（默认不落地，等待客户确认）
- 保留：...
- 删除：...
- 拆分到子目录：...
- 合并入口：...

## 是否落地修改
- 客户尚未确认，本次仅诊断 / 客户已确认，按以下顺序修改：...

Mode 2 Drafting process

1. Ask three things first; if unsure, ask, do not make assumptions：
   • Project type: what kind of project it is, the 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 at the same time
2. Determine the entry file：
   • Only Claude Code → CLAUDE.md as the sole entry point
   • Cross-tool collaboration (Codex/Gemini/Cursor and other AIs) → AGENTS.md as the source of truth,CLAUDE.md/GEMINI.md use a concise pointer or soft link depending on tool support, and do not maintain multiple copies of the body text
   • Monorepo/multiple subprojects → the root file only holds shared rules, and each subproject places a copy nearby under its own directory for AGENTS.md/CLAUDE.md to carry its exclusive rules
3. Produce a skeleton based on "concise root file + nearby subdirectory"：
   • The root file only holds: 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 hold rules specific to that directory that the root file does not need
4. Output the full skeleton, and mark 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

When deciding whether to add a certain .claude/ sub-mechanism, use this table, rather than adding everything by default:

Mechanism	Applicable signals	Over-engineering signals (adding is not recommended)
CLAUDE.md/AGENTS.md	Every project should have it, carrying global rules and command entry points	—
.claude/commands/	The same prompt is repeatedly typed by hand, so it 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 packaging separately as a skill
.claude/agents/	Clear role division requiring independent context/independent tool permissions (reviewer/debugger, etc.)	The project is simple, and one main conversation is enough
.claude/hooks/	The action is deterministic (formatting/validation/logging) and does not depend on subjective judgment	Processes requiring judgment should be assigned to a skill/agent rather than a hook

Judgment principle: many directories do 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 change business logic; it only handles the design quality of AI instruction configuration files themselves.
• Review mode is read-only by default and does not modify; 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 determine whether the project really needs it, referring to the quick reference table above.
• Does not overlap with soia-dev-doc-sync : finding that paths/commands referenced by the configuration are 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 source-of-truth conflict judgment, release backfilling, and proposal status alignment is transferred to soia-dev-doc-sync, and this skill does not do it on its behalf.
• This skill only processes files provided by the client or publicly readable configuration files in the project; it does not read the client's account, vault, or unrelated local files.

Completion receipt

The receipt includes:

1. 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 changes have been implemented.
2. File changes — Mode ① defaults to "No files changed (this session only outputs a diagnostic report)" unless the client has confirmed and requested implementation; mode ② is fixed as "No files changed (this session only outputs a skeleton draft for the client to create on their own after confirmation)"; mode ③ is fixed as "No files changed (this skill only outputs Q&A text)".
3. Next steps — Mode ① reminds the client "The diagnosis has been provided; do you need to implement the changes now?"; mode ② reminds the client to verify whether the placeholders and commands in the skeleton are real, and to implement them into files after confirmation; mode ③ reminds the client that if they want to review existing files or draft new configurations, they can switch to the corresponding mode.