Introduction
What it is
Common Docs organizes project documentation using a progressive disclosure model. A reader, human or agent, moves through the structure in a fixed order: domain context, then system design, then decisions and implementation detail, then operations.
Every directory has an index.md that lists its contents. Finding an answer does not require scanning the whole tree.
Plans describe the future. ADRs record the past. Architecture describes the present. The specification keeps these three separate. A document is a proposal, a decision, or the current state, never a mix.
Why use it
Agents and contributors use the same structure
AI coding agents read project documentation before making changes. Common Docs gives them a fixed entry point, a fixed location for domain terms, and one current source for architecture, instead of a guess across old PRs and comments. Human contributors get the same fixed layout.
- 01Context before detail. Domain first, then design, then implementation.
- 02Every directory has an index. No need to scan the tree.
- 03One concern per file. Split files over about 300 lines.
- 04kebab-case, lowercase. No spaces.
- 05Frontmatter on every file. title, description, status, updated. Enables index generation.
- 06Plans, ADRs, and architecture are separate. Future, past, and present are not conflated.
- 07Curated, not a wiki. Stale docs are updated or deleted.
- 08Agents start at the index.
AGENTS.md/CLAUDE.mdreferencedocs/index.mddirectly.
Compatibility
OKF v0.2 conformance
A docs/ tree built to this specification is a valid bundle under Open Knowledge Format (OKF) v0.2. Every non-reserved file carries a type field. index.md files carry no frontmatter except the bundle root's okf_version. OKF-aware tooling, search indexes, and other agent consumers can traverse and read the tree without custom integration work. Fields such as status and updated are producer-defined extensions. OKF requires consumers to tolerate them.
Docs
Directory structure
The full layout:
docs/
├── index.md # Master entry point
├── context/ # Why we exist, who we serve, domain vocabulary
├── architecture/ # Current system design
├── adr/ # Architecture Decision Records
├── plans/ # Future work, roadmap, feature specs
├── api/ # API reference
├── configuration/ # Configuration reference
├── integrations/ # Third-party integrations
├── security/ # Security posture and practices
├── guides/ # How-to guides for humans and agents
├── operations/ # Production operations
├── migrations/ # Database and data migrations
└── changelog/ # Release historyRequired content for each file, what architecture/overview.md must cover, what belongs in an ADR, what a runbook needs, is defined in the specification.
Docs
Agent skills
Five skills for creating, writing, and maintaining a Common Docs tree. Each is scoped to one job.
common-docs-scaffold
Scaffolds the standard docs/ structure. Creates every section directory and stub file with correct frontmatter.
common-docs-write
Writes the real content for one file. Runs a targeted interview, explores the codebase to fill in what it can, then produces a complete document with no placeholders.
common-docs-write-all
Writes substantive content for every file in the structure in one pass, scaffolding first if needed.
common-docs-find
Maps a question or topic to the exact file that should answer it, using a fixed lookup table.
common-docs-convert-to-okf
Retrofits an existing tree for OKF v0.2 conformance: adds the required type field, strips stray frontmatter from index.md files. A metadata patch, not a content rewrite.
Docs
Get started
-
Get Common Docs. Pick one:
Install with npx
npx skills add velvet-tiger/common-docs@common-docs-write-allClone the repo
git clone https://github.com/velvet-tiger/common-docs.git - Build the docs. Run the
common-docs-write-allskill. It scaffoldsdocs/if it does not exist yet, then writes complete content for every file based on your codebase. - Point your agent at it. Add the reference block below to
AGENTS.mdorCLAUDE.md.
## Documentation
All project documentation is in `docs/`. Always start at `docs/index.md`.
| Section | Path | Contains |
|---------|------|----------|
| Domain & product context | `docs/context/` | Terminology, goals, stakeholders |
| System design | `docs/architecture/` | Current architecture, data model, infrastructure |
| Decision log | `docs/adr/` | Immutable record of architectural decisions |
| Future work | `docs/plans/` | Roadmap, epics, feature specs |
| API reference | `docs/api/` | Endpoints, auth, errors |
| Configuration | `docs/configuration/` | Env vars, flags, secrets reference |
| Integrations | `docs/integrations/` | Third-party system docs |
| Security | `docs/security/` | Threat model, auth design, data handling |
| How-to guides | `docs/guides/` | Setup, development, deployment, contributing |
| Production ops | `docs/operations/` | Monitoring, runbooks, disaster recovery |
| Migration log | `docs/migrations/` | DB and data migration history |
| Release history | `docs/changelog/` | What changed in each release |Docs
Prompt for an LLM
No skill installed. Paste this into any LLM with access to your codebase.
Set up documentation for this project using the Common Docs specification:
https://raw.githubusercontent.com/velvet-tiger/common-docs/main/specification.md
1. Read the specification at that URL.
2. Create the docs/ directory structure it defines, with correct frontmatter on every file.
3. Read the codebase, README, and config files to gather real project detail.
4. Write complete, substantive content for every file. No placeholders or TODOs.
5. Add the documentation reference block to AGENTS.md or CLAUDE.md, pointing to docs/index.md.
If a fact cannot be found in the codebase, say it is not yet defined instead of inventing it.Resources
Links
- SpecificationFull directory structure, frontmatter rules, and per-file content requirements
- READMEProject overview and quick start
- GitHub repositorySource, issues, and the skills directory
- AutomaticCommon Docs is available as a plugin
- LicenseMIT