What is a Playbook?

A Playbook is the complete operating environment for an AI agent - everything it needs to work effectively, all in one portable package. Think of it as an AI's "work profile" that travels with it across any platform.

The Problem Playbooks Solve

When you use AI assistants across different platforms (ChatGPT, Claude, Gemini Gems/Gem agents, local LLMs), you face these challenges:

• Knowledge fragmentation - Each platform has its own memory and context
• Repeated setup - Recreating system prompts and configurations everywhere
• Platform lock-in - Your AI's accumulated knowledge is trapped in one service
• No portability - Switching platforms means starting over

AgentPlaybooks solves this by providing a platform-independent vault that any AI can access.

Playbook Components

A Playbook combines the elements that together define an AI agent's complete working environment:

1. Persona - Personality & Style

The agent's base personality, communication style, and system prompt. This defines HOW the agent behaves and responds.

# Persona Example

You are a senior software architect with 15 years of experience.
You:
- Write clean, well-documented code
- Explain complex concepts simply
- Ask clarifying questions before making assumptions
- Prefer simplicity over cleverness

Use cases:

• Consistent brand voice across all AI interactions
• Role-specific behavior (coder, writer, analyst)
• Custom interaction styles (formal, casual, technical)

2. Project Instructions - How This Project Works

The always-on operating rules of one project or workspace: build commands, conventions, things not to touch. This is the content local agent tools keep in AGENTS.md or CLAUDE.md, and every session loads it in full.

# Project instructions

- Use pnpm, never npm.
- Run the test suite before committing.
- Do not edit anything under `/legacy` without asking.

Instructions and the persona are deliberately separate fields. The persona is who the agent is and travels with you between projects; instructions are how this project works and stay with the project. A runtime that needs one system prompt composes them persona-first.

Unlike skills, instructions are never selected on demand — they are always in context, which is why they belong in their own slot rather than in a skill named "main".

Use cases:

• Repository conventions and build commands
• Review and release rules a whole team shares
• Guardrails ("never touch production data")

3. Skills - Knowledge & Capabilities

Portable SKILL.md instructions and knowledge the agent can load. Skills describe HOW to approach a task; executable network operations belong to MCP/OpenAPI integrations.

{
  "name": "Code review guide",
  "description": "Use when reviewing code for correctness and security",
  "content": "# Code review\nUse this checklist...",
  "licence": "MIT",
  "priority": 80
}

Use cases:

• Structured task definitions
• Company-specific procedures
• Domain expertise (legal, medical, technical)
• Bundled files — scripts, references, templates — that travel with the skill
• Demonstrations: recordings of the task being performed, in execution order, for agents that learn by watching

4. MCP Servers - Tools & Integrations

External tools and APIs the agent can access via the Model Context Protocol. MCP provides a standardized way for AI to use external tools.

Important: AgentPlaybooks discovers and executes configured MCP/OpenAPI operations through its federated proxy. The agent only needs the playbook MCP endpoint.

{
  "name": "database_tools",
  "tools": [
    {
      "name": "query_database",
      "description": "Execute a read-only SQL query",
      "inputSchema": {
        "type": "object",
        "properties": {
          "query": { "type": "string" },
          "database": { "type": "string" }
        }
      }
    }
  ],
  "resources": [
    {
      "uri": "db://schema",
      "name": "Database Schema",
      "mimeType": "application/json"
    }
  ]
}

Use cases:

• Database access
• File system operations
• API integrations
• Custom tool definitions

5. Canvas - Working Documents

Structured markdown documents that serve as the agent's persistent workspace. Notes, drafts, project files - documents the agent can read and write across sessions.

# Project: Website Redesign

## Status
In Progress - Phase 2

## Key Decisions
- Using Next.js 16 with App Router
- Tailwind CSS for styling
- Supabase for backend

## Open Questions
- [ ] Confirm color palette with design team
- [ ] Review performance requirements

## Notes
2024-01-15: Initial meeting with stakeholders...

Use cases:

• Project documentation
• Meeting notes and summaries
• Draft documents
• Research notes
• Persistent scratchpads

6. Memory - Persistent Context

Key-value storage for remembering facts, preferences, and state across sessions. The agent's long-term memory for structured data.

{
  "user_preferences": {
    "code_style": "functional",
    "preferred_language": "TypeScript",
    "verbosity": "concise"
  },
  "project_context": {
    "name": "AgentPlaybooks",
    "stack": ["Next.js", "Supabase", "Cloudflare"],
    "last_task": "Implemented i18n support"
  }
}

Use cases:

• User preferences
• Session state
• Accumulated facts
• Configuration data

7. Secrets - Secure Credentials

Encrypted key-value vault for storing API keys, passwords, and tokens. Values are AES-256-GCM encrypted. By default, they are never exposed in plaintext to the AI agents (Proxy Only). Instead, agents use the use_secret MCP tool to inject these credentials into HTTP requests server-side. Users can optionally enable API Key Reveal on a per-secret basis if an agent explicitly requires the raw value.

{
  "OPENAI_API_KEY": "sk-...",
  "DB_PASSWORD": "super-secret-password"
}

Use cases:

• API authentication (OpenAI, Anthropic, GitHub)
• Database connection strings
• Webhook signing secrets
• Third-party service tokens

How It All Fits Together

┌─────────────────────────────────────────────────────────────┐
│                        PLAYBOOK                             │
│  "My Coding Assistant"                                      │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐         │
│  │   PERSONA   │  │   SKILLS    │  │ MCP SERVERS │         │
│  │             │  │             │  │             │         │
│  │ How I act   │  │ What I know │  │ Tools I use │         │
│  │ & respond   │  │ & can do    │  │ & connect   │         │
│  └─────────────┘  └─────────────┘  └─────────────┘         │
│                                                             │
│  ┌───────────────────────────────────────────────────────┐  │
│  │                     INSTRUCTIONS                      │  │
│  │                                                       │  │
│  │     Always-on rules for THIS project (AGENTS.md)      │  │
│  └───────────────────────────────────────────────────────┘  │
│                                                             │
│  ┌─────────────────────────┐  ┌─────────────────────────┐  │
│  │         CANVAS          │  │         MEMORY          │  │
│  │                         │  │                         │  │
│  │   Working documents     │  │   Persistent facts      │  │
│  │   Notes, drafts, files  │  │   Key-value storage     │  │
│  └─────────────────────────┘  └─────────────────────────┘  │
│                                                             │
│  ┌───────────────────────────────────────────────────────┐  │
│  │                       SECRETS                         │  │
│  │                                                       │  │
│  │      Encrypted keys, tokens, and credentials          │  │
│  └───────────────────────────────────────────────────────┘  │
│                                                             │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
              Works on ANY AI platform:
         ChatGPT • Claude • Gemini • Local LLMs
              • Custom Agents • Future Robots

Accessing Your Playbook

Once published, your playbook is available in multiple formats:

Creating Your First Playbook

• Sign up at apbks.com
• Create a playbook from the dashboard
• Add a persona - Define your AI's personality
• Add skills - Define what it can do
• Publish - Make it accessible
• Connect - Give the URL to your AI

See Getting Started for detailed instructions.

Working With a Team

The owner of a playbook can invite signed-in people as editors from the Sharing tab. An accepted playbook appears on the editor's dashboard with a Shared badge and can be edited alongside their own playbooks.

Editors can work on the playbook's name, description, configuration, persona, skills, MCP servers, attachments, canvas, and memory. The owner retains exclusive control over visibility, collaborators, playbook API keys, secrets, and deletion.

Human collaboration is deliberately separate from agent access. Do not send an Admin or Coworker API key to a person as a substitute for an invitation: API keys are bearer credentials, while an editor invitation is bound to the account that accepts it and can be revoked independently.

See Team Collaboration for the invitation flow, permission matrix, and security model.

Best Practices

Personas

• Be specific about communication style
• Include examples of good responses
• Define what the AI should NOT do

Skills

• Use clear, descriptive names
• Include parameter descriptions
• Add examples for complex skills

Canvas

• Use consistent document structure
• Include timestamps for notes
• Organize with clear headings

Memory

• Use descriptive key names
• Keep values structured (JSON)
• Document what each key stores

Next Steps

• Platform Integrations - Connect to ChatGPT, Claude, Gemini
• MCP Integration - Deep dive into Model Context Protocol
• API Reference - Full endpoint documentation