How to Create and Use Devin AI Playbooks

Keyword research for this topic puts the long-tail seed devin ai playbook at about 10 monthly searches, while the shorter related query devin playbook carries higher volume. That mismatch is useful context. People search for the runbook, not the marketing phrase, and Cognition's product docs match that instinct: a playbook is a shareable, reusable prompt for a repeated task, closer to a custom system prompt than to a chat snippet you paste once.

In plain terms, a Devin AI playbook is a reusable, shareable prompt template that steers Devin through a repeated multi-step engineering workflow with clearer procedure and success criteria. Cognition's Creating Playbooks guide describes it as a custom system prompt for work you will run again: integrate the same third-party library in different parts of an app, migrate a database with the same checklist, stand up the same analytics notebook shape against a new dataset.

Playbooks sit next to two other Devin AI surfaces that teams often blur together:

• Ad hoc prompts solve one session. They disappear when the session ends.
• Knowledge holds tips, constraints, and org context Devin retrieves when triggers match.
• Playbooks hold the full multi-step procedure you want to attach on purpose for a class of jobs.

SD Times covered Cognition's product update when Playbooks shipped: documents that give Devin instructions for common software tasks, with success criteria and guardrails, plus a gallery of shared examples such as web scraping and notebook conversion. The product framing has stayed consistent since then. You invest once so the next engineer (or the same engineer next week) does not re-teach the agent from scratch.

When a playbook is worth writing

Cognition recommends playbooks when:

• You or teammates will reuse the prompt across sessions
• You keep repeating the same reminders to Devin mid-session
• The workflow might help others in the org or the wider Devin community

Start with a simple multi-step task you already understand. The docs are honest that writing playbooks still takes skill and trial and error, the same way prompt engineering does. The payoff is a document that can unlock longer independent runs, from data loads and migrations to API-heavy integrations.

What a playbook is not

A playbook is not a dump of every coding standard you have. Cognition states that most best practices, style guides, and project-specific instructions belong in Knowledge, not in a session-attached playbook. If you put house style into every playbook, you maintain the same rules in five places and none of them stay current.

A playbook is also not a substitute for secrets management, repo access, or environment setup. Those stay in Devin's normal product surface (secrets, snapshots, integrations). The playbook should name what Devin must do once those prerequisites exist.

Few public guides draw a hard line between playbooks and Knowledge. That is the content gap that wastes the most time. Cognition draws it in the first paragraphs of the Creating Playbooks guide: read Knowledge first, then decide whether a playbook is the better fit.

Knowledge is retrieval memory

Knowledge is a bank of tips, advice, and instructions Devin can reference across sessions. You write a trigger description and short content. Devin retrieves items when current work matches the trigger. You can pin Knowledge to no repo, one repo, or all repos, enable or disable items per user, organize folders, and, on enterprise accounts, promote organization notes to enterprise scope.

Use Knowledge for material that should influence many sessions without you attaching it every time:

• Code conformance rules and package import bans
• Common bugs and fixes
• How proprietary internal tools work
• Deployment and testing habits that apply broadly

Cognition also notes that parts of prompts or playbooks you repeat regularly are Knowledge candidates. That is the transfer path: a reminder that keeps showing up in playbooks should graduate to Knowledge so every session can retrieve it.

Playbooks are intentional procedures

A playbook is attached when you want a full procedure for this session class. You select it from the Team or Community library, type a macro like !data-tutorial, or drop a .devin.md file on session start. Official using-playbooks guidance says a successful attach shows a blue pill and an inline editor before the session starts; once the session is running, the playbook appears with a grey background in chat.

Use a playbook when the work has:

• A defined outcome
• Ordered steps (setup, work, delivery)
• Explicit postconditions
• Guardrails that matter for this workflow only

How Cognition expects you to combine them

Reporting on Cognition's product messaging has been consistent: create playbooks for common recurring tasks and put general org context in Knowledge so it applies with or without a playbook. In practice:

1. Put stable team rules in Knowledge with sharp triggers.
2. Put the multi-step job shape in a playbook.
3. Keep secrets and credentials in the secrets manager, not in markdown.
4. When a playbook keeps teaching the same one-line tip, move that tip to Knowledge and delete the duplication.

Decision table you can apply today

• Repeating a whole workflow (migrate service X, generate tutorial Y, onboard integration Z): write a playbook.
• Repeating a constraint ("never import from legacy billing"): write Knowledge.
• One-off investigation: use a normal prompt; promote later if the pattern repeats.
• Company-wide standard procedure: enterprise playbooks (for enterprise customers) plus enterprise Knowledge for always-on rules.

Getting this split right matters more than clever wording. A beautiful playbook that re-teaches lint rules Devin already has in Knowledge just adds noise.

Keep Devin playbook outputs in one shared workspace

Store session deliverables, review packs, and handoff notes in a Fast.io workspace with Intelligence Mode search, per-file version history, and MCP access for agents. Every organization starts with a 14-day free trial.

Start 14-Day Trial

Cognition's create flow is short. The craft is in the document structure.

Featured path: create and attach

1. Draft a document that names the outcome Devin should achieve and the steps required to get there.
2. Add optional sections: Procedure, Specifications, Advice, Forbidden Actions, Required from User.
3. Create the playbook in the web app via Create a new Playbook, or save a file with the .devin.md extension and drag-and-drop it when starting a session.
4. Confirm attach: blue pill plus inline edit before start.
5. After runs, edit and save. Playbooks keep version history, so each save creates a new version you can review or revert.

Procedure: one imperative step per line

Official guidance for Procedure:

• One step per line, written imperatively
• Cover the whole task
• Include at least setup, the actual work, and delivery
• Aim for steps that are mutually exclusive and collectively exhaustive
• Use action verbs: Write, Navigate to, Run, Open a PR
• Avoid over-specifying every micro-decision unless you truly need determinism; too much specificity can reduce Devin's ability to problem-solve
• Treat procedure order like control flow: if/else, loops, and "goto" style sequencing when the path branches

Weak procedure:

1. Handle the data and make a notebook.
2. Do analysis.
3. Finish up.

Stronger procedure (shape from Cognition's R Data Science Tutorial example):

1. Download the dataset provided by the user.
2. Create an R markdown notebook titled data_science_tutorial.Rmd.
3. Create a tmp.Rmd file for writing and saving intermediate code.
4. Add five main sections (stats, EDA, train-test split, training, inference).
5. Add a short explanation for each section.
6. Convert the notebook to HTML.
7. Send the notebook, HTML, saved model, and test data to the user.

Notice the delivery step is explicit. Cognition's writing tips say to tell Devin what good looks like and how to communicate completion: which files to attach, which links to share, what "done" means.

Specifications: postconditions, not vibes

Specifications describe what must be true when Devin finishes. Prefer checkable outcomes:

• "Open a draft PR against main with migration files under db/migrations/"
• "Send the HTML report and the trained model artifact to the user"
• "All new endpoints return amounts as integer cents"

If you cannot verify the specification without reading the whole codebase, rewrite it until a human could accept or reject the result in a few minutes.

Advice, Forbidden Actions, and Required from User

Advice corrects Devin's priors across the task. Put step-specific advice under that procedure step as nested bullets. Put global advice in its own section.

Forbidden Actions are hard stops: do not overwrite this file, do not touch production credentials, do not force-push.

Required from User (or "What's Needed From User") lists inputs Devin cannot invent: dataset link, API token the user must provide, metric name for evaluation, target environment.

Cognition also endorses including specific commands and model strings when they matter. Their TTS example is concrete: create the request dict with model: "tts-1" and voice: "alloy" because those values are easy for the agent to miss if left open-ended.

Macros and .devin.md files

Assign a macro starting with ! (for example !data-tutorial). Macros may contain letters, numbers, and hyphens only, and must be unique inside the organization. Typing the macro in the prompt input attaches the playbook quickly.

For file-based workflows, keep a something.devin.md next to the runbook owners who already live in git. That is useful when the playbook is versioned with the repo, reviewed in PRs, and only attached for certain branches. Team library playbooks remain better for org-wide reuse, macros, and enterprise distribution.

Enterprise playbooks and libraries

On enterprise plans, playbooks can live at enterprise scope as well as organization scope. Enterprise playbooks are shared across organizations in the enterprise so standard workflows do not fork team by team. Enterprise admins manage them from enterprise settings. For discovery, Cognition points people at the Community Gallery under Playbooks settings.

A starter template you can adapt

Playbook: Backfill feature flags for service-X

## Overview
Add feature-flag guards for the listed endpoints and open a draft PR.

## Required from User
- Service repo and branch name
- Flag key names and default values
- Environments that must stay off until launch

## Procedure
1. Check out the provided branch and install dependencies with the repo's standard command.
2. Locate the endpoints listed by the user.
3. Wrap each endpoint behind the named feature flag using the shared flags client.
4. Add unit tests that assert off-by-default behavior.
5. Run the service test suite for the touched packages.
6. Open a draft PR with a summary of endpoints changed and flag keys.

## Specifications
1. Draft PR exists against the requested base branch.
2. Flags default to off in production config.
3. Tests cover both flag-on and flag-off paths.

## Advice
1. Reuse the existing flags client; do not invent a second flags package.
2. Prefer the smallest diff that lands the guards.

## Forbidden Actions
1. Do not enable flags in production configs.
2. Do not push directly to main.

Creating the document is half the job. Cognition's Using Playbooks guide is short because the attach model is simple, and the Creating guide is where the iteration tactics live.

Attach paths that work in practice

• Library pick: choose from Team or Community, edit inline if needed, start the session.
• Macro: type !your-macro in the prompt input when you already know the identifier.
• File attach: drop a .devin.md onto session start when the procedure lives in-repo.

Once the session starts, confirm the playbook is present in chat (grey background in the official UI description). If it is missing, stop and re-attach before Devin burns a long run on the wrong instructions.

The iteration loop Cognition actually documents

Official tips for hardening:

1. Run 2+ Devins in parallel with the same playbook to surface failure modes quickly.
2. When Devin needs help, chat it through the stuck point, then add what you taught it back into the playbook so the next run does not need you.
3. Be explicit about the deliverable and completion signal.
4. Optimize for the efficient path: explore decisions Devin makes and encode the good branch.
5. Use version history when an edit makes runs worse: revert instead of endlessly patching a broken draft.

This parallel-run loop is the part most blog posts skip. A playbook that only ever ran once is still a draft. Two concurrent sessions on the same playbook turn "it worked for me" into a small reliability sample.

What to log after each run

Keep a short postmortem next to the playbook (in the playbook itself under Advice, or in a team note):

• Where Devin stalled
• Which procedure step was ambiguous
• Which forbidden action was missing
• Which user input should have been required up front
• Whether a tip belongs in Knowledge instead

Then edit, save a new version, and rerun. Treat the playbook like production code: small diffs, clear ownership, and reverts when quality drops.

Optimize runtime without gutting problem-solving

Cognition warns against steps that are too specific unless required. The balance is:

• Specify tools, filenames, model IDs, and delivery artifacts when wrong defaults are costly.
• Leave room for Devin to choose implementation details inside a step when many correct solutions exist.
• Encode efficiency when you have already learned the slow path (for example, "do not reinstall packages if already present" in the R tutorial advice).

Community and team libraries

Browse the Community Gallery for proven shapes, then fork into the team library and rewrite for your stack. Do not run a community playbook against production systems without reviewing Forbidden Actions and Required from User. Shared galleries optimize for generality. Your environment optimizes for safety.

Devin AI produces code, reports, notebooks, patches, and PR links. Playbooks tell the agent how to produce them. They do not, by themselves, give your org a durable place for humans and other agents to review, search, and re-share those artifacts.

Many teams start with the obvious options: keep files only in the git repo, drop zips into Google Drive or Dropbox, or park build outputs in S3. Those all work for some slices of the problem. Git is right for source. Object storage is right for large blobs. Consumer drives are fine for casual human sharing. They get awkward when an agent needs structured access, when reviewers need per-file history, and when the handoff is "agent built this, human owns it now."

Fast.io is one option for that coordination layer around Devin AI, not a built-in Devin feature. Org-owned workspaces hold session deliverables with per-file version history, granular permissions, and an append-only audit log. Enable Intelligence Mode so files are indexed for semantic search and chat with citations. Agents can work through Fast.io's consolidated MCP tools over Streamable HTTP at /mcp (legacy SSE at /sse); see mcp.fast.io/skill.md for the current tool surface. Humans use the same workspace in the UI. When an agent finishes setup, ownership transfer hands the org to a human while the agent can keep admin access.

Practical pattern many teams use:

1. Store the canonical .devin.md playbook in git if it is service-specific, or in the Devin team library if it is org-wide.
2. Point Procedure delivery steps at a shared workspace folder for reports, HTML exports, and review packs that do not belong in the repo.
3. Use branded Send shares when clients only need a package, not repo access.
4. Keep Knowledge and playbook text free of secrets; secrets stay in Devin's secrets manager and in your normal secret store.

Plans are Starter at $29/mo, Business at $99/mo, and Growth at $299/mo. Every organization starts with a 14-day free trial (credit card required). For agent-oriented onboarding text, see fast.io/llms.txt.

The point is not to replace Devin AI. It is to keep playbook-driven output from scattering across local disks and one-off chat attachments after the session ends.

If you want a concrete ramp instead of a theory pass, use this sequence.

Day 1: inventory repeats

List three tasks you already re-explain to Devin or to teammates. Good candidates show up at least twice a month and have a clear "done" state. Drop pure Q&A and open-ended research; those stay as normal prompts.

Day 2: write one thin playbook

Use Procedure, Specifications, Forbidden Actions, and Required from User only. Skip clever Advice until you have a failure to correct. Create it in the web app and assign a macro.

Day 3: dual-run

Launch two sessions with the same playbook and the same inputs. Note divergences. Chat only as much as needed to unblock, then fold the fixes into the document and save a new version.

Day 4: split Knowledge from the playbook

Anything that is a permanent team rule moves to Knowledge with a tight trigger. The playbook should get shorter after this step, not longer.

Day 5: delivery path

Decide where artifacts land: PR only, repo path, object storage, Drive, or a shared Fast.io workspace. Update Specifications so "done" includes that location. If reviewers need semantic search over exports, enable Intelligence Mode on the workspace.

Ongoing: version and promote

Revert bad edits with version history. When a playbook becomes a company standard on enterprise, manage it at enterprise scope so orgs do not fork silently. Review community gallery ideas, but always rewrite Forbidden Actions for your threat model.

Playbooks reward teams that treat them like software. The first draft will be wrong in boring ways. Parallel runs, version history, Knowledge offloads, and explicit delivery steps are how a devin.md playbook becomes something the whole team trusts.