Skills

Your team already knows how it works: how you write a plan, how you review a change, what "done" means on a bug. A skill is where you write that down once so the agent does it your way every time. It is a named, reusable prompt for one kind of work, and once you author it, it shows up everywhere agent work starts: in the action launcher on a record, in the chat slash menu, and as a step inside a Flow.

The Skills concept covers the idea: why a named prompt is the unit of work, and why availability is tied to status. This page is how you build and curate them: writing a skill, pinning the model it runs on, sharing it, versioning it, and deciding which skills appear at which status.

The Skills page

Open Platform, then Skills, to see every skill your workspace can use in one list. Each row carries what you need to tell them apart at a glance:

• The name and its command, the /slug you type in chat or pick from a launcher.
• A source label: Built-in for the skills Disco Parrot ships, Tenant for ones your workspace authored. A skill that is private to its author shows a Private badge in place of its source.
• The SDK, the runtime a skill is pinned to, showing Default when nothing is pinned and a warning when a pinned runtime has been turned off.
• Its tags, and a Bound to count, the number of workflow statuses where the skill is offered, linking straight to the bindings that put it there.

Search runs across slug, name, description, and tags. A filter panel narrows the list by source, by visibility, and by whether a skill was written by hand or drafted by the agent. The primary action is New Skill, available to anyone your workspace has cleared to author. To clean up skills the agent has drafted over time, select rows and bulk-delete the AI-authored ones in one pass. Built-in and hand-written skills in the selection are left alone.

Writing a skill

Click New Skill and the agent opens in a side drawer to help you author it, or open the editor directly to write one by hand. Either way, a skill is a short record with a few fields:

• A name, and a command derived from it. The command is the /slug people type; it is editable while you are creating the skill and locks once it exists, so the name people learn stays stable. Slugs are lowercase, hyphenated, and short.
• A prompt, the instruction the agent follows when the skill runs. This is plain instruction text written in a markdown editor, not a templating language with variables to fill in.
• A short description, a one-line summary shown in the list and matched by search, so the right skill is easy to find later.
• A visibility: Tenant, shared with the whole workspace, or Private, visible only to you. Private is enforced, not cosmetic: a private skill never appears in anyone else's list, launcher, or slash menu.
• Optional tags, an optional pinned runtime and model, and an Always available switch that surfaces the skill in every status regardless of the bindings.

Pinning the model

A skill can carry the AI runtime and model it should run on, set right in the editor. The pin travels with the skill wherever it runs, in a Flow or straight from the launcher, so the routing holds without anyone choosing a model by hand: a heavyweight reasoning model on your implement skill, a cheaper one on a routine cleanup, a different provider on a skill whose job is to check another model's output. Pinning a runtime or an off-default model is part of the multi-provider capability: a workspace on that entitlement sets the pin, and a workspace without it runs every skill on the workspace default.

Customizing a built-in

The built-in skills cover the common moves: research a codebase, draft an initiative, write a plan, implement it, generate test cases, verify the work, review a pull request, open one. They are labeled Built-in, and you cannot break one. To change a built-in, you Customize it, which seeds an editable copy into your workspace from the original, the same gesture you make on a built-in Flow. The copy is yours to edit; the built-in underneath stays untouched, so the original is always there to fall back to. A skill you write from scratch and a skill you fork from a built-in live side by side and follow the same rules.

Let the agent write it

You can hand the writing to the agent. Choose to create or edit a skill with AI and a focused chat opens; describe the skill you want, and the agent drafts the name, the command, the prompt, the visibility, the tags, and even the pinned model, then writes the record for you. The change runs through the same guarded path as any agent-authored edit: it is permission-checked, and the resulting version is stamped as AI-authored, so you can always tell a generated skill from a hand-written one and review the history of either. A handful of core slugs are reserved, so an agent-authored skill cannot claim the name of a built-in that ships real work. A /verify or a /review always points at the skill behind it, not at something the agent named the same.

What makes a good skill prompt

A skill's prompt is the whole skill. There is no form, no variables, no settings screen behind it doing the real work, so the quality of a skill is the quality of what you wrote. The good news is that this reads like briefing a capable teammate, not like programming, and the same instincts apply.

A prompt that holds up across a hundred runs tends to do four things.

• Name the job in the first line. "Review this plan against our house style" tells the agent what kind of work this is before any detail. The agent runs this prompt on a record it can already see, so you are adding the intent, not re-describing the record.
• Spell out what "done" means. The skills that pay off are the ones that encode a standard your team already holds in its head: the three things every review checks, the shape a plan has to have, the files a change is not allowed to touch. Write the checklist down. That is the part the agent cannot guess.
• Say what to produce, not just what to consider. "Flag any column rename in a comment on the plan" gives the agent a verb and a destination. A prompt that lists concerns without an output leaves the agent to choose how to report, and that choice drifts run to run.
• Leave room for the run. Anything that changes per run belongs in the starting context a person types when they launch the skill, not baked into the prompt. The prompt is the standing instruction; the starting context is the one-time pointer. Keep the line between them and the same skill stays right for every record it runs on.

The instinct to resist is over-specifying. A prompt that scripts every step turns the agent into a slow macro and breaks the first time the work does not match the script. Write the standard and the output; trust the agent with the path between them. If a skill needs to make a real decision, have it report a plain finding rather than encoding the decision in the prompt, the same way a Flow condition reads a decision a step made rather than computing one itself.

Skills worth writing first

The skills that earn their place fastest are the ones that write down a standard your team currently re-explains in chat. A few patterns come up on almost every team.

• A house-style review. The two or three things every review on your codebase has to check, so the review step of every Flow and the review action on every plan apply the same bar.
• A verification skill that knows your fixtures. Point it at the test data and the commands your team actually runs, so "verify this" means something specific to your stack rather than a generic pass.
• A plan or spec skill in your team's shape. The sections a plan has to have, the level of detail you expect, the questions a spec has to answer, so a drafted plan arrives in the format your team already reviews.
• A scoped cleanup or triage skill. A narrow, repeatable move, sweep a directory, route a bug, summarize a thread, pinned to a cheaper model because the work is routine.

Each of these starts as a customized built-in when one is close, or a skill from scratch when none fits. The test for whether something should be a skill is simple: if you have explained it in chat more than once, it is a skill you have not written yet.

One skill, three surfaces

You author a skill once, and it shows up in three places agent work starts. The skill is the same record in all three; what changes is how a run gets started and what reads its result.

Two things hold across all three. The skill's pinned model travels with it, so the routing is the same whether a person launched it or a Flow did. And the skill's prompt is the same instruction every time, so a review skill reviews the same way from the launcher, from chat, and as a Flow step. The one difference worth knowing is the result: a built-in skill hands back a structured result a later Flow step can read, while a custom skill returns a general result, which is why a custom skill fits a one-off action or the last step of a chain.

A skill, from blank to bound

Sarah's Analytics team keeps rewriting the same review note in chat: check the query against the fixtures, confirm the CSV headers match the spec, flag any column rename. She writes it down once.

She clicks New Skill, names it Review house style, and writes the prompt the way she would brief Priya, the three things every review on the Insights project has to check, in plain language. She pins it to the model the team trusts for review work, sets visibility to Tenant so the whole team gets it, and saves. The first version is stamped with her name.

Now she places it. On the Plan workflow's Skills tab she opens In review and adds Review house style as the default, so it leads the launcher the moment a plan reaches that status. After that the skill just shows up: Tom opens his plan in review and it is the first action offered, Maya drops it into the CSV Export Flow as the review step, and nobody re-types the house rules in chat again.

A month later the team adds a fourth check. Sarah edits the prompt, the save snapshots a new version next to the first, and every launcher and Flow that points at the skill picks up the change at once. She wrote down how her team reviews once, and the agent has done it her way ever since.

Versions and restore

Every save snapshots a version, tagged with whether the edit came from a person or the agent. The skill's Version History shows them in order with the author and a change note on each. Open a version to see a side-by-side diff against the one before it, and Restore it to bring its content back. A version captures the whole record, not just the prompt: the name, the pinned model, the visibility, the tags, so the history reads as the complete state of the skill at each save, and a diff shows exactly which of those moved.

Restore is non-destructive. It does not roll history back; it writes the old content forward as a new version, so the version you restored from and everything after it stay in the record. The history is a complete account of how a skill got to where it is, not a thing that gets rewritten when you change your mind.

Status-scoped skills

A flat menu of every skill on every screen would be noise. Status-scoped skills keep the surface relevant by tying the skills that appear to where a piece of work actually is: a plan in progress offers implement and verify; a bug in triage offers the skills you use to assess and route it.

A binding maps an entity type and a status to an ordered list of skills, with an optional default. Bindings apply to the work types that move through a status machine: your initiatives, plans, bugs, and flows. (Projects do not have a status machine, so they do not take bindings.) The order is meaningful, and the default is the skill that leads at that status.

Managing bindings

You curate bindings from two directions, and both let you work across many statuses at once.

• Per status, on a workflow's Skills tab, you open a status and build its ordered list: add skills, set one as the default, reorder them, or clear the list. Edits save as you make them, so the menu people see updates the moment you change it.
• Per skill, on the skill's own Workflows tab, you see every status a skill appears in and toggle it on or off across a whole entity type at once, with an Available switch for presence and a Default switch for the lead position.

When you bind one skill to many statuses in a single pass, you decide how it should treat each status's existing default. The choice is explicit, so a bulk change never quietly reshuffles which skill leads where it already matters:

• Don't change defaults, the safe default: add the skill everywhere you selected and leave each status's current default alone.
• Set as default where no default exists: make the skill the default only on statuses that do not have one yet.
• Overwrite all defaults: make the skill the default on every status you selected.

Bind one skill across a workflow

The single-status bind is the common move; the bulk bind is the one that saves an afternoon. Maya has just written a security-scan skill and wants it offered on every in-flight status across her plans and bugs, without disturbing the defaults her team already set.

From the skill's own Workflows tab she opens Apply to statuses. The modal shows a tree grouped by entity type, Initiative, Plan, Bug, and Flow, with every status under each. A faint check marks the statuses where security-scan is already bound, so she can see at a glance what she is adding to. She expands Plan and Bug, ticks the in-progress and in-review statuses under each, and leaves the planning and done statuses alone.

Then she makes the one decision a bulk bind asks for: how to treat each status's existing default. She leaves it on Don't change defaults, because she is adding a skill to the menu, not changing which one leads. The modal tells her how many of her selected statuses already have a default and that they will be left untouched, so the choice is never a guess. She clicks Apply, and security-scan appears in the launcher at every status she picked, on plans and bugs alike, in a single pass. The defaults her team relies on stay exactly where they were.

Had she wanted security-scan to lead instead, Set as default where no default exists would have made it the default only on the statuses that had none, and Overwrite all defaults would have made it the default everywhere she selected. The modal names how many statuses each choice touches before she commits, so a bulk change never quietly reshuffles which skill leads where it already matters.

What actually surfaces

When a record opens at a status, the platform resolves the skills to show. The rules are worth knowing because they make the surface predictable:

• A configured status shows its bound list, in order, with its default first.
• An unconfigured status is not empty; it is unscoped. A status you never touch falls back to every skill you can see, so a record always offers something sensible before anyone curates it.
• Always-available skills are added to every status on top of the bound list. They respect visibility, so a private always-available skill appears only for its owner.
• A skill whose runtime or record has gone missing is dropped from the list rather than shown broken.

The menu is cached per person so it opens instantly, and it refreshes whenever the inputs behind it move, a binding changes or a skill is edited, so a curator's edit reaches everyone's launcher without a reload and a skill that should no longer appear drops out the same way. When a status is removed from a workflow, the bindings that pointed at it are cleaned up with it, so a menu never offers a skill for a status that no longer exists.

One workspace-level switch sits above all of this. Curating menus per status is part of the skills capability, so a workspace without that capability on its plan has its bindings left unapplied at launch: every status falls back to the full visible set, exactly as an unconfigured status does. Turn the capability on and the bindings you have written start shaping the menus again.

The operations that always ship

Three operations run the skill that ships for them, whatever a binding says: verifying work, reviewing a change, and creating a pull request. These are the steps that gate quality and shipping, so they stay fixed by design. A binding still shapes the menu at that status, adding skills and leading with a default, but it cannot swap out the one that checks the work before it lands, which is what keeps the ship path predictable for everyone on the workspace.

Who can author, curate, and run

Three different permissions answer three different questions, and keeping them apart is what lets you open skills to your whole team without opening the ability to rewrite them.

Reading skills and running them ship on every content-facing role, so anyone who can open a record can launch the skills offered there. Authoring skills and curating bindings are the elevated, admin-tier permissions, so the people who decide how your team works with agents are the people you choose, and everyone else gets the benefit without the ability to change the setup. Curating bindings is part of the skills capability, available to workspaces on that entitlement.

The shape of this is worth saying plainly: which skills a person sees on a record is decided by status and by visibility, not by their role. A binding offers the same set to everyone who opens the record, private skills are scoped to their owner, and the skills that surface are the same for a product manager and an engineer looking at the same plan in the same status. You shape what an agent does by curating the menu for the work, so every person who opens that record sees the same set. Your team sets the surface once, and everyone who opens the work inherits it.

Why skills work this way

Most tools that let you customize an agent give you one big prompt and a settings screen. Disco Parrot breaks the work into named skills because the thing that does the work becomes a thing you can read, fork, version, share, and place at a status. One big prompt is a black box. A skill is a file your team can point at and argue about, which is why writing a good one comes down to writing clearly, and why the same skill is a step in a Flow, an action on a record, and a slash command in chat without being three different things.

Tying availability to status is the uncommon part. A binding encodes the judgment your team already makes about what should happen to a piece of work at each stage, and then the agent offers exactly that, at exactly that stage, to everyone who touches it.

For a planner, the action that fits the work is the one on top, not buried in a wall of every command the workspace has. For an engineer, a skill is a prompt you can open, read line by line, fork, and pin to the model you trust for that work, so you are reviewing the agent's instructions, not guessing at them. For a lead, every skill and every binding is permissioned and versioned, so you can point at exactly who changed how the team works with agents, and when, and roll it back if it was wrong. For a new hire, the skills offered on a record are a map of what to do next, learned by opening the work rather than by reading a manual.