Author Playbook

Author a PLAYBOOK.md (AIP-12)

Use this skill when the user asks to capture, codify, or evolve a persona adjustment for an operator — a small overlay fragment that rides on top of the operator's base persona without rewriting it. The skill produces a valid AIP-12 PLAYBOOK.md with a single overlay fragment, plus an entry exposing the standard definePlaybook signature.

Playbooks are not lessons. A lesson tells the agent do X in a single turn (AIP-11). A playbook is part of the agent — it modifies persona at session compose time. Lessons retrieve; playbooks weave.

When to use

• "Whenever the agent helps with X, it should phrase Y like Z."
• "I noticed the agent rushes through crisis flags — capture the slower behaviour as a reusable overlay."
• "Promote this shadow playbook to active."
• "The reflection loop produced a delta — turn it into a playbook file."

When NOT to use

• The change is a single-turn instruction → use the AIP-11 lesson-authoring skill instead.
• The change rewrites the whole operator persona → that's an AIP-9 operator edit, not a playbook overlay.
• The user wants to invoke an existing playbook — no authoring needed; the runtime weaves it automatically.

Process

Eight steps. Skipping the lock-check or shadow gate is how self-improving prompts go off-mission silently — every step matters.

1. Fix identity and scope

• Pick slug: kebab-case, descriptive of the behaviour the overlay installs (slow-pace-on-crisis, not playbook-1).
• Write title: one sentence — what this overlay does.
• Decide targets[]: which operators / roles / skills / runtimes the overlay should weave into. Use the narrowest scope the insight justifies. Globs are allowed (operator/*) but every glob is a chance to misfire — prefer concrete refs.

2. Pick kind

Two kinds available — pick the most specific that fits:

Reject these anti-decompositions:

• A single playbook that mixes two unrelated adjustments (split into two — credit assignment depends on one-fragment-one-idea).
• A block-replacement that targets a block the persona doesn't expose as replaceable (host refuses at apply time).
• An overlay that paraphrases the base persona instead of adding to it (drift surface — keep overlays additive).

3. Declare locked traits

This is the safety contract. Walk the operator's locked-trait list and ask:

• Which traits is this overlay intended to leave alone?
• Could the body be misread as touching any of them?

Populate lock_check[] with every trait the author commits not to modify. Common ids: warmth, honesty, voice-register, safety-boundary, mission, identity.

lock_check is intent. The runtime enforces its own list independently — overlays that violate either are non-conforming. Stricter wins. When in doubt, copy the operator's full lock list: declaring more locked traits never hurts; declaring fewer means a faulty evolution loop has one less guardrail.

4. Write the overlay body

Markdown, addressed to the operator, weave-ready. Rules:

• One concrete behaviour per playbook. If you wrote "and also…", split into two playbooks.
• Never refer to being a playbook ("this overlay tells you to…") — the body is just persona text. Overlay framing is metadata, not prose.
• No chain-of-thought leakage to user-facing output. The body is prompt material, not narration.
• Quote concrete examples where useful (input → behaviour). The LLM reads these.
• Keep it short. Long overlays compete with the base persona for attention; aim for one paragraph.

5. Provenance — evidence[]

Every playbook MUST trace back to the run, conversation, work-item, or reflection that produced it:

evidence:
  - kind: reflection
    ref: reflections/2026-04-27/companion-pacing.md
    note:
      3 of 5 crisis-flagged sessions showed agent rushing past safety
      acknowledgement

Why this matters: when a playbook stops working (or starts misfiring), the evidence pointer is the only way to retrace authorship. Untraceable playbooks are a maintenance tarpit.

6. Status, priority, TTL

7. Compose the manifest + entry

Author PLAYBOOK.md:

---
schema: playbooks/v1
slug: <kebab-id>
title: <one sentence>
targets:
  - kind: <operator|role|skill|runtime>
    ref: <slug-or-glob>
kind: <overlay|block-replacement>
priority: 50
lock_check: [<trait-id>, …]
evidence:
  - { kind: <run|conversation|work-item|reflection>, ref: <…>, note: <…> }
status: shadow
ttl: <PnD> # optional
supersedes: [<slug>] # optional
metadata: {}
---

# <title>

<the overlay fragment — one paragraph of prompt material>

Author playbook.ts exposing the canonical signature:

import { definePlaybook } from "<host-runtime>"

export default definePlaybook({
  slug: "slow-pace-on-crisis",
  title: "Slow pacing when the user is crisis-flagged.",
  targets: [{ kind: "role", ref: "companion" }],
  kind: "overlay",
  priority: 60,
  lockCheck: ["warmth", "honesty", "safety-boundary"],
  evidence: [
    {
      kind: "reflection",
      ref: "reflections/2026-04-27/companion-pacing.md",
      note: "3 of 5 crisis sessions showed agent rushing past acknowledgement",
    },
  ],
  status: "shadow",
  body: `
When the active user is flagged as in crisis, prefer one question at a
time over a multi-question check-in. Acknowledge feelings verbally
before offering any next step. Do not list bullet points of advice —
read one back, ask if it lands, then continue.
  `.trim(),
})

Mirror the manifest exactly. Drift between manifest and entry is a spec bug.

8. Validate

Validate the manifest against ./PLAYBOOK.schema.json:

npx ajv validate -s ./PLAYBOOK.schema.json -d ./PLAYBOOK.md

Fix every error before declaring success. Specifically check:

• slug is kebab-case and unique within the playbooks folder.
• Every targets[].ref resolves (or is an explicit glob).
• lock_check covers every trait the operator marks locked, or the author has explicitly accepted the gap.
• status is shadow (new) or carries an evidence entry of kind reflection justifying promotion.
• Body contains no instruction that paraphrases or contradicts a locked trait.

The reflective delta contract

This skill also handles the second-most-common request: codify a delta the reflection loop produced. Reflective deltas are append-only; the current playbook set is the materialised view.

When a delta arrives:

1. Read the delta. It carries a candidate body, target scope, and the runs that motivated it.
2. Check the lock list. If the candidate body touches any locked trait of any in-scope operator, discard it — do not write the file. Surface the rejection with the trait id and a short excerpt.
3. Write the playbook at status: shadow. Never auto-promote. Shadow status means "the runtime computes this overlay but does not weave it" — the system accumulates evidence without changing behaviour.
4. Append a history entry describing the delta source (run id or reflection id, timestamp, summary). The history is the audit-trail; it MUST grow append-only.
5. Stop. Promotion to active is a separate decision. This skill does not promote. Promotion goes through the host's gate (A/B, scorer delta, or AIP-7 governance for high-impact overlays).

A delta whose body would replace the whole persona is not a delta — it's a persona rewrite. Refuse it. The point of AIP-12 is to forbid monolithic rewrites in favour of additive overlays.

Output

Produce two files in the chosen folder:

<folder>/
  PLAYBOOK.md      # the manifest
  playbook.ts      # (or playbook.py / …) — the entry exposing definePlaybook

Reply to the user with:

1. The folder you wrote to.
2. The targets[] and lock_check[] so they can verify the scope and safety contract before activation.
3. The current status (almost always shadow) and what the promotion gate is (A/B, scorer delta, or governance).
4. Open assumptions: defaults you guessed (priority, TTL, the exact phrasing of the body) the user might want to override.

Do NOT promote the playbook to active yourself — that's the host's gate. Authoring ends with the file written and the index regenerated.

See also

• AIP-12 — PLAYBOOK.md spec
• AIP-9 — agentoperators/v1 — operator personas playbooks weave into
• AIP-7 — governance, approval, audit — high-impact promotion path
• AIP-11 — agentlearning/v1 — single-turn lessons (different layer)
• ./ADAPTER.md — implementer's guide for hosts
• ./EXAMPLES.md — reference PLAYBOOK.md files (minimal overlay, scoped, locked, evolved, composed, retired)