# PlaybookOps as your agents' context

> Use PlaybookOps as the context repository for your AI agents, in place of a Git repo full of Markdown files.

A lot of teams keep their agents' context in a Git repository of Markdown: an `AGENTS.md`, runbooks, style guides, product notes, how-we-work docs. It's a good start. Then the gaps show:

- Only people comfortable with Git can fix a wrong instruction, so the docs drift away from how the team really works.
- Every agent loads the same files into its prompt, whether they're relevant or not, and the prompt grows until it's too big.
- Nothing says who owns a document, whether it's still right, or who to ask when it's silent.
- Everyone who can read the repo can read all of it.

PlaybookOps keeps what works about that setup, Markdown in and Markdown out, and adds the rest. Anyone on the team can edit in the app. Agents find what they need by meaning instead of loading everything. Every change is versioned, documents have owners and reviewers, and each agent sees only what its key's owner can see.

## What maps to what

| In a docs repo | In PlaybookOps |
| --- | --- |
| A top-level folder, like `runbooks/` | A playbook |
| A subfolder | A folder in the playbook |
| A `.md` file | A document. You write it in [Markdown](https://developers.playbookops.ai/guides/markdown) and read it back as Markdown. |
| Front matter: `title`, `tags`, `type` | The document's title, `tags` and `document_type` |
| A commit | A new version in the document's history, under the name of whoever made it |
| A merge conflict | A `409 version_conflict` when you send a stale `base_version` |
| `CODEOWNERS` | The document's owner and reviewers. `who_knows` finds the right person for a topic. |
| `grep` | `search_knowledge` searches by meaning; `list_content` by title |
| `git pull` | `GET /v1/document-changes`: what changed, moved or was deleted since a time |
| A file path | An MCP resource address, like `playbookops://documents/{id}` |
| Pull request review | Documents start as drafts, and a body change asks reviewers to review again |
| Who can clone the repo | Who can open each playbook, plus the key's scopes |

## Four ways agents use it

Most agents combine two or three of these.

| Pattern | How | Use it when |
| --- | --- | --- |
| **Look it up** | `search_knowledge`, then `read_document` for the documents that matter, then cite their links | The default. It scales to thousands of documents and keeps prompts small. Each search uses 1 AI credit. |
| **Pin a few documents** | Read a handful of documents by id when the agent starts, and put them in its instructions | Rules the agent must always follow, like coding conventions or a tone of voice. This is your `AGENTS.md`. Reads are free. |
| **Mirror to files** | Copy a playbook into a folder of `.md` files and refresh what changed | Tools that only read files, offline or CI runs, or your own search index |
| **Write back** | `update_document` with section edits and `base_version` | Agents that learn something worth keeping: a fixed runbook step, a new FAQ, an incident timeline |

## Cookbooks

- [Move a docs repo into PlaybookOps](https://developers.playbookops.ai/cookbooks/import-a-docs-repo): A script that imports a folder of Markdown files into playbooks and folders, keeps tags and links, and is safe to run again.
- [Give coding agents your playbooks](https://developers.playbookops.ai/cookbooks/coding-agents): Claude Code, Cursor and Codex look things up in PlaybookOps instead of a docs folder.
- [Answer with citations](https://developers.playbookops.ai/cookbooks/grounded-answers): An agent that answers only from your documents and links what it used, with Claude, OpenAI or your own loop.
- [Mirror a playbook to files](https://developers.playbookops.ai/cookbooks/sync-to-files): Keep a folder of Markdown in step with a playbook, fetching only what changed.
- [Have agents keep docs current](https://developers.playbookops.ai/cookbooks/keep-docs-current): Agents that fix a runbook step or log what they learned, without overwriting anyone.

## Write documents agents can use

Agents read your documents the way a new starter would, only faster and more literally. A few habits make a big difference:

- **One topic per document, titled as what it answers.** "How we deploy the backend" is found by search and understood at a glance. "Deploy notes v2" isn't.
- **Headings that name things.** Search returns passages, and edits target headings, so `## Rolling back` beats `## Step 4`.
- **The rule first, then the reason.** "Never run migrations on Fridays. Weekend on-call is one person." The rule survives being quoted out of context.
- **Say who to ask.** A [mention](https://developers.playbookops.ai/guides/markdown#mentions) of the owner gives agents and people somewhere to go when the document is silent.
- **Keep documents under 24,000 characters.** Longer ones come back cut short unless the agent asks for `full=true`, and long documents are harder to search well. Split them by topic.
- **A playbook for agent instructions.** Keep the always-on rules, the ones you'd put in `AGENTS.md`, in their own playbook so they're easy to pin and easy to review.

> **A key for each agent**
> Keys act as the person who made them, so an agent sees exactly what its key's owner can open. For a shared agent, have a dedicated account (like `agents@yourcompany.com`) make the key, and give that account access to just the playbooks the agent should use. See [building agents](https://developers.playbookops.ai/agents) for more.
