{"id":50965353,"url":"https://github.com/fmind/agent-docs","last_synced_at":"2026-06-18T19:33:22.222Z","repository":{"id":359750317,"uuid":"1226551624","full_name":"fmind/agent-docs","owner":"fmind","description":"Project docs that answer locally before the web — file-based Agent Skills for Claude Code, Gemini CLI, GitHub Copilot, and OpenCode.","archived":false,"fork":false,"pushed_at":"2026-05-31T17:32:34.000Z","size":414,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-06-11T15:41:46.960Z","etag":null,"topics":["agent-skills","agy","ai-agents","ai-tooling","antigravity","antigravity-cli","claude-code","coding-agents","developer-tools","documentation","gemini-cli","gemini-cli-extension","github-copilot","llm-agents","opencode"],"latest_commit_sha":null,"homepage":"https://fmind.github.io/agent-docs/","language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fmind.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-05-01T14:46:38.000Z","updated_at":"2026-05-31T17:32:38.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/fmind/agent-docs","commit_stats":null,"previous_names":["fmind/agent-docs"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/fmind/agent-docs","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fmind%2Fagent-docs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fmind%2Fagent-docs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fmind%2Fagent-docs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fmind%2Fagent-docs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fmind","download_url":"https://codeload.github.com/fmind/agent-docs/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fmind%2Fagent-docs/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34505420,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-18T02:00:06.871Z","response_time":128,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-skills","agy","ai-agents","ai-tooling","antigravity","antigravity-cli","claude-code","coding-agents","developer-tools","documentation","gemini-cli","gemini-cli-extension","github-copilot","llm-agents","opencode"],"created_at":"2026-06-18T19:33:21.313Z","updated_at":"2026-06-18T19:33:22.217Z","avatar_url":"https://github.com/fmind.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"# Agent Docs\n\n[![CI](https://github.com/fmind/agent-docs/actions/workflows/ci.yml/badge.svg)](https://github.com/fmind/agent-docs/actions/workflows/ci.yml) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE) [![Claude Code](https://img.shields.io/badge/Claude%20Code-supported-D97706)](https://github.com/anthropics/claude-code) [![Gemini CLI](https://img.shields.io/badge/Gemini%20CLI-supported-4285F4)](https://github.com/google-gemini/gemini-cli) [![GitHub Copilot](https://img.shields.io/badge/GitHub%20Copilot-supported-181717)](https://github.com/features/copilot) [![OpenCode](https://img.shields.io/badge/OpenCode-supported-059669)](https://opencode.ai)\n\n![agent-docs — Project docs that answer locally before the web](image.jpeg)\n\n\u003e **Project docs that answer locally before the web.**\n\n**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.\n\n**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.\n\n## Why this exists\n\nAgents waste a lot of turns web-searching for things the project already commits to.\n\n- Web searches are slow, lossy, and often grab the wrong version of a doc.\n- The \"right\" answer for a given repo is narrower than upstream — flags actually used, patterns this project follows, the canonical URL the team trusts.\n- Without curation, two agents researching the same topic on the same repo come back with two different answers.\n\nAgent Docs flips the default: the project ships a tiny, dated reference set under `.agents/docs/`, and agents read it **before** reaching for the web.\n\n## What you get\n\n- **Local-first lookups.** `use-agent-docs` teaches the agent to consult `.agents/docs/INDEX.md` before web research — fewer round-trips, more reproducible answers.\n- **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.\n- **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.\n- **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.\n- **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 `\u003e ⚠ Stale` banner until the next successful run.\n- **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.\n- **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.\n- **Install once, use anywhere.** The same `skills/` tree drives Claude Code, Gemini CLI, GitHub Copilot, and OpenCode.\n\n## The three skills\n\n- **`/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.\n- **`/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.\n- **`/refresh-agent-docs`** — Re-verify entries against upstream: repair dead links in the documentation map, update drifted snippets, bump `last_verified` dates, insert a `\u003e ⚠ 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.\n\nThe three pair into a small loop:\n\n```text\ngather → use → (drift detected) → refresh → use → ...\n       ↘ (depth needed) → deepen ↗\n```\n\n## Walkthrough\n\n```text\n$ /gather-agent-docs\n  → inspects the project (package manifests, CI configs, IaC files), picks 3–8 topics\n  → fetches one upstream nav source per topic (sidebar / docs home / sitemap)\n  → writes .agents/docs/\u003ctopic\u003e/DOC.md with frontmatter, summary, key concepts, documentation map\n  → writes .agents/docs/INDEX.md with one dated line per topic\n  → \"Seeded 5 topics under .agents/docs/. Review the diff before committing.\"\n\n$ /use-agent-docs       # invoked implicitly whenever the agent is about to web-search\n  → reads INDEX.md, opens DOC.md, scans the documentation map for the right entry\n  → fetches the matching upstream URL on demand (one hop, not N web searches)\n  → optionally backfills a paste-ready snippet to DOC.md's Patterns section if the user opts in\n\n$ /gather-agent-docs deepen gemini-cli\n  → revisits gemini-cli's DOC.md; captures up to 5 high-frequency snippets (T2) with inline _Source: …_\n  → adds a Patterns section, bumps last_verified\n\n$ /refresh-agent-docs gemini-cli\n  → tries the cheap path first: matches upstream_commit / scans sources.changelog since last_verified\n  → falls through to a link-rot scan of the documentation map; repairs moved/renamed pages\n  → re-verifies any captured snippets against their inline _Source: …_ links\n  → \"gemini-cli: links repaired (DOC.md), unchanged (HOOKS.md, smart path).\"\n```\n\n## See it in action\n\n[`examples/`](./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/`.\n\n## Install\n\n### Claude Code\n\n```text\n/plugin marketplace add fmind/agent-docs\n/plugin install agent-docs@agent-docs\n```\n\nFor local development, point the marketplace at a clone:\n\n```text\n/plugin marketplace add /path/to/agent-docs\n/plugin install agent-docs@agent-docs\n```\n\n### Gemini CLI\n\n```bash\ngemini extensions install fmind/agent-docs\n```\n\nFor local development (live-link, edits reload on next session):\n\n```bash\ngemini extensions link /path/to/agent-docs\n```\n\n### Antigravity CLI\n\n```bash\nagy plugin install https://github.com/fmind/agent-docs\n```\n\nFor local development (live-link, edits reload on next session):\n\n```bash\nagy plugin install /path/to/agent-docs\n```\n\n### OpenCode\n\nTo 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.\n\n### GitHub Copilot\n\nCopilot CLI:\n\n```bash\ncopilot plugin marketplace add fmind/agent-docs\ncopilot plugin install agent-docs@agent-docs\n```\n\nFor local development, point the marketplace at a clone:\n\n```bash\ncopilot plugin marketplace add /path/to/agent-docs\ncopilot plugin install agent-docs@agent-docs\n```\n\nVS Code — point `chat.pluginLocations` at a local clone:\n\n```jsonc\n// settings.json\n\"chat.pluginLocations\": {\n  \"/path/to/agent-docs\": true\n}\n```\n\n## Reference\n\n### Layout\n\n```text\nagent-docs/\n├── AGENTS.md                          # canonical context — read by Copilot; @-included by CLAUDE.md / GEMINI.md\n├── skills/                            # Agent Skills (open standard)\n│   ├── gather-agent-docs/SKILL.md     # user-facing: seed .agents/docs/\n│   ├── use-agent-docs/SKILL.md        # user-facing: read .agents/docs/ before web research\n│   └── refresh-agent-docs/SKILL.md    # user-facing: re-verify entries against upstream\n├── examples/                          # worked sample of what /gather-agent-docs produces\n├── .claude-plugin/                    # Claude Code plugin manifest + bundled marketplace\n├── gemini-extension.json              # Gemini CLI extension manifest\n├── plugin.json                        # GitHub Copilot manifest\n└── .github/workflows/ci.yml           # lint via pre-commit\n```\n\nIn an end-user project after `/gather-agent-docs`:\n\n```text\n.agents/docs/\n├── INDEX.md                           # one dated entry per topic, pointing to its DOC.md\n└── \u003ctopic\u003e/                           # kebab-case slug (e.g. gemini-cli, cloud-run)\n    ├── DOC.md                         # entry point: summary, key concepts, documentation map, optional patterns\n    └── \u003cSUBTOPIC\u003e.md                  # optional deep dive (e.g. EXTENSIONS.md, HOOKS.md)\n```\n\n`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.\n\n### When to split a subtopic\n\nEach `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 `\u003cSUBTOPIC\u003e.md` when **all** of the following hold:\n\n- The subsystem has its own canonical upstream page(s) — distinct from the topic's overview.\n- The deepened version (with captured snippets) would push past the soft cap.\n- Agents reach for that depth repeatedly in this project, not just hypothetically.\n\nThe 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.\n\n## Contributing\n\nIssues and PRs welcome. Two house rules to keep the skills lean:\n\n- **Skill files have line caps** (see `AGENTS.md` §Conventions) — they load into agent context on every run, so verbosity costs budget.\n- **Voice is imperative.** Skill bodies address the agent (\"Read X, then write Y.\"), not a human reader — that prose belongs in this README.\n\n## License\n\nMIT — see [LICENSE](./LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffmind%2Fagent-docs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffmind%2Fagent-docs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffmind%2Fagent-docs/lists"}