Add an agent primer, AGENTS.md, skill.md and prompt cards

[methodofaction]

Stacked on #69 (CLI install path); GitHub will retarget this to main once that merges.

Why

Coding agents are now a large share of the readers of these docs, and they keep tripping over the same GOBL conventions before they get anything useful done: writing totals by hand, percentages without the % sign, uppercase keys, a missing $regime, invented extension codes, hand-assembled preceding blocks. This PR gives them a dedicated entry point, mirroring what docs.invopop.com now has (invopop/docs.invopop.com#585), and fixes two stale statements found while verifying.

What's new

• /llms primer (llms.mdx, Overview group after the introduction): the model in one minute, how to read the generated schema, regime and addon pages, the tooling that validates for you (public API, CLI, MCP, Go, others), twelve rules each checked against gobl.dev v0.500.15 / core v0.504.0, a five-command CLI walkthrough, five copyable prompts, a "where to look" table and a vocabulary map. The "what build returns" block is the CLI's exact output for the "what you send" block.
• AGENTS.md at the repo root. Mintlify serves root Markdown verbatim, so this publishes at docs.gobl.org/AGENTS.md as the condensed version integrators paste into their own agent instructions.
• skill.md at the repo root, overriding Mintlify's auto-generated skill for npx skills add https://docs.gobl.org, with agentskills.io frontmatter.
• <Prompt> cards on the CLI, invoices and builder quick starts, the invoicing use case, the API introduction, the MCP page, the addon and regime overviews and the validation page.
• docs.json: the nav entry and a contextual menu (copy, ChatGPT, Claude, Perplexity, MCP, Cursor, VS Code), matching docs.invopop.com.
• A card on the introduction page and a README section describing the agent-facing files.

Corrections

• use-cases/invoicing.mdx said Spain "doesn't have support for credit-notes". The ES regime accepts credit-note, corrective and debit-note and maps credit notes to rectification by differences; reworded and pointed at the regime page's Correction Definitions.
• The same page said the reverse-charge tag "will automatically include a special note" without saying where. It lands in tax.notes, verified.

Verified behaviours worth knowing

All of these are stated on the new pages and were confirmed with the CLI: "percent": "21" is read as 2100% with no error; "cat": "vat" fails with invalid-category; no $regime and no supplier tax_id gives currency: missing or invalid; unknown $tags fail; VERI*FACTU requires a customer unless $tags: ["simplified"] (which also sets doc type F2); a GR tax identity normalises to EL; validate on a partial document fails; editing a signed envelope fails with GOBL-ENVELOPE-11; Envelope.Insert in Go calculates but does not validate.

Reviewer notes

• mint broken-links reports only two pre-existing broken links in generator-owned pages (draft-0/org/identity.mdx and draft-0/org/item.mdx link to /draft-0/l10n/i_s_o_country_code; the page is iso_country_code). toSnakeCase in cmd/generate/schemas.go splits the ISO acronym letter by letter; worth a separate fix in the generator.
• skill.md replaces the generated skill; deleting the file restores Mintlify's version.
• Rendered locally with mint dev; no compile errors.

🤖 Generated with Claude Code

[Copilot]

🟡 Changes recommended

A couple of newly added/updated doc lines are internally inconsistent with the PR’s own guidance (notably around $tags usage and gobl correct input), which could mislead agent readers.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

Adds an agent-focused entry point to the GOBL documentation set (primer, condensed agent instructions, and an explicit agent-skill definition), and embeds copyable <Prompt> cards across key pages so coding agents reliably follow the “build-first, minimal-input” workflow and look up authoritative schema/regime/addon rules.

Changes:

• Introduce a comprehensive /llms primer (llms.mdx) plus a condensed repo-root AGENTS.md, and an explicit skill.md for agent-skill installers.
• Add <Prompt> cards to multiple quick starts and reference overviews to guide common agent workflows (install CLI, use API/MCP, map models, debug validation).
• Update navigation (docs.json) and add an intro card and README section pointing maintainers/readers to the agent-facing docs.

File summaries

File	Description
use-cases/invoicing.mdx	Adds an agent prompt card and updates guidance around invoice types/scenarios.
skill.md	Adds a custom agent-skill definition (frontmatter + usage guidance).
regimes/overview.mdx	Adds a prompt card to guide agents through regime requirements.
README.md	Documents the purpose and maintenance expectations of agent-facing files.
quick-start/invoices.mdx	Adds a prompt card to adapt the invoice quick start to other regimes.
quick-start/cli.mdx	Adds a prompt card to guide agents through CLI install + walkthrough execution.
quick-start/builder.mdx	Adds a prompt card offering a non-browser workflow alternative.
overview/validation.mdx	Adds a prompt card to help agents interpret and fix validation faults.
llms.mdx	Adds the new long-form agent primer, rules, examples, and copyable prompts.
introduction.mdx	Adds a card linking to the new agent primer page.
docs.json	Adds llms to the nav and introduces the contextual menu options.
api/mcp.mdx	Adds a prompt card for connecting to and exercising the GOBL MCP server.
api/introduction.mdx	Adds a prompt card for implementing a typed API client in a target language.
AGENTS.md	Adds the condensed “paste into agent instructions” rule set and examples.
addons/overview.mdx	Adds a prompt card to help agents choose addons and enumerate required extensions.

Review details

• Files reviewed: 15/15 changed files
• Comments generated: 3
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.