agentleFS
SawanaLabsSawanaLabs/agent-demos/.agents/skills/project-docs-system/SKILL.md

project-docs-system

Skill4 starsChanged 56 days agoMITView on GitHub

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.

The file

Show its rules and text

We split this skill into the rules it gives an agent

32 rules. About 0 are common, 13 are distinctive, and 19 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈13

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 19

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Read AGENTS.md, docs/DOCS.md, and docs/index.md if they exist.

    line 17
  2. Very specific:

    If docs/index.md exists, read relevant docs/<domain>/DOCS.md and docs/<domain>/index.md files before editing leaf docs.

    line 18
  3. Very specific:

    Treat docs/ as initialized only when compatible docs/DOCS.md (Project Knowledge Protocol) and docs/index.md files exist.

    line 19
  4. Distinctive:

    Use the starter layout in references/docs-layout.md.

    line 22
  5. Distinctive:

    Create or maintain the core files.

    line 23
  6. Distinctive:

    Keep file roles distinct.

    line 24
  7. Distinctive:

    When creating a new leaf doc, copy the structure in references/subdomain-doc-template.md.

    line 26
  8. Very specific:

    Treat non-Markdown resource directories under docs/ as outside docs layout validation.

    line 28
  9. Very specific:

    Put cross-domain language, collaboration conventions, and boundary principles in docs/DOCS.md.

    line 31
  10. Very specific:

    Put domain-level language, conventions, and boundary principles shared by multiple subdomain docs in docs/<domain>/DOCS.md.

    line 32
  11. Very specific:

    Put domain navigation in docs/<domain>/index.md.

    line 33
  12. Very specific:

    Put stable subdomain knowledge in docs/<domain>/<subdomain>.md by default, or in a deeper indexed scope when the project needs another …

    line 34
  13. Very specific:

    Add a ## Domain Language section only when a docs file depends on confirmed project-specific terms.

    line 35
  14. Very specific:

    Keep current knowledge in the living document.

    line 36
  15. Distinctive:

    Keep companions out of index entries and generated catalogs.

    line 37
  16. Distinctive:

    Do not store short-lived debugging notes or one-off session details.

    line 38
  17. Distinctive:

    Keep AGENTS.md as the entry point.

    line 40
  18. Very specific:

    If docs/ is initialized, ensure AGENTS.md includes this exact rules block:

    line 41
  19. Very specific:

    If docs/ is not initialized yet, do not add the rules block yet.

    line 51
  20. Very specific:

    When adding a first-level domain, create both docs/<domain>/DOCS.md and docs/<domain>/index.md.

    line 54
  21. Very specific:

    When adding, renaming, merging, or removing living Markdown docs files, update the nearest parent index.md in the same change.

    line 55
  22. Very specific:

    When adding, renaming, merging, or removing a child docs directory, update the nearest parent index.md with the child index.md link in the …

    line 56
  23. Very specific:

    When adding, renaming, merging, or removing first-level domains, update docs/index.md in the same change.

    line 57
  24. Distinctive:

    Update docs during normal work, not as an afterthought.

    line 59
  25. Distinctive:

    After a user correction, update the relevant docs file in the same task when possible.

    line 60
  26. Distinctive:

    After a new module or workflow appears, add or extend the relevant domain and subdomain docs.

    line 61
  27. Distinctive:

    Prefer short, durable bullets over long narrative notes.

    line 62
  28. Distinctive:

    When bootstrapping a new system from scratch, use the frontmatter keys in references/docs-layout.md.

    line 67
  29. Very specific:

    Keep docs files scoped and stable.

    line 68
  30. Very specific:

    Keep ## Domain Language short: use one-sentence definitions, optional _Avoid_: ..., and optional Related: ....

    line 69
  31. Distinctive:

    When migrating inline decision records, move their history into the companion without changing its meaning or chronology.

    line 70
  32. Very specific:

    When shell access is available, run the bundled scripts/verify-docs-system.sh with the target repo root or docs/ directory to verify the …

    line 83

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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/<domain>/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 <stem>.adr.md companion, reached only through its living <stem>.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/<domain>/DOCS.md and docs/<domain>/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.
    • 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.
    • 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/<domain>/DOCS.md.
    • Put domain navigation in docs/<domain>/index.md.
    • Put stable subdomain knowledge in docs/<domain>/<subdomain>.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 <stem>.adr.md with relative Markdown links in both directions. Create it only when there is history to preserve. See the companion template.
    • 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:
<!-- BEGIN:docs-system-rules -->
# 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/<domain>/DOCS.md`, `docs/<domain>/index.md`, and `docs/<domain>/<subdomain>.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.
<!-- END:docs-system-rules -->
  • If docs/ is not initialized yet, do not add the rules block yet.
  1. Keep maps complete.
    • When adding a first-level domain, create both docs/<domain>/DOCS.md and docs/<domain>/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.
  2. 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.
  • Keep docs files scoped and stable; move repeated domain-level knowledge into docs/<domain>/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](./<stem>.adr.md) and [Current documentation](./<stem>.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/<domain>/DOCS.md and docs/<domain>/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 with the target repo root or docs/ directory to verify the docs structure.
  • Summarize what was created or updated and why.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.