architecture-documenter

Maintain and update architecture documentation in docs/architecture/. Uses tool-based inspection first, falling back to CLI only when needed.

⭐5stars🔀1forks📁View on GitHub🕐Updated Jan 11, 2026⬇️2downloads

When & Why to Use This Skill

The Architecture Documenter is a specialized Claude skill designed to automate the creation and maintenance of technical architecture documentation. By leveraging tool-based inspection and real-time code analysis, it ensures that your project's documentation remains synchronized with the actual codebase. It automatically generates structured Markdown files and Mermaid diagrams, eliminating documentation rot and providing a clear, visual map of system components, cloud infrastructure, and service flows.

Use Cases

  • Automated Documentation Sync: Keeping architecture docs up-to-date automatically after major code refactors or infrastructure changes to ensure they reflect the 'current reality'.
  • New Project Onboarding: Rapidly generating a comprehensive documentation entry point (index.md) and system overviews to help new developers understand the project structure.
  • Visualizing Complex Systems: Creating and updating Mermaid diagrams to illustrate data flows, service dependencies, and cloud topologies without manual drawing.
  • Standardizing Technical Docs: Enforcing a consistent documentation structure across multiple services or repositories using predefined templates for CI/CD, cloud, and service architectures.
namearchitecture-documenter
description"Maintain and update architecture documentation in docs/architecture/. Uses tool-based inspection first, falling back to CLI only when needed."

Architecture Documenter Skill

General Guidance

This skill maintains architecture documentation under:

docs/architecture/

Always use tool-based inspection first (MCP tools if configured).
Only fall back to CLI when necessary.

Documentation must always reflect current reality, not assumptions.

When asked to update documentation:

  1. Inspect existing docs (if any).
  2. Inspect code/configs/infrastructure via tools.
  3. Determine which documentation files make sense for this project.
  4. Create/update only relevant files.
  5. Never guess — ask for confirmation if unclear.
  6. Use Mermaid diagrams where they add clarity.

Documentation Structure

Index File (MANDATORY)

Always create docs/architecture/index.md as the main entry point. This is the only mandatory file.

This file should:

  • Provide a brief overview of the system
  • Link to other architecture documents (if any exist)
  • Explain the system architecture in a way that's readable on its own
  • Include a high-level diagram of key components
  • Be comprehensive enough to understand the system without other docs

Optional Supporting Documentation Files

Only create additional files if the system is complex enough to warrant them. Use these as templates when relevant:

system-overview.md

High-level map of the entire system, major components, and external integrations.

When to create:

  • Multi-service systems
  • Systems with external integrations
  • Complex architectures needing bird's-eye view

cloud-architecture.md

Cloud deployment topology, networking model, load balancers, compute layers, storage.

When to create:

  • Cloud-deployed applications
  • Infrastructure-heavy systems
  • Multi-region or complex networking

service-architecture.md

Internal services, modules, queues, APIs, and data flows.

When to create:

  • Microservices architectures
  • Service-oriented systems
  • Multiple internal APIs

cicd-architecture.md

Build, test, artifact creation, deployment flow, environments.

When to create:

  • Complex CI/CD pipelines
  • Multiple deployment environments
  • Custom build/deploy processes

You can also create custom documents based on the project's specific needs (e.g., data-architecture.md, security-architecture.md, api-architecture.md).


Templates

Template files are provided in this skill directory:

  • index.md - Entry point template (always use this)
  • system-overview.md - Optional system-level template
  • cloud-architecture.md - Optional cloud infrastructure template
  • service-architecture.md - Optional service/API template
  • cicd-architecture.md - Optional CI/CD pipeline template

Adapt these templates to fit the project. Remove sections that don't apply, add sections that are needed.

Behavioral Rules

  • MANDATORY: Always create docs/architecture/index.md - it's the only required file.

  • Use tool-based introspection before CLI.

  • Ask for files or context when uncertain.

  • Only create additional documents if the project complexity warrants them.

  • The index.md should be comprehensive enough to stand alone for simple systems.

  • Update diagrams to match reality.

  • Keep diagrams readable and scoped.

  • Maintain consistency across documents.

  • Filenames: All filenames MUST be lowercase and use dashes (-) as word separators. Do not use spaces or underscores.

  • If a suggested template doesn't fit, adapt or skip it.

  • When in doubt about which files to create, ask the user.

  • When in doubt about which files to create, ask the user.

  • README maintenance: Keep the repository README.md up to date with the current state of the application. Prefer an overview-only README that links to the relevant docs/architecture/ pages for detailed information.