c4-architecture

Overview of c4-architecture skill

The c4-architecture skill helps you generate software architecture documentation as Mermaid C4 diagrams, not just draw boxes. It is best for engineers, technical writers, staff architects, and teams who need architecture docs that explain a system at the right level for the audience: context for broad readers, containers for technical stakeholders, components for developers, and deployment views for operations.

What c4-architecture is for

Use c4-architecture when the real job is to turn a codebase, service landscape, or rough system description into structured architecture documentation. It is especially useful when you need diagrams that can live in Markdown and version control rather than a one-off whiteboard export.

Best-fit use cases

This c4-architecture skill is a strong fit for:

• documenting an existing repo for onboarding
• creating a system context and container view for ADRs or technical docs
• explaining microservices, event-driven systems, and external dependencies
• producing architecture diagrams for docs sites, wikis, or pull requests
• creating architecture content for Technical Writing workflows

What makes it different from a generic diagram prompt

A normal prompt can produce a diagram-shaped answer, but this skill gives you a clearer workflow and better defaults:

• it centers the C4 model, so abstraction levels stay cleaner
• it treats Context and Container as the baseline, not optional extras
• it includes syntax guidance for Mermaid C4 diagrams
• it points you to common modeling mistakes before you publish misleading docs
• it includes advanced patterns for microservices and more complex systems

What users usually care about first

Before installing or invoking c4-architecture, most users want to know:

• Will it help if my system is only partly understood? Yes, if you can provide actors, major services, data stores, and external systems.
• Does it work for Markdown-first documentation? Yes, Mermaid output is the core value.
• Is it useful for technical writers without deep architecture expertise? Yes, because the skill is opinionated about levels and common mistakes.
• Will it replace deep architecture review? No. It accelerates first drafts and structured documentation, but system accuracy still depends on your inputs.

How to Use c4-architecture skill

Install c4-architecture in your skills environment

If your agent supports the skills CLI pattern used by this repository, install with:

npx skills add softaworks/agent-toolkit --skill c4-architecture

If your environment loads skills from a cloned repository instead, use the skill from:

skills/c4-architecture

Read these files first before first use

For a fast, high-signal c4-architecture guide, read in this order:

1. skills/c4-architecture/SKILL.md
2. skills/c4-architecture/references/common-mistakes.md
3. skills/c4-architecture/references/c4-syntax.md
4. skills/c4-architecture/references/advanced-patterns.md
5. skills/c4-architecture/README.md

Why this order works:

• SKILL.md gives the intended workflow
• common-mistakes.md prevents the most common modeling errors
• c4-syntax.md helps you debug Mermaid output quickly
• advanced-patterns.md matters when your system is not a simple monolith

Choose the right C4 level before prompting

The biggest quality lever in c4-architecture usage is picking the right level for the audience:

• C4Context: always start here; shows users and external systems
• C4Container: usually required; shows apps, databases, queues, and services
• C4Component: only add when internal structure genuinely helps readers
• C4Deployment: use for runtime/infrastructure concerns
• C4Dynamic: use for important request or event flows

A common failure mode is jumping straight to components and producing clutter before readers understand the system boundary.

Give the skill the minimum input it actually needs

You do not need perfect architecture notes, but you do need enough structure to avoid hallucinated topology. Good inputs include:

• system name and purpose
• primary users or external actors
• major services/apps/datastores
• external systems or vendors
• key relationships and protocols
• target audience
• desired diagram levels
• output file or doc location

If you only say “make a C4 diagram for my app,” expect generic output.

Turn a rough request into a strong c4-architecture prompt

Weak prompt:

Create a C4 diagram for our platform.

Stronger prompt:

Use the c4-architecture skill to document our B2B analytics platform. Audience: engineering and product. Create C4Context and C4Container diagrams in Mermaid plus brief Markdown explanations. System boundary: Analytics Platform. Actors: Customer Admin, Analyst. External systems: Okta, Stripe, Snowflake, SendGrid. Internal containers: React web app, API gateway, Python ingestion service, dbt transform jobs, PostgreSQL app DB, Redis cache. Show key relationships and protocols. Avoid component-level detail unless necessary.

The stronger version improves output because it specifies audience, scope, boundaries, actors, internal containers, and external dependencies.

Use a practical workflow, not a one-shot ask

A reliable c4-architecture install decision often comes down to whether the workflow matches real documentation work. In practice:

1. ask for a context diagram first
2. review missing actors and external systems
3. generate the container diagram
4. add component or deployment views only where readers need them
5. save diagrams into Markdown with short explanatory text

This staged approach is better than requesting five diagram types at once, because errors at Level 1 and 2 cascade into every lower-level diagram.

Use it well for Technical Writing

c4-architecture for Technical Writing is a good fit when writers need architecture docs that are readable, maintainable, and versioned with code. The skill helps by producing diagrams that can be embedded in Markdown and paired with short prose.

For technical writing tasks, include:

• target reader level: executive, mixed technical, developer, ops
• glossary terms or approved product names
• preferred terminology for services and teams
• docs location, such as /docs/architecture/
• whether the output should explain why each diagram exists

This prevents the common issue where diagrams are technically plausible but misaligned with the documentation voice or information architecture.

Know the modeling rules that most affect output quality

The repository’s mistake guide surfaces a few rules that matter a lot:

• containers are deployable/runtime units, not classes
• components are internal parts within a container
• do not invent unofficial C4 levels
• keep abstraction levels consistent within a diagram
• only add detail that supports the audience’s decision-making

If you remember one thing, remember this: most bad C4 diagrams fail because they mix levels, not because the syntax is wrong.

Use the reference docs when Mermaid output fails

When the generated diagram does not render or looks structurally wrong, check:

• references/c4-syntax.md for valid C4 Mermaid declarations and elements
• relationship syntax and boundary syntax first
• whether you used the correct diagram type, such as C4Container vs C4Component

This skill is more usable than a generic prompt partly because the syntax reference gives you a clear repair path.

When advanced patterns matter

Open references/advanced-patterns.md when your architecture includes:

• microservices with multiple service boundaries
• API gateways
• event-driven or queue-based workflows
• more than one ownership boundary
• infrastructure or deployment views that need real nodes and environments

That file is especially useful when a simple “one system, one app, one database” mental model would produce misleading documentation.

c4-architecture skill FAQ

Is c4-architecture good for beginners?

Yes, especially if you can describe the system in plain language. The skill’s workflow and mistake guide reduce common C4 errors. Beginners should start with Context and Container only and avoid Component diagrams until the system boundary is stable.

When should I not use c4-architecture?

Skip c4-architecture if you only need a quick informal sketch, a pixel-perfect design artifact, or a UML-heavy internal design model. It is strongest when you want maintainable architecture documentation in Mermaid, not exhaustive implementation design.

Is this better than asking an AI for a Mermaid diagram directly?

Usually yes for architecture documentation. A generic prompt can output Mermaid, but c4-architecture gives you a stronger structure: level selection, modeling discipline, syntax reference, and known anti-patterns. That makes it more dependable for docs that other people will read and maintain.

Does c4-architecture work for monoliths and microservices?

Yes. For monoliths, it helps separate context, container, and selective component views. For microservices, the advanced patterns reference is useful for deciding when services are shown as containers versus broader system boundaries.

Do I need access to the full codebase?

No, but better source material improves results. The skill can work from architecture notes, repo structure, service lists, API docs, deployment manifests, or stakeholder descriptions. If your inputs are partial, ask it to mark assumptions explicitly.

Can I use c4-architecture for deployment and runtime views?

Yes. The skill supports C4Deployment and also dynamic flow diagrams. Use these only when runtime topology or request flow matters to the reader; otherwise they can add noise.

How to Improve c4-architecture skill

Start with facts, not inferred structure

The fastest way to improve c4-architecture output is to provide a fact list before asking for diagrams:

• users
• system boundary
• deployable units
• data stores
• external dependencies
• protocols
• environments or hosting model

This reduces confident but wrong relationships.

Ask for assumptions to be listed explicitly

A high-value prompt addition is:

If any element is uncertain, list assumptions before generating the final Mermaid.

This is especially helpful when documenting an inherited system or using the skill from partial notes.

Review context and container output before going deeper

Do not accept a component diagram until the context and container layers are right. If the container model is wrong, component detail only makes the document look polished while staying inaccurate.

Correct abstraction mistakes aggressively

If the output shows classes, packages, or endpoints as containers, stop and fix that first. The common-mistakes.md guidance matters because wrong abstraction levels make the whole document harder to trust.

A useful correction prompt is:

Revise this as a true C4Container diagram. Only include deployable applications, services, data stores, and external systems. Move internal modules to a later component view.

Specify audience in every serious request

Audience changes what “good” looks like:

• executives need context, outcomes, and external dependencies
• engineers need containers, protocols, and responsibility boundaries
• developers may need component detail inside one container
• ops teams need deployment nodes and environments

Without audience, the skill may produce the wrong level of detail even if the syntax is valid.

Pair diagrams with short explanatory prose

The skill is more useful when you ask for 2–5 bullets under each diagram covering:

• what the diagram shows
• why the level was chosen
• key interactions
• what is intentionally excluded

That small addition makes the output much more usable in docs and review threads.

Iterate with targeted edits, not full rewrites

After the first pass, improve quality by giving focused corrections such as:

• add missing external systems
• rename containers to match product terminology
• split one overloaded service into two containers
• add protocols to relationships
• remove component detail from the container view
• generate a deployment view for production only

Targeted iteration preserves good structure and converges faster than “try again.”

Use c4-architecture as a documentation system, not only a generator

The best long-term use of c4-architecture skill is to standardize architecture docs in your repo. Keep the Mermaid diagrams near the code or docs, review them in pull requests, and update them when services or boundaries change. That is where this skill beats ad hoc prompting: it supports repeatable, Markdown-native architecture documentation.