| 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
- 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.
- 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.
- For bootstrap or structural changes, read
references/doc-structure.md.
- For template generation, read
references/templates.md, then prefer
scripts/bootstrap_docs.py over manually recreating files.
- Connect every new doc from the appropriate index.
- Prefer checks over prose: link durable rules to tests, schemas, type checks,
lint rules, textlint, or scripts when those checks exist.
- 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).
