Skip to content
OpenAgentSkill
Browsing is open · Catalog captured 2026-11-21 · Automatic updates and account services are paused.
DevOps & cloud

accelint-architecture-doc

Create or update a living ARCHITECTURE.md for a codebase. Use when the user wants to write, refresh, restructure, or maintain an architecture document; document how the system is organized across tech stack, deployment model, services, components, and data stores; or turn codebase findings into durable architecture docs for engineers or agents. Trigger on requests such as write an architecture doc, document this system, create or update ARCHITECTURE.md, give me a technical overview of this repo, or map out how this app is put together, even when the file is not named. Prefer this skill for file-producing architecture documentation, not for generic architecture advice, implementation planning, or diagram-only brainstorming unless that work is clearly part of updating the document.

accelint · Static checks on file

Installation

Read the source and dependencies before running a command. Copying does not install or execute anything.

npx skills add gohypergiant/agent-skills --skill accelint-architecture-doc

About this skill


name: accelint-architecture-doc description: Create or update a living ARCHITECTURE.md for a codebase. Use when the user wants to write, refresh, restructure, or maintain an architecture document; document how the system is organized across tech stack, deployment model, services, components, and data stores; or turn codebase findings into durable architecture docs for engineers or agents. Trigger on requests such as write an architecture doc, document this system, create or update ARCHITECTURE.md, give me a technical overview of this repo, or map out how this app is put together, even when the file is not named. Prefer this skill for file-producing architecture documentation, not for generic architecture advice, implementation planning, or diagram-only brainstorming unless that work is clearly part of updating the document. license: Apache-2.0 metadata: author: accelint version: "1.2.2"

Architecture Doc

Generate or update a living ARCHITECTURE.md for the current codebase. It should give agents and engineers a fast, complete view of the system structure, tech stack, and deployment model.

Architecture-Doc Guardrails

  • MUST NOT overwrite ARCHITECTURE.md without reading it first — existing sections may contain human-authored context such as deployment specifics, security decisions, and roadmap notes that codebase scanning cannot recover. Always read the file before you touch it.
  • MUST NOT fabricate infrastructure details — if you cannot determine the cloud provider, deployment model, or data store from the codebase, mark it <!-- TODO: fill in --> rather than guessing. Wrong infrastructure docs cause real confusion during incidents.
  • MUST NOT paste the entire directory tree verbatim — the Project Structure section should show meaningful architectural layers, not every file. Collapse noisy directories (node_modules, dist, .git, __pycache__) and annotate each entry with its architectural role.
  • MUST NOT skip drift detection in refresh mode — scan the codebase for changed signals before you run any interview. Questions about unchanged sections waste the user's time.
  • MUST NOT leave all 11 sections as <!-- TODO --> — scan aggressively first. Most sections can be filled at least partially through inference. A document full of TODOs appears complete but misleads every reader.
  • MUST NOT document internal implementation details in the System Diagram (Section 2) — that section is a 10,000-foot view of components and data flow. Database schemas, function signatures, and module internals belong elsewhere.
  • MUST use parallel subagents for Stage 2 discovery when subagents are available — spawn them simultaneously across discovery domains. Do not scan serially. If subagents are unavailable, use focused inline discovery instead.

Before writing, ask

Check these points before you start. Do them in order.

Is this root or package level?

  • Are we at the repo root or inside a monorepo package? Check for pnpm-workspace.yaml, turbo.json, nx.json, lerna.json, or a workspaces field in package.json. If you are inside a package, also check whether a root-level ARCHITECTURE.md already exists.
  • Root-level docs cover the whole system: all services, shared infrastructure, and top-level architecture. Package-level docs focus on that package and reference the root.

Is this a create, restructure, or refresh?

  • Does ARCHITECTURE.md already exist? If yes, read it before you scan so you know what is accurate and what has drifted.
  • Does it follow the template? If not, proactively offer to restructure it before you modify the file structure.

What can I infer vs. what must I ask?

  • Use parallel subagents for discovery when subagents are available. Spawn them simultaneously across discovery domains. Do not scan serially. If subagents are unavailable, use focused inline discovery instead.
  • Reserve questions for genuine gaps such as deployment specifics, roadmap items, and security decisions that are not in the code.

Workflow

Stage 0: Track progress

Purpose: keep workflow state visible during create, refresh, or restructure handling.

Step 0: Start progress tracking

Do this before any other stage work when the task requires create, refresh, or restructure handling. Create a short progress checklist in your working state or reply. Update it after each stage.

  • Step 1: Detect scope and related files
  • Step 2: Detect mode and apply the correct gate
  • Step 3: Run discovery and merge findings
  • Step 4: Ask the targeted interview questions
  • Step 5: Show the preview and wait for confirmation
  • Step 6: Write the approved files and summarize open TODOs

Done when: the checklist exists and will be updated after each stage.

Stage 1: Scope and mode detection

Purpose: determine scope, detect related files, and activate the correct mode gate before discovery or interview work begins.

Step 1: Detect scope and related files

Determine whether the current working directory is a monorepo root or a package inside a monorepo. Do this before you detect mode.

Monorepo signals to check:

SignalFile
PNPM workspacespnpm-workspace.yaml
npm/Yarn workspacespackage.json → workspaces field
Turborepoturbo.json
Nxnx.json
Lernalerna.json
Package inside monorepoParent dirs contain any of the above

If at the monorepo root:

  • Generate a root-level ARCHITECTURE.md covering the full system — all services, shared infra, and how packages relate.
  • Within Section 3 (Core Components), create a subsection per significant package rather than treating the repo as a single app.
  • In Section 1 (Project Structure), show the workspace layout with each package's role annotated.

If inside a monorepo package:

  1. Check whether a root-level ARCHITECTURE.md exists above the current directory.
  2. If a root doc exists, re
Read the complete source ↗