SKILL DOCUMENTATION

Repo Docs Generator

Generate repository harness docs: a short AGENTS.md map, README.md, CLAUDE.md stub, and repo-local docs that make the codebase legible to agents.

Overview

Generate repository harness docs: a short AGENTS.md map, README.md, CLAUDE.md stub, and repo-local docs that make the codebase legible to agents.

This skill ships inside the Repo Docs Generator plugin and can be installed through the Claude Code marketplace or directly in Codex from its skill path.

Parent Surface

Parent docs: Repo Docs Generator

Related wrapper commands from the parent plugin:

/repo-docs:generate/repo-docs:canonicalize

When to Use This Skill

failure modes.

  • A repo has weak, stale, or missing agent-facing documentation.
  • AGENTS.md has become a long dumping ground instead of a navigation layer.
  • Engineers or agents keep rediscovering the same commands, constraints, or failure modes.
  • You want to canonicalize CLAUDE.md into a minimal @AGENTS.md stub.
  • You want repo docs that improve execution speed, not just onboarding prose.

Core Model

Treat documentation as a layered harness:

hold the durable details.

Important nuance:

docs/quality/gates.md or docs/architecture/overview.md.

  • AGENTS.md is the canonical entrypoint.
  • The source of truth for a topic can live in a linked doc such as docs/quality/gates.md or docs/architecture/overview.md.
  • CLAUDE.md must not carry unique behavioral rules.

Required Outcomes

Every run should leave the repo with a clear harness shape:

commands, and which constraints are non-negotiable.

  • AGENTS.md
  • Short, scannable, and command-heavy.
  • Explains what the repo is, where important docs live, how to run key commands, and which constraints are non-negotiable.
  • Usually targets roughly 80-180 lines unless the repo is genuinely tiny.
  • README.md
  • Preserves human-authored content.
  • Points readers to AGENTS.md and any major docs directories.
  • CLAUDE.md
  • Minimal @AGENTS.md stub only.
  • docs/ (or existing equivalent)
  • Add or normalize topic-specific docs when the repo complexity warrants it.
  • Prefer a few focused docs over one giant file.

Generate Mode

Use /repo-docs:generate when creating or rebuilding the harness from scratch.

docs/ indexes first.

commands.

type gate (ty, then pyright, then mypy, unless repo docs/CI differ).

runbooks.

its directory.

flows better than prose and code references.

recommend or add mechanical enforcement when reasonable.

repeating the same free-form instructions.

  • Read existing README.md, AGENTS.md, CLAUDE.md, and any existing docs/ indexes first.
  • Inspect manifests, wrappers, CI, pre-commit, scripts, Makefiles, and test commands.
  • Identify recurring failure modes, architectural boundaries, and the active type gate (ty, then pyright, then mypy, unless repo docs/CI differ).
  • Tiny repo: README.md, AGENTS.md, CLAUDE.md may be enough.
  • Normal product repo: add focused docs for architecture, quality gates, and runbooks.
  • Complex monorepo: add per-domain docs and keep each AGENTS.md scoped to its directory.
  • Put stable commands, navigation, and "where truth lives" in AGENTS.md.
  • Put deep architecture, policies, plans, and runbooks in topic docs.
  • Keep diagrams optional; include them only when they clarify boundaries or flows better than prose and code references.
  • If the repo repeatedly fails on the same issue, document the fix path and recommend or add mechanical enforcement when reasonable.
  • Prefer wrapper commands, lint messages, CI checks, and dedicated docs over repeating the same free-form instructions.

Resources

Declared allowed tools:

BashReadEditWriteGrepGlob

References

  • generate-and-canonicalize-playbook.md
  • harness-principles.md
  • templates.md

Installation

Switch between Claude Code and Codex, then copy the install command for the runtime you use.

claude plugin marketplace add DiversioTeam/agent-skills-marketplace
claude plugin install repo-docs@diversiotech

Invocation:

/repo-docs:generate
/repo-docs:canonicalize