Agent Docs

agent-docs — Project docs that answer locally before the web

Project docs that answer locally before the web.

Agent Docs is a small set of file-based Agent Skills that give a coding agent a curated, on-disk reference for the tools, services, and frameworks your project actually uses. Install once — the same skills/ tree runs in Claude Code, Gemini CLI, GitHub Copilot, and OpenCode.

The payoff: the agent lands on the right upstream URL in one hop instead of N web searches, and every agent on every run gets the same answer for the same question.

Why this exists

Agents waste a lot of turns web-searching for things the project already commits to.

• Web searches are slow, lossy, and often grab the wrong version of a doc.
• The "right" answer for a given repo is narrower than upstream — flags actually used, patterns this project follows, the canonical URL the team trusts.
• Without curation, two agents researching the same topic on the same repo come back with two different answers.

Agent Docs flips the default: the project ships a tiny, dated reference set under .agents/docs/, and agents read it before reaching for the web.

What you get

• Local-first lookups. use-agent-docs teaches the agent to consult .agents/docs/INDEX.md before web research — fewer round-trips, more reproducible answers.
• Navigation map first. Each DOC.md leads with a structured documentation map — the upstream nav, captured as one-line link entries grouped by section — plus a brief summary and key concepts. The agent lands on the right upstream URL in one hop instead of N web searches. Soft cap: ~100 lines per DOC.md, ~150 for a subtopic deep-dive.
• Progressive disclosure. Default gather is lightweight: one fetch per topic produces the link map. Captured snippets (paste-ready patterns) are opt-in — extended on user request ("deepen X"), or backfilled when use-agent-docs fetches upstream for depth and the user opts in.
• Honest staleness. Every page opens with YAML frontmatter (last_verified, optional upstream_commit, sources.{docs,repo,changelog,release}). INDEX.md propagates the oldest date per topic — agents see the staleness floor at a glance, and tooling can parse it without regex.
• Smart refresh. refresh-agent-docs reads the frontmatter and short-circuits when upstream hasn't moved (commit-pin match, or no changelog entries newer than last_verified); falls through to a link-rot scan of the documentation map. Pages it cannot re-verify get a visible > ⚠ Stale banner until the next successful run.
• Tiered capture. The documentation map is captured by default (T1: page title + URL + one-line hook, every entry in upstream nav). Paste-ready snippets are captured on request with a per-block source link (T2, capped at ~5 per topic). Volatile values (model IDs, pricing, preview flags) are linked, never copied (T3). Captured details are verbatim — never paraphrased, inferred, or auto-completed.
• Subtopic split when warranted. Large surfaces (e.g. a CLI's hooks, extensions, MCP servers) get sibling files like HOOKS.md, EXTENSIONS.md — each with its own refresh clock.
• Install once, use anywhere. The same skills/ tree drives Claude Code, Gemini CLI, GitHub Copilot, and OpenCode.

The three skills

• `/gather-agent-docs` — Seed .agents/docs/ with a navigation map for the project's key topics (tools, services, frameworks). Default writes INDEX.md and one DOC.md per topic with summary, key concepts, and a structured link index of upstream pages. On request ("deepen X"), enriches a topic with up to ~5 paste-ready snippets.
• `/use-agent-docs` — Before web-searching for a project topic, check .agents/docs/INDEX.md and scan the matching DOC.md's documentation map for the right upstream URL. No-op when the file is missing.
• `/refresh-agent-docs` — Re-verify entries against upstream: repair dead links in the documentation map, update drifted snippets, bump last_verified dates, insert a > ⚠ Stale banner when a page can't be re-verified. Default scope is every topic; targets a single topic or topic/subtopic when named. Smart-refresh path uses upstream_commit / sources.changelog to skip work when upstream hasn't changed.

The three pair into a small loop:

gather → use → (drift detected) → refresh → use → ...
       ↘ (depth needed) → deepen ↗

Walkthrough

$ /gather-agent-docs
  → inspects the project (package manifests, CI configs, IaC files), picks 3–8 topics
  → fetches one upstream nav source per topic (sidebar / docs home / sitemap)
  → writes .agents/docs/<topic>/DOC.md with frontmatter, summary, key concepts, documentation map
  → writes .agents/docs/INDEX.md with one dated line per topic
  → "Seeded 5 topics under .agents/docs/. Review the diff before committing."

$ /use-agent-docs       # invoked implicitly whenever the agent is about to web-search
  → reads INDEX.md, opens DOC.md, scans the documentation map for the right entry
  → fetches the matching upstream URL on demand (one hop, not N web searches)
  → optionally backfills a paste-ready snippet to DOC.md's Patterns section if the user opts in

$ /gather-agent-docs deepen gemini-cli
  → revisits gemini-cli's DOC.md; captures up to 5 high-frequency snippets (T2) with inline _Source: …_
  → adds a Patterns section, bumps last_verified

$ /refresh-agent-docs gemini-cli
  → tries the cheap path first: matches upstream_commit / scans sources.changelog since last_verified
  → falls through to a link-rot scan of the documentation map; repairs moved/renamed pages
  → re-verifies any captured snippets against their inline _Source: …_ links
  → "gemini-cli: links repaired (DOC.md), unchanged (HOOKS.md, smart path)."

See it in action

examples/ ships a worked sample of what /gather-agent-docs produces in an end-user project — two topics (gemini-cli, cloud-run), one with a deepened subtopic split (HOOKS.md). The directory layout matches what the skill writes into your own repo under .agents/docs/.

Install

Claude Code

/plugin marketplace add fmind/agent-docs
/plugin install agent-docs@agent-docs

For local development, point the marketplace at a clone:

/plugin marketplace add /path/to/agent-docs
/plugin install agent-docs@agent-docs

Gemini CLI

gemini extensions install fmind/agent-docs

For local development (live-link, edits reload on next session):

gemini extensions link /path/to/agent-docs

Antigravity CLI

agy plugin install https://github.com/fmind/agent-docs

For local development (live-link, edits reload on next session):

agy plugin install /path/to/agent-docs

OpenCode

To use these skills in OpenCode, place or clone the skill directories under .agents/skills/ (for project scope) or ~/.agents/skills/ (for global scope). OpenCode automatically discovers and loads them.

GitHub Copilot

Copilot CLI:

copilot plugin marketplace add fmind/agent-docs
copilot plugin install agent-docs@agent-docs

For local development, point the marketplace at a clone:

copilot plugin marketplace add /path/to/agent-docs
copilot plugin install agent-docs@agent-docs

VS Code — point chat.pluginLocations at a local clone:

// settings.json
"chat.pluginLocations": {
  "/path/to/agent-docs": true
}

Reference

Layout

agent-docs/
├── AGENTS.md                          # canonical context — read by Copilot; @-included by CLAUDE.md / GEMINI.md
├── skills/                            # Agent Skills (open standard)
│   ├── gather-agent-docs/SKILL.md     # user-facing: seed .agents/docs/
│   ├── use-agent-docs/SKILL.md        # user-facing: read .agents/docs/ before web research
│   └── refresh-agent-docs/SKILL.md    # user-facing: re-verify entries against upstream
├── examples/                          # worked sample of what /gather-agent-docs produces
├── .claude-plugin/                    # Claude Code plugin manifest + bundled marketplace
├── gemini-extension.json              # Gemini CLI extension manifest
├── plugin.json                        # GitHub Copilot manifest
└── .github/workflows/ci.yml           # lint via pre-commit

In an end-user project after /gather-agent-docs:

.agents/docs/
├── INDEX.md                           # one dated entry per topic, pointing to its DOC.md
└── <topic>/                           # kebab-case slug (e.g. gemini-cli, cloud-run)
    ├── DOC.md                         # entry point: summary, key concepts, documentation map, optional patterns
    └── <SUBTOPIC>.md                  # optional deep dive (e.g. EXTENSIONS.md, HOOKS.md)

INDEX.md's per-topic date is the oldest last_verified among the topic's files (DOC.md plus any subtopic files), so the index honestly reflects the staleness floor.

When to split a subtopic

Each DOC.md aims to be a self-sufficient navigation map for the topic (soft cap ~100 lines; ~150 for subtopic deep-dives). Split a subsystem into a sibling <SUBTOPIC>.md when all of the following hold:

• The subsystem has its own canonical upstream page(s) — distinct from the topic's overview.
• The deepened version (with captured snippets) would push past the soft cap.
• Agents reach for that depth repeatedly in this project, not just hypothetically.

The link map alone rarely justifies a split — surfaces are wide but each entry is one line. Fold a subtopic back into DOC.md if it shrinks below its own weight.

Contributing

Issues and PRs welcome. Two house rules to keep the skills lean:

• Skill files have line caps (see AGENTS.md §Conventions) — they load into agent context on every run, so verbosity costs budget.
• Voice is imperative. Skill bodies address the agent ("Read X, then write Y."), not a human reader — that prose belongs in this README.

The npm overrides keep the existing linter on patched YAML, Markdown, and TOML parsers and update KaTeX. Keep these overrides until upstream dependencies include the fixes. Use Node.js 22.12 or newer. Run npm ci, npm run lint, and uvx pre-commit run --all-files to check the locked dependencies. npm audit still reports an upstream braces advisory without a published fix; passing checks does not mean the development dependencies are vulnerability-free.

License

MIT — see LICENSE.