architecture-md-writer
Create, update, review, or split ARCHITECTURE.md files when docs are missing, stale, over-detailed, poorly scoped, or need nested subsystem coverage.
How do I install this agent skill?
npx skills add https://github.com/sjunepark/agent-scripts --skill architecture-md-writerIs this agent skill safe to install?
- Gen Agent Trust Hubpass
This skill provides a structured workflow and guidelines for an AI agent to create and maintain ARCHITECTURE.md files. It focuses on technical writing best practices and does not include any malicious commands, network activities, or data access risks.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
What does this agent skill do?
ARCHITECTURE.md Writer
Write architecture docs that give contributors a fast mental model of system shape, starting points, and non-negotiable constraints. Prefer stable structure over implementation trivia, and prefer editing existing ARCHITECTURE.md files over creating new ones unless the scope is wrong.
Workflow
- Determine scope and document topology.
- Inspect whether the task is for the repo root, a subsystem, or both.
- Treat the root
ARCHITECTURE.mdas the system map, not the full encyclopedia. - Add nested
ARCHITECTURE.mdfiles only when a subtree has enough independent structure, lifecycle, or constraints to justify its own page. - When adding a nested doc, update the parent doc to link to it and explain its scope in one line.
- When deciding whether to split, merge, add, or remove architecture documents, read guides/document-topology.md before changing the document topology.
- Build context from stable code structure.
- Read existing docs only to recover boundaries, terminology, and decision history.
- Inspect entry points, package boundaries, long-lived directories, interfaces, background jobs, storage seams, and external integrations.
- Trace one or two important flows end to end so the document reflects how the system actually moves.
- Capture responsibilities, interactions, and invariants before drafting prose.
- Draft the smallest useful document.
- Explain what the system or module is for, what major parts exist, and how they interact.
- Prefer concrete file and directory starting points over exhaustive inventories.
- Use a small ASCII diagram only when it shortens explanation; do not use Mermaid.
- Choose section names that fit the system instead of forcing a rigid template.
- When drafting a new document, reorganizing sections, or choosing how to present components, runtime flow, code paths, or invariants, read guides/section-patterns.md before drafting.
- Keep the document high-level and durable.
- Omit class-by-class or function-by-function catalogs.
- Omit setup steps, coding standards, runbooks, and tutorials unless a design constraint depends on them.
- Link ADRs for rationale and tradeoff history instead of embedding long decision logs.
- If an area is unclear, say less and point to the best start-here files rather than speculating.
- Review for contributor usefulness.
- Ensure a new engineer can answer: what are the major parts, where should I start tracing behavior, and what must not be broken?
- Remove statements that would go stale after an ordinary refactor.
- When updating an existing doc, check every remaining claim against the current code; fix or delete any that no longer hold.
- Verify links, file paths, and parent-child architecture doc references.
- Preserve repository terminology so readers can jump from document to code without translation.
Writing Rules
- Prefer short paragraphs and flat bullets.
- Write from outside in: system shape first, then the most important flows and files.
- Call out
start herefiles explicitly. - Name invariants as enforceable rules, not vague values.
- When a module doc exists, state how it fits into the parent architecture and link back upward.
- Treat missing ADRs as a fact to note briefly, not a reason to invent rationale.
- Favor searchable headings and concrete paths over narrative filler.
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/sjunepark/agent-scripts/architecture-md-writer">View architecture-md-writer on skillZs</a>