Epismo
Get Started

Author Your First Playbook

Use when someone has an Epismo account but no Playbook yet, and does not know what to write. Sets up the surface and the Epismo skill, finds the recurring work already living in their environment, filters it to the one thing a single skill cannot carry, writes it with input, output, and harness pinned so a stranger's agent can rerun it, then rehearses it against real past evidence and publishes it on the owner's go-ahead. Ends in one session with a working setup and one published, aliased Playbook — not a library plan.

Quickstart — choose an install route, then say one sentence. macOS or Linux: curl -fsSL https://epismo.ai/install.sh | sh. Windows PowerShell: irm https://epismo.ai/install.ps1 | iex. npm: npm install -g epismo. You can also download native binaries and SHA-256 checksums directly from https://github.com/epismoai/cli/releases. Then run epismo login. MCP: add https://mcp.epismo.ai/ as a Streamable HTTP server with OAuth. Then prompt your agent: "Use pb:epismo/first-playbook to build my first Playbook." It will read this guidance, look at what you already do, and come back with a candidate — you only decide what to publish and to whom. Everything else is in the Steps below.

Execution convention: keep intermediate materials in runtime-private scratch state, not in the user’s repository. After each meaningful step, present a concise, human-readable summary in the conversation. Create a local file only when the user explicitly asks to export one.

Steps

  1. 1

    Set up the surface and the Epismo skill

    Two things must be true before anything else: the agent can reach Epismo, and it knows the model well enough to stop guessing at shapes the service will reject.

    Surface. If Epismo MCP tools are already present, use them. Otherwise choose an install route: on macOS or Linux run curl -fsSL https://epismo.ai/install.sh | sh; on Windows PowerShell run irm https://epismo.ai/install.ps1 | iex; or use npm with npm install -g epismo. Native binaries and SHA-256 checksums are also available directly from https://github.com/epismoai/cli/releases. Then run epismo login. For MCP, add https://mcp.epismo.ai/ as a Streamable HTTP server with OAuth.

    Skill. Install the portable Epismo skill from github:epismoai/skills into the agent's skills directory and load its SKILL.md. This is the setup that makes every later step cheap, so do it properly rather than skipping ahead. If this runtime has no skills directory, or installing one needs permission you do not have, read the SKILL.md and its references directly as context and continue — a strong recommendation, not a blocker.

    Identity. Resolve it before any write: epismo whoami, or read epismo://context/current_user. Note the owner Account ID — every create, alias, and ACL later needs it.

    Gate: one surface answers a real read, the skill is installed or its content is loaded, you have the owner Account ID, and you have created nothing.

  2. 2

    Find the one recurring thing a single skill cannot carry

    The hard part of a first Playbook is not the API — it is knowing what deserves one. Do not ask the user 'what would you like to write?'. Go and find it, then cut to exactly one.

    Read what this runtime can already reach, newest first: shell and command history, agent session transcripts, the repo's scripts, runbooks, and CI config, docs directories, issue and PR titles, chat threads, recurring calendar entries, saved memory, and any connected MCP or CLI surface for tickets, CRM, or support. Prefer sources showing what was actually done over sources describing what should be done. The signature of recurring work: the same multi-step sequence appearing three or more times, the same question re-answered for different inputs, work that got handed off and came back wrong, work that stalls when one specific person is away, or a checklist someone keeps rewriting from memory.

    Sketch 5-10 candidates with their outcome, frequency, current owner, and what goes wrong when done badly — then apply the single-skill test, which is the discriminator that keeps Epismo from becoming a second skills folder. It belongs in a skill when one agent finishes it in one uninterrupted pass with no human decision, no handoff, and nothing worth reading back later. It belongs in a Playbook when at least two of these hold: it spans more than one tool, surface, or agent; a human makes a judgment call partway through; someone else picks it up or reviews it; the outcome must survive the session; doing it wrong is expensive.

    Drop anything that is really documentation, anything stale within a month, and anything whose evidence you could not verify. Rank what survives by frequency times cost-of-getting-it-wrong and take the top one; where two are close, prefer the one whose next genuine instance is already on the calendar. Then state the boundary — what it covers and what it deliberately does not — and search existing Playbooks for that outcome, improving a fitting one rather than creating a near-duplicate.

    Ask the user only what the environment cannot show: which of these still matter, and which are already dead.

    Gate: exactly one candidate, backed by evidence you actually read — a path, a command, a thread, a ticket — passing the single-skill test on stated grounds, with no existing Playbook already owning that outcome.

  3. 3

    Write the Definition: input, output, harness, steps

    Draft the whole Definition — title, description, category, inputSchema, and steps — in runtime-private scratch state. Do not create files in the user’s repository or anything in Epismo yet; everything stays free to change until the next Step.

    Title names the outcome, not the topic. Description says when to reach for this and when not to; it is what search and every future agent match against, so spend real effort there.

    The three things that make it reproducible for someone who is not you:

    Input — inputSchema as JSON Schema Draft 2020-12 with an object root. Name only fields that change per run and would change the answer, mark the genuinely required ones required, and describe every field, because the description is what an agent reads to fill it. Never put credentials, tokens, or signed URLs in a schema, default, or example.

    Output — for each Step, name the concise human-readable handoff it must return in the conversation: its format and fields or sections. Expected outputs are hints, not completion criteria; use a Case Record only when durable shared history is needed.

    Harness — the agent setup the work actually assumes: which model or agent role, which tools and permissions, which sandbox or working directory, what runs in parallel versus one pass, and what must never happen without a human yes. Attach it as resource hints of kind + ref + selector (skill, mcp, cli, api, plugin, graph, document, agent, custom). Make refs as resolvable as the audience needs: publicly available skills, graphs, plugins, and MCP servers get a real link — github:owner/repo, an https docs URL, an mcp:// endpoint — with a conservative selector like main, stable, or ^1, since the link is what makes the harness reproducible off your machine. Private or team-only resources need only the name people there already use; skill://deploy-check is fine and far better than omitting the dependency or leaking an internal URL. Hints are candidates for the runtime to resolve and trust, never an instruction to install.

    Then the Steps themselves. Use as many judgment-sized Steps as the work needs: large enough that a competent agent must decide something, small enough that a reviewer can tell whether it was done. Imperative voice, aimed at whoever executes next, and end each one with a gate line stating what must be true before moving on — the cheapest quality mechanism available. Keep out shell transcripts, run-specific facts, credentials, personal data, per-run status, and large background material that should be a linked document. Steps carry no status, assignee, or completion; array order is the recommended order, not an execution graph. Omit Step IDs entirely — the server assigns them, and they are what preserves Step identity across future Versions.

    Gate: the Definition is complete and self-contained, and nothing in it is secret, run-specific, or true only this week.

  4. 4

    Rehearse it, get the go-ahead, publish it, name it

    Do not execute the real work just to test the Playbook. Manufacturing a run to validate guidance mutates real systems, spends real money, and involves other people — and teaches less than the first genuine run will anyway.

    Rehearse without side effects instead. Walk the Steps against a specific past instance you already have evidence for, and check the guidance against what actually happened. Four failures show up every time: an input field you needed that the schema does not declare, a Step that is really two or half of one, a resource hint that would not resolve on the executing machine, and a gate vague enough that two competent people would disagree. Read-only inspection is fine; anything that writes, sends, deploys, spends, or deletes is not. Fix what surfaces right now, while it is free — nothing is published, so there are no Step IDs to preserve and no Version history carrying the mistake forward.

    Then stop and ask. Show the owner a concise, human-readable summary of the final Definition — outcome, intended use, inputs, steps, resource assumptions, and recommended audience — and get an explicit yes. Recommend public when the Playbook describes a general way of working with no internal hostnames, customer names, private repo paths, headcount, pricing, or unreleased plans — shared guidance is discoverable, citable, starrable, and open to Suggestions from people who hit cases you never will. Recommend a named team or yourself when the content is genuinely company-specific, competitively sensitive, or references resources that only resolve inside your network. 'It might not be perfect yet' is not a reason to keep it private; a Version is a snapshot and a better one supersedes it. Version 1 is immutable the moment it exists, so this is the last point where changing your mind is free.

    On a yes, create the Playbook and its first Version in one call, under an owner Account you manage, with an explicit non-empty ACL — there is no implicit default, so include yourself deliberately. Every mutation takes a fresh UUID idempotency key; reuse one only when retrying an identical uncertain request.

    Then set an alias in your own owner namespace, because a UUID is not something anyone will type twice and pb:deploy-rollback is. Use a lowercase, hyphenated name for the outcome rather than the current implementation, so it survives a rewrite. An alias grants no access — the live ACL is enforced on every resolve — so it is safe to set even while the Playbook is private.

    Verify what came back: Playbook ID, Version ID, digest, assigned Step IDs, ACL, and that pb:<alias> resolves to the Version you expect. Star it so it stays in reach.

    Finally, tell the owner how this changes from here, because the published Version cannot be edited. Improvements they own go into a Draft, which saves repeatedly without minting a Version, and get the same confirmation before publishing as Version 1 did. Improvements from someone outside their control arrive as a Suggestion against this Version. Setup is done and one Playbook is live; a second one starts back at the candidate list, not here.

    Gate: the alias resolves, the ACL matches the audience the owner approved, no secret reached the published Version, and the owner knows future changes go through a confirmed Draft or a Suggestion — never a silent edit.