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 repoIn PlaybookOps
A top-level folder, like runbooks/A playbook
A subfolderA folder in the playbook
A .md fileA document. You write it in Markdown and read it back as Markdown.
Front matter: title, tags, typeThe document's title, tags and document_type
A commitA new version in the document's history, under the name of whoever made it
A merge conflictA 409 version_conflict when you send a stale base_version
CODEOWNERSThe document's owner and reviewers. who_knows finds the right person for a topic.
grepsearch_knowledge searches by meaning; list_content by title
git pullGET /v1/document-changes: what changed, moved or was deleted since a time
A file pathAn MCP resource address, like playbookops://documents/{id}
Pull request reviewDocuments start as drafts, and a body change asks reviewers to review again
Who can clone the repoWho can open each playbook, plus the key's scopes

Four ways agents use it

Most agents combine two or three of these.

PatternHowUse it when
Look it upsearch_knowledge, then read_document for the documents that matter, then cite their linksThe default. It scales to thousands of documents and keeps prompts small. Each search uses 1 AI credit.
Pin a few documentsRead a handful of documents by id when the agent starts, and put them in its instructionsRules the agent must always follow, like coding conventions or a tone of voice. This is your AGENTS.md. Reads are free.
Mirror to filesCopy a playbook into a folder of .md files and refresh what changedTools that only read files, offline or CI runs, or your own search index
Write backupdate_document with section edits and base_versionAgents that learn something worth keeping: a fixed runbook step, a new FAQ, an incident timeline

Cookbooks

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 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 for more.