Provider-agnostic arc42 documentation skills for AI coding assistants — Claude Code, GitHub Copilot, Cursor, Codex, and any LLM tool that reads markdown.
Create professional software architecture documentation through guided, interactive AI conversations. Each of the 12 arc42 sections is covered by a dedicated skill that asks the right questions first, generates a structured draft, then iterates until you are satisfied.
- 14 interactive skills — one per arc42 section, plus quality review and consistency linting
- Provider-agnostic — works with Claude Code, GitHub Copilot, Cursor, Codex, and any LLM tool
- Ask-first approach — every skill gathers your project details before generating anything
- Three depth levels — LEAN, ESSENTIAL, or THOROUGH, chosen per section based on your needs
- C4 PlantUML diagrams — architecture diagrams as separate
.pumlfiles, never inlined - Q42 quality model — 492 quality attributes across 8 properties integrated into relevant skills
- Cross-section consistency — skills check related sections and flag contradictions
- Automated consistency linting — catch IF-xx, QS-xx, ADR, and RISK-xx mismatches before they accumulate
- Standards-based — grounded in arc42.org, docs.arc42.org, and quality.arc42.org
arc42 is the proven, open-source template for software architecture documentation created by Dr. Gernot Starke and Dr. Peter Hruschka. Used in thousands of projects worldwide, it provides a pragmatic, tool-agnostic approach.
Core philosophy:
- Document economically but continuously
- "Painless documentation" — only what stakeholders truly need
- All sections are optional — use what fits your project
- Suitable for agile and traditional environments
One mandatory exception: Section 1.2 (Quality Goals) must exist before any other architecture work begins.
Claude Code
claude plugin install MSiccDev/arc42-toolkitSkills are available as slash commands immediately.
GitHub Copilot CLI
copilot plugin install arc42-toolkitIf the arc42-toolkit marketplace is not yet registered, add it first:
copilot plugin marketplace add MSiccDev/arc42-toolkit
copilot plugin install arc42-toolkitOpenAI Codex
Use the built-in $skill-installer inside Codex and provide the repository URL, or install for your user account:
# User-wide (available in all your projects)
git clone https://github.com/MSiccDev/arc42-toolkit.git ~/.codex/skills/arc42-toolkit
# Project-wide (checked into the repo)
git clone https://github.com/MSiccDev/arc42-toolkit.git .codex/skills/arc42-toolkitCursor, Copilot Chat, and other tools
Clone or copy into your project:
git clone https://github.com/MSiccDev/arc42-toolkit.gitOr copy AGENTS.md, the skills/ directory, and the .agents/ symlink into your existing project.
Windows / ZIP installs: If symlinks are unavailable, create a directory junction instead:
mklink /J .agents skills(Windows CMD) — or simply copy theskills/directory to.agents/.
Invoke the skill for your AI tool:
| Tool | Command |
|---|---|
| Claude Code | /arc42-section-01 |
| GitHub Copilot Chat | #arc42-section-01 |
| Cursor / Codex | Reference skills/arc42-section-01/SKILL.md in context |
The skill asks about your project — requirements, stakeholders, quality goals. No generation happens until you have answered.
The skill produces a draft, runs a built-in quality checklist, and asks what you want to refine. Repeat until satisfied.
Use the same pattern for each section you need. The /arc42-review skill validates any section or the full document at any time.
arc42-toolkit/
│
├── AGENTS.md # Project context — read by all AI assistants
├── README.md # This file
├── LICENSE # MIT License
├── CONTRIBUTING.md # Contribution guidelines
│
├── skills/ # Canonical skill source (agentskills.io spec)
│ ├── arc42-section-01/SKILL.md # Introduction and Goals
│ ├── arc42-section-02/SKILL.md # Constraints
│ ├── arc42-section-03/SKILL.md # Context and Scope
│ ├── arc42-section-04/SKILL.md # Solution Strategy
│ ├── arc42-section-05/SKILL.md # Building Block View
│ ├── arc42-section-06/SKILL.md # Runtime View
│ ├── arc42-section-07/SKILL.md # Deployment View
│ ├── arc42-section-08/SKILL.md # Crosscutting Concepts
│ ├── arc42-section-09/SKILL.md # Architecture Decisions
│ ├── arc42-section-10/SKILL.md # Quality Requirements
│ ├── arc42-section-11/SKILL.md # Risks and Technical Debt
│ ├── arc42-section-12/SKILL.md # Glossary
│ ├── arc42-review/SKILL.md # Quality review (any section or full doc)
│ └── arc42-lint/SKILL.md # Cross-section consistency linter
│
├── scripts/
│ ├── arc42-lint.py # Standalone linter (stdlib only, CI-ready)
│ └── languages/
│ ├── en.json # English (default)
│ ├── de.json # Deutsch
│ ├── fr.json # Français
│ ├── it.json # Italiano
│ ├── es.json # Español
│ └── pt.json # Português
│
├── templates/
│ └── arc42-lint.yml # GitHub Actions workflow template (copy to your project)
│
└── .agents/ -> skills/ # Symlink for agent-discovery compatibility
Generated documentation goes in your project's docs/ directory. Architecture diagrams are stored as .puml files in docs/diagrams/.
| Section | Name | Skill | Required? |
|---|---|---|---|
| 1 | Introduction and Goals | /arc42-section-01 |
Quality goals mandatory |
| 2 | Constraints | /arc42-section-02 |
Optional |
| 3 | Context and Scope | /arc42-section-03 |
Recommended |
| 4 | Solution Strategy | /arc42-section-04 |
Recommended |
| 5 | Building Block View | /arc42-section-05 |
Level-1 mandatory |
| 6 | Runtime View | /arc42-section-06 |
Optional |
| 7 | Deployment View | /arc42-section-07 |
Optional |
| 8 | Crosscutting Concepts | /arc42-section-08 |
Optional |
| 9 | Architecture Decisions | /arc42-section-09 |
Recommended |
| 10 | Quality Requirements | /arc42-section-10 |
Recommended |
| 11 | Risks and Technical Debt | /arc42-section-11 |
Optional |
| 12 | Glossary | /arc42-section-12 |
Recommended |
Use /arc42-review at any point to validate one section, a related set, or the full document.
Use /arc42-lint to check cross-section ID consistency automatically.
Every skill supports three depth levels. Choose based on your project's needs — you can use different levels for different sections.
Best for: Agile teams, time-constrained projects, evolving systems
- 1–3 pages per section maximum
- Essential information only — "dare to leave gaps"
- Minimum viable documentation: Section 1.2, Section 3, Section 5 Level-1, Section 9, Section 12
Best for: Most projects — the balanced default
- Non-negotiable minimum for production systems
- Critical architectural information enabling team understanding
- Includes LEAN content plus requirements overview, stakeholders, black-box descriptions
Best for: Critical systems, regulated environments, audit requirements, large teams
- Complete documentation across all sections
- Detailed scenarios, multiple diagram levels, extensive validation
- Full Q42 quality scenario coverage
/arc42-section-01
Skills are automatically available as slash commands when AGENTS.md and the skills/ directory (with .agents/ symlink) are in your project.
#arc42-section-01
Use in Copilot Chat. Copilot reads AGENTS.md for project context automatically.
Open skills/arc42-section-01/SKILL.md in the Composer context, or reference it with @SKILL.md in chat.
Paste the content of the relevant SKILL.md file as a system prompt or context message. All skills are plain markdown — they work with any LLM that understands structured text.
- Save documentation time through guided, structured generation
- Consistent, high-quality output across all sections
- Standards-compliant documentation without needing to memorise arc42 rules
- Focus on architectural decisions, not formatting
- Shared vocabulary and structure across the organisation
- Easy onboarding — new members understand the system faster
- Reduced documentation debt through iterative, incremental documentation
- Better stakeholder communication with consistent artifact format
- Standardized architecture documentation across projects
- Knowledge preservation — decisions and rationale are captured, not just the outcome
- Improved audit readiness
- Scalable process that works from startup to enterprise
The skills integrate the Q42 quality model — a comprehensive framework with 492 quality attributes in 8 properties. Quality goals from Section 1 are traced through constraints, solution strategy, deployment, crosscutting concepts, and quality scenarios.
| Property | Attributes | Focus |
|---|---|---|
| #reliable | 97 | Availability, Fault Tolerance, Accuracy |
| #flexible | 50 | Adaptability, Maintainability, Extensibility |
| #efficient | 71 | Response Time, Throughput, Resource Usage |
| #usable | 103 | Learnability, Operability, Accessibility |
| #safe | 28 | Risk-free, Fail-safe, Hazard Warnings |
| #secure | 36 | Confidentiality, Integrity, Authentication |
| #suitable | 52 | Functional Completeness, Testability |
| #operable | 55 | Installability, Monitorability, Deployability |
Learn more: quality.arc42.org
The arc42 toolkit ships a standalone linter that validates cross-section ID consistency in your generated documentation. It catches mismatches that accumulate silently over time — interface IDs renamed in one section but not another, ADR risks never registered, quality scenarios with no matching goal.
| Rule | Sections | Validates |
|---|---|---|
| 1 | Section 3 ↔ Section 5 | IF-xx interface IDs match between the context diagram and Level-1 building blocks |
| 2 | Section 5 ↔ Section 7 | Every building block name appears in the deployment mapping |
| 3 | Section 1 ↔ Section 10 | Every Q42 tag used in quality scenarios is present in Section 1.2 quality goals |
| 4 | Section 9 ↔ Section 11 | Every RISK-xx in an ADR's "Risks created" field has a Section 11 risk matrix entry |
| 5 | Section 10 ↔ Section 11 | Every aspirational (not yet met) scenario from Section 10.3 is referenced in Section 11 |
# Check docs/ in English (default)
python scripts/arc42-lint.py
# Check docs written in another language
python scripts/arc42-lint.py --lang de
python scripts/arc42-lint.py --lang fr
python scripts/arc42-lint.py --lang it
python scripts/arc42-lint.py --lang es
python scripts/arc42-lint.py --lang pt
# Check a custom path
python scripts/arc42-lint.py path/to/your/docs --lang de
# Treat warnings as errors (useful in CI)
python scripts/arc42-lint.py --strictExit code 0 = clean, 1 = issues found.
Copy templates/arc42-lint.yml from this repo to .github/workflows/arc42-lint.yml in your project. It runs automatically when files under docs/** change.
To use in your own project: copy the entire scripts/ directory (script + languages) and templates/arc42-lint.yml (to .github/workflows/arc42-lint.yml) into your repo. No Python dependencies to install — stdlib only.
Copy any file from scripts/languages/ as a starting point, name it scripts/languages/{code}.json, and translate the keyword patterns. All values are case-insensitive regular expressions — plain text works too. Multiple alternatives are supported per pattern. Once merged, the new language is available via --lang {code}.
Use /arc42-lint to run the linter interactively through your AI tool. The skill runs the script when available, or applies the five rules manually when not. It also offers to fix any issues it finds.
Contributions are welcome. Here is how you can help:
- Report issues — found a problem with a skill? Open a bug report
- Improve skills — better questions, clearer checklists, sharper output templates
- Add examples — submit real-world arc42 documentation produced with this toolkit
- Domain-specific variants — skills tuned for microservices, embedded systems, data platforms
- Share feedback — used it on a real project? Tell us what worked and what did not
Read our Contributing Guide for detailed guidelines.
This project is licensed under the MIT License — see the LICENSE file for details.
Note: arc42® is a registered trademark of Dr. Gernot Starke and Dr. Peter Hruschka. This project is based on the freely available arc42 template and is not officially affiliated with arc42.org.
This repository is a demonstration of AI-assisted technical content development. The arc42 skills were created through iterative collaboration between a human architect (Marco) and Claude (Anthropic's AI assistant), grounded in official arc42 sources throughout.
- Research — Extensive review of arc42.org, docs.arc42.org, quality.arc42.org, faq.arc42.org
- Skill development — Section-by-section creation of interactive skills following the agentskills.io specification
- Quality assurance — Systematic review against arc42 standards for accuracy and completeness
- Iterative refinement — Multiple review and improvement cycles, including Copilot code review
- Provider-agnostic refactor — Migrated from Copilot-specific prompts to the AGENTS.md + skills standard
- Authenticity first — all content based on official arc42 sources, nothing invented
- Standards compliance — validated against docs.arc42.org and quality.arc42.org
- Human oversight — human architect provided direction, requirements, and validation
- AI efficiency — AI assistant handled research, synthesis, and structured content creation
This repository was researched and structured by AI from authoritative arc42 sources, directed by human expertise in software architecture, validated through systematic quality reviews, and is maintained with ongoing human oversight.
- arc42 Template — Created by Dr. Gernot Starke and Dr. Peter Hruschka
- Official Sources:
- arc42.org — Main website
- docs.arc42.org — Official documentation
- quality.arc42.org — Q42 quality model
- faq.arc42.org — Frequently asked questions
- Claude (Anthropic) — AI assistant used in creating and refining this repository's content
- Contributors — See CONTRIBUTORS.md for everyone who has helped
- Architecture Decision Records (ADR)
- C4 Model — Recommended diagramming approach (used throughout this toolkit)
- agentskills.io — Skills specification this toolkit follows
- Issues: GitHub Issues
- Discussions: GitHub Discussions
- Questions: Open a discussion or issue
- v1.0 — Complete arc42 coverage, all 12 sections + review skill
- Skills-based — Migrated to provider-agnostic AGENTS.md + skills standard
- Actively maintained — Regular improvements based on real-world usage
- Community driven — Open to contributions
Migrated from a Copilot-specific prompt library to a provider-agnostic skills toolkit following the agentskills.io standard. All 12 section skills and the review skill are complete with:
- Interactive question-first approach
- LEAN / ESSENTIAL / THOROUGH depth levels
- C4 PlantUML diagram generation
- Cross-section consistency checks
- Actionable quality checklists
Goal: Battle-test the toolkit on an actual project
- Use case: persona-template MCP Server — a developer tool for managing persona preferences and software projects across AI providers
- Purpose: document the MCP (Model Context Protocol) server architecture using this toolkit
- Output: complete example arc42 documentation in the repository, serving as a reference implementation
Goal: Expand examples and community contributions
- More real-world documentation examples
- Domain-specific skill variants (microservices, embedded systems, data platforms)
- Community-submitted examples and improvements
- Tutorial content and walkthroughs
- Test it — use the toolkit on your project and share feedback
- Contribute examples — submit your arc42 documentation as reference material
- Report issues — help identify and fix problems
- Suggest improvements — share ideas for better skills or output templates
- Star the repo — help others discover this resource
Made for the software architecture community.
Bringing structured, AI-assisted efficiency to architecture documentation while maintaining standards compliance.