agentic-docs

name

agentic-docs

description

Bootstrap, audit, and maintain repository-local documentation systems for agentic software work. Use when Codex needs to create or reorganize AGENTS.md, ARCHITECTURE.md, docs/index.md, design docs, product specs, exec plans, generated references, DESIGN.md (Google Labs format for visual design tokens), or documentation governance for a project that lacks agent-readable docs or needs docs/ structure updates.

Agentic Docs

Use this skill to make repository knowledge discoverable, resumable, and verifiable for coding agents. Keep this file as the routing layer; load references only when needed.

Portability And Privacy

Treat this skill as portable infrastructure. It must be safe to commit to a personal dotfiles repo or share across unrelated projects.

• Do not include source-project names, customer names, private repository paths, internal URLs, secrets, tenant names, product codenames, or proprietary architecture details in the skill or templates.
• Generalize from examples into reusable placement rules and workflows.
• Keep project-specific details in the target repository's docs, not in this skill.
• Before committing updates to this skill, run a targeted rg check for known private names and local absolute paths.

Decision Rule

Create or update docs when the project lacks a reliable answer to one of these questions:

• Where should an agent start reading?
• Where do stable architecture decisions live?
• Where do product/user-facing requirements live?
• How is multi-turn implementation state resumed?
• Which generated contracts or external references are trusted?
• Which docs rules are mechanically checked?

If the repository already answers these questions clearly, avoid new structure. Tighten links, freshness, or verification instead.

Workflow

1. Inspect the project before writing.
   • Read existing AGENTS.md, CLAUDE.md, README.md, ARCHITECTURE.md, docs/, package scripts, test configs, and lint configs.
   • Use rg to find existing mentions of docs, plans, architecture, ADRs, generated schemas, and product specs.
   • Identify the real subsystems and checks. Do not invent categories that do not fit the repository.
2. Choose the mode.
   • Bootstrap: no coherent docs system exists.
   • Audit: docs exist but navigation, freshness, or ownership is unclear.
   • Update: a code or architecture change needs docs to stay in sync.
3. For bootstrap or structural changes, read references/doc-structure.md.
4. For template generation, read references/templates.md, then prefer scripts/bootstrap_docs.py over manually recreating files.
5. Connect every new doc from the appropriate index.
6. Prefer checks over prose: link durable rules to tests, schemas, type checks, lint rules, textlint, or scripts when those checks exist.
7. Verify before reporting completion.
   • Run relevant markdown/text lint if available.
   • Run link or grep checks when docs were moved.
   • Report any pre-existing failures separately from the files you changed.

Resources

• references/doc-structure.md: placement rules, bootstrap shape, and quality bar.
• references/templates.md: template catalog and generation workflow.
• references/design-md-format.md: Google Labs DESIGN.md format reference for visual design tokens.
• scripts/bootstrap_docs.py: copy the generic docs scaffold into a target repo.
• assets/templates/: generic templates used by the script.
• assets/optional/: opt-in templates not copied by the bootstrap script (currently DESIGN.md).