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.