# Project Docs System > Bootstrap, audit, or maintain a repository-specific project docs system centered on `AGENTS.md` and `docs/`, including repository DOCS, domain DOCS, docs index files, domain index files, subdomain docs, and lightweight decision records. Use for any agent (such as Codex, Claude Code, and OpenClaw) when it needs to initialize docs files, maintain indexed docs maps, add or update project conventions, capture durable non-obvious practices, preserve scoped decisions, or sync AGENTS.md docs-system rules. - Skill: `multicul-silver-wolf/project-docs-system` (Agent Skill, multi-file: 9 files) - Install (CLI): `npx skillmds@latest add multicul-silver-wolf/project-docs-system` - Raw SKILL.md: https://api.skillmd.com/api/skills/multicul-silver-wolf/project-docs-system/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: multicul-silver-wolf (https://skillmd.com/u/multicul-silver-wolf) - Updated: 2026-09-22 - Page: https://skillmd.com/skills/multicul-silver-wolf/project-docs-system --- # Project Docs System Build and maintain a layered docs system so future work can reuse durable project knowledge without collapsing everything into one file. ## Design Philosophy This docs system borrows from Domain-Driven Design: organize durable knowledge around project domains and bounded contexts, keep shared vocabulary explicit, and place each convention where its scope belongs. `docs/DOCS.md` is the repository knowledge protocol for cross-domain language, collaboration conventions, and boundary principles; `docs//DOCS.md` carries the same kind of shared principles inside one domain; index files act as a context map, and leaf docs capture stable knowledge inside one focused subdomain. Decision history lives in an adjacent `.adr.md` companion, reached only through its living `.md` document. Do not force tactical DDD patterns into the docs unless the project itself uses them. ## Follow This Workflow 1. Inspect the current docs state. - Read `AGENTS.md`, `docs/DOCS.md`, and `docs/index.md` if they exist. - If `docs/index.md` exists, read relevant `docs//DOCS.md` and `docs//index.md` files before editing leaf docs. - Treat `docs/` as initialized only when compatible `docs/DOCS.md` (Project Knowledge Protocol) and `docs/index.md` files exist. - Detect whether the repository already has a docs convention and preserve it when possible. 2. Use the starter layout in [references/docs-layout.md](./references/docs-layout.md). - Create or maintain the core files. - Keep file roles distinct. - Reuse the standard frontmatter keys and section layout. - When creating a new leaf doc, copy the structure in [references/subdomain-doc-template.md](./references/subdomain-doc-template.md). - Allow deeper docs scopes when they are useful and indexed. - Treat non-Markdown resource directories under `docs/` as outside docs layout validation. 3. Sort knowledge before writing. - Put cross-domain language, collaboration conventions, and boundary principles in `docs/DOCS.md`. - Put domain-level language, conventions, and boundary principles shared by multiple subdomain docs in `docs//DOCS.md`. - Put domain navigation in `docs//index.md`. - Put stable subdomain knowledge in `docs//.md` by default, or in a deeper indexed scope when the project needs another grouping level. - Add a `## Domain Language` section only when a docs file depends on confirmed project-specific terms. - Keep current knowledge in the living document; move decision history into an adjacent `.adr.md` with relative Markdown links in both directions. Create it only when there is history to preserve. See [the companion template](./references/adr-template.md). - Keep companions out of index entries and generated catalogs. Read them only when the linked living document makes the historical reasoning relevant. - Do not store short-lived debugging notes or one-off session details. 4. Keep `AGENTS.md` as the entry point. - If `docs/` is initialized, ensure `AGENTS.md` includes this exact rules block: ```md # This is NOT the docs system you know This repository maintains project-specific knowledge and conventions in `docs/`; start with `docs/index.md` and `docs/DOCS.md`, then follow links into `docs//DOCS.md`, `docs//index.md`, and `docs//.md` as needed, treat `docs/` as the source of durable non-obvious project practices, and use the installed `$project-docs-system` skill when initializing, maintaining, or updating this docs system. ``` - If `docs/` is not initialized yet, do not add the rules block yet. 5. Keep maps complete. - When adding a first-level domain, create both `docs//DOCS.md` and `docs//index.md`. - When adding, renaming, merging, or removing living Markdown docs files, update the nearest parent `index.md` in the same change. - When adding, renaming, merging, or removing a child docs directory, update the nearest parent `index.md` with the child `index.md` link in the same change. - When adding, renaming, merging, or removing first-level domains, update `docs/index.md` in the same change. 6. Update docs during normal work, not as an afterthought. - After a user correction, update the relevant docs file in the same task when possible. - After a new module or workflow appears, add or extend the relevant domain and subdomain docs. - Prefer short, durable bullets over long narrative notes. ## Editing Rules - Preserve the repository's chosen freshness key if one already exists. - When bootstrapping a new system from scratch, use the frontmatter keys in [references/docs-layout.md](./references/docs-layout.md). - Keep docs files scoped and stable; move repeated domain-level knowledge into `docs//DOCS.md` and repeated cross-domain knowledge into `docs/DOCS.md`. - Keep `## Domain Language` short: use one-sentence definitions, optional `_Avoid_: ...`, and optional `Related: ...`; skip the section when no confirmed terms are needed. - When migrating inline decision records, move their history into the companion without changing its meaning or chronology; retain current behavior in the living document and add both links. Use `[Decision history](./.adr.md)` and `[Current documentation](./.md)`. - Preserve earlier rationale when decisions change. A planned decision does not establish implemented behavior. - When verification warns that a document exceeds 500 author-maintained lines, review it for accumulated ADRs, mixed responsibilities, and unnecessary reading context. Extract history, split cohesive domains, or trim content as appropriate; do not split mechanically to satisfy the threshold. This applies to companions too; generated catalog blocks are excluded. - Reference concrete files, routes, or modules when that makes the docs more reusable. ## Final Verification - Confirm the core docs files exist and are linked together. - Confirm every docs document starts with frontmatter. - Confirm every first-level Markdown docs domain has `docs//DOCS.md` and `docs//index.md`. - Confirm `docs/index.md` covers every first-level Markdown docs domain. - Confirm each docs scope `index.md` covers its direct living Markdown docs files and child docs scope indexes; companion ADRs are excluded. - Confirm each companion has a living document and relative Markdown links in both directions. - When shell access is available, run the bundled [scripts/verify-docs-system.sh](./scripts/verify-docs-system.sh) with the target repo root or `docs/` directory to verify the docs structure. - Summarize what was created or updated and why.