# Agent instruction files

Drop-in instructions that let coding agents integrate nisebookings into your website or app correctly without
re-reading the whole documentation set. They describe the same contract as the guides; where they
disagree, the guides win.

| File | Use it for | How |
|---|---|---|
| [`AGENTS.md`](AGENTS.md) | Any agent that reads AGENTS.md: **OpenAI Codex, Cursor, GitHub Copilot coding agent, VS Code, Windsurf, Gemini CLI, Zed, Aider and others** | Copy it into the root of the project that will integrate the booking service (or merge it into an existing `AGENTS.md` — the nearest file in the directory tree wins). |
| [`claude/nisebookings/SKILL.md`](claude/nisebookings/SKILL.md) | **Claude Code** | Copy the folder to `.claude/skills/nisebookings/` in your project (or `~/.claude/skills/` for all your projects). Claude loads it automatically when a booking task comes up; `/nisebookings` invokes it manually. |
| [`copilot-instructions.md`](copilot-instructions.md) | **GitHub Copilot** (higher priority than AGENTS.md) | Copy to `.github/copilot-instructions.md` in your project. |

Notes, based on the vendors' own documentation (agents.md, code.claude.com/docs/en/skills,
code.visualstudio.com/docs/agent-customization/custom-instructions, docs.github.com, modelcontextprotocol.io):

- **AGENTS.md** is the portable baseline: a plain-Markdown file at the repository root, read
  natively by Codex, Cursor, the Copilot coding agent, VS Code, Gemini CLI and others. In monorepos
  the nearest file to the edited code wins.
- **Claude Code** reads `CLAUDE.md` rather than AGENTS.md; the common bridge is a symlink
  (`ln -s AGENTS.md CLAUDE.md`). A Skill is better than a symlink here: it loads only when the task
  matches, so it costs nothing on unrelated work.
- **VS Code / Copilot** reads AGENTS.md behind the `chat.useAgentsMdFile` setting, and reads
  `.instructions.md` files with `applyTo` globs for path-specific rules. Priority order (lowest to
  highest): organisation < AGENTS.md/CLAUDE.md < `.github/copilot-instructions.md` <
  `.instructions.md` < manual chat instructions.
- **Cursor** reads AGENTS.md natively (`.cursor/rules/*.mdc` still works for path-scoped rules).
- **Codex** reads AGENTS.md natively; MCP servers are configured in `~/.codex/config.toml` under
  `[mcp_servers.<name>]`.

**Operating your account rather than integrating it?** Connect the agent to the hosted MCP server instead
of (or next to) these files: `https://app.nisebookings.com/api/mcp` with a Management API key. Config
for Claude Code (`claude mcp add --transport http`), Codex (`~/.codex/config.toml`, `bearer_token_env_var`),
Cursor (`.cursor/mcp.json`, `${env:…}` in `headers`) and VS Code (`.vscode/mcp.json`, `inputs`) is in
[`../../api/mcp.md`](../../api/mcp.md).

**Need something to test against?** Every file tells the agent to verify on a sandbox:
`POST https://app.nisebookings.com/api/sandbox` (no auth) returns a 24-hour test account with a public
key and an all-scopes API key, no outbound mail and a fake payment page — see
[`../08-sandbox.md`](../08-sandbox.md).

**Your backend needs to know about bookings?** Every file points at [webhooks](../10-webhooks.md)
(signed, retried, deduplicate on `webhook-id`) and at `Idempotency-Key` for safe retries of
`POST bookings`.

These files carry no credentials. Your account's public key is not a secret, but keep it in the host
application's configuration rather than committing it where it is unnecessary.