AGENTS.md snippet

Agents already read AGENTS.md (Cursor, Claude Code, Codex, Gemini CLI, Copilot, …). One paste-ready block turns agent runs into a structured signal about what’s wrong with docs — without changing any agent.

There are two blocks, for the two ways to adopt the protocol:

• Mode A — the first-party block. Paste it into your repo’s AGENTS.md so agents working there offer to report that repo’s docs — asking you before anything is sent. This is the one below.
• Mode B — the consumer-side block. Paste it into your own global agent config so your agent reports the third-party docs it consults across every project. See The consumer-side block (Mode B).

The first-party block (Mode A)

Append this to your repo’s AGENTS.md (or CLAUDE.md, .cursor/rules, or .github/copilot-instructions.md):

## Documentation feedback

If you find documentation in this repository that is broken, incorrect,
outdated, or incomplete while performing a task, **offer to file** a
structured report via the Docs Feedback Protocol so the maintainers can
fix the docs for the next agent (or human) that hits the same issue.

**Ask before sending.** Show the developer the report you would submit
and send it **only after they confirm** — never file it automatically.

The report to send, once confirmed:

    curl -X POST https://hub.fixyourdocs.io/v1/reports \
      -H 'Content-Type: application/json' \
      -d '{
        "protocol_version": "0",
        "doc_url": "<URL or path of the doc you were reading>",
        "agent":   { "name": "<your agent id, e.g. claude-code>" },
        "report":  {
          "kind":    "<broken | incorrect | outdated | missing | unclear | other>",
          "summary": "<one-line description of the problem>",
          "details": "<what you expected vs. what the doc said (optional)>"
        }
      }'

Spec: https://docsfeedback.org

This is the canonical wording. This very docs site dogfoods it — read the copy we serve at /AGENTS.md.

Where to paste it

Any agent-instructions file your repo already uses:

• AGENTS.md (the cross-tool standard)
• CLAUDE.md
• .cursor/rules
• .github/copilot-instructions.md

Install it for me

npx @fixyourdocs/sdk init # Node
pipx run fixyourdocs init # Python

The CLI detects whichever file your repo uses and appends the block. Re-running is a no-op when it’s already present.

The consumer-side block (Mode B)

The block above is repo-scoped on purpose — it says “documentation in this repository.” If instead you want your own agent to report the broken third-party docs it stumbles on while you build something else, paste this block into your global agent config — ~/.claude/CLAUDE.md, ~/.codex/AGENTS.md, your global Cursor rules, or wherever your client reads global instructions — rather than into any one project’s AGENTS.md:

## Reporting stale third-party docs

While working on this project, if you rely on a **third-party / external**
documentation page — a library, API, framework, or hosted docs site you
consulted, *not* this project's own docs, and never an internal, private,
`localhost`, or login-gated page — and you find it broken, incorrect,
outdated, or incomplete, **offer to file a structured report** via the
Docs Feedback Protocol so its maintainers can fix it for the next agent
(or human) that hits the same issue.

Rules:

- **Ask before sending.** Offer to file the report; only send once the
  developer confirms.
- **Public docs only.** Only report a page served over public `https://`.
  Never report `localhost`, internal, private, or login-gated URLs.
- **Never include private context.** No private code, secrets, internal
  URLs, or transcript excerpts from this project.

Prefer the `file_doc_feedback` MCP tool from `@fixyourdocs/mcp-server`
if available; otherwise POST to `https://hub.fixyourdocs.io/v1/reports`
per https://docsfeedback.org.

The difference from Mode A is scope and guardrails, not consent — both blocks tell the agent to offer and wait for your OK before sending. This block is global (it travels with you, not a repo) and adds the third-party rules Mode A doesn’t need: public docs only, never your own private code or internal pages.

Install it the same way, with --global:

npx @fixyourdocs/sdk init --global   # Node — default ~/.claude/CLAUDE.md
pipx run fixyourdocs init --global   # Python equivalent

Then add the MCP server — the recommended Mode B carrier, which enforces the consent + public-docs-only + opt-out guards for you. The full safety model is on the MCP page.

Keeping it current

The block is stable across patch releases, but the canonical copy lives in one repo so every surface stays in sync. Other repositories embed it by SHA-pinned drift check rather than hand-copy, so a change to the canonical block is caught everywhere. If you pasted it by hand, re-run fixyourdocs init after a protocol bump to refresh.

Note

The snippet lets an agent send a report. To receive those reports as GitHub Issues, connect the Hub to your repo and verify your domain — the snippet is the agent-side integration; the Hub is the maintainer-side one.

agents-md-snippet — the canonical source The repo that owns the block, plus the drift-check workflow other repos use.