Skills

A skill is a named, reusable instruction for a single kind of work: plan a change, implement it, review a pull request, write a spec. Skills are the building blocks a Flow runs, and the actions you launch from a plan, an initiative, or a bug. Disco Parrot ships a set of skills, and your team can write its own.

This page is the concept. For the how-to, writing a skill, pinning its model, sharing it, versioning it, and binding it to a status, see Skills in Work with agents.

What a skill is

A skill is small and self-contained:

• A slug and title that name it, and a prompt template, which is the instruction the agent follows when the skill runs.
• A visibility: private to you, or shared with the whole workspace.
• Optional tags, and an optional pinned AI runtime or model, so a skill can always run on the model best suited to its work.

A prompt template is plain instruction text, not a templating language. When a skill runs, its template is handed to the agent as the active instruction for that piece of work, layered on top of your Agent Instructions. That is the whole trick: a skill is a named, reusable prompt with a little metadata around it, which is why writing a good one is mostly a matter of writing clearly.

Pinning a model

The pinned model is where a skill meets your model strategy. Because the pin lives on the skill, you set the model per kind of work rather than per run: a heavyweight reasoning model for the implement skill, a smaller and cheaper one for a routine cleanup skill, and a different provider for a skill whose job is to check another model's output. The skill carries that choice wherever it runs, in a Flow or straight from the launcher, so the routing holds without anyone choosing a model by hand.

Built-in and custom

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, and review or create a pull request. A skill your team writes sits right alongside them and can be used anywhere a built-in can.

Built-in skills are labeled as such, and you cannot break one. To change a built-in, you customize it, which creates an editable copy of your own seeded from the original, the same move you make on a built-in Flow. A custom skill, whether written from scratch or forked from a built-in, lives in your workspace and follows the same rules as everything else here.

Versions and AI authoring

Skills are versioned, and a skill can be authored with the agent's help. When the agent drafts or edits a skill for you, that version is marked as AI-authored, so you can tell hand-written skills from generated ones and review the history of either.

Launching a skill

You run a skill from the record it applies to. Open a plan, an initiative, or a bug, reach for its actions, and the action launcher opens as a side drawer with the skills that fit. Pick one, optionally give it some starting context, and it runs as an agent turn against that record, right where you are.

Starting context is free text, not a form to fill in. You type what the skill should know for this run, a link, a constraint, a pointer to the part of the code that matters, and the agent reads it alongside the skill's prompt. There is nothing to wire up, which is the same reason a prompt template has no variables: a skill is instruction, and you steer it by adding instruction.

The same skills are the steps a Flow runs, so the move you make by hand and the move a Flow makes are the same unit of work. One difference is worth knowing: a built-in skill returns a structured result that a later Flow step can read, the id of the plan it wrote or the pull request it opened, while a custom skill returns a general result. That makes a custom skill ideal as a one-off action or the last step of a Flow, and built-in skills the ones you chain when a later step needs to act on what an earlier step produced.

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 binding maps an entity type and a status to the skills offered for it. A plan in "in progress" might offer implement and verify; a bug in "triage" might offer the skills you use to assess and route it. Bindings apply to the work types that move through a status machine, your initiatives, plans, bugs, and flows. A binding is an ordered list with an optional default skill, and an empty binding falls back to the built-in defaults, so a status you never configure still does something sensible.

Some skills are marked always available. These show up regardless of status, which keeps the skills you reach for constantly, and the ones that ship work, from ever being hidden behind a status you forgot to configure.

A few operations are locked the other way. Verifying work, reviewing a change, and creating a pull request always run the skill that ships for them, no matter what a binding says, so the steps that gate quality and shipping cannot be quietly swapped out.

You manage bindings two ways: per status, where you pick the skills a given status offers, and per skill, where you see and set the statuses a skill appears in. Both support adding and removing across many statuses at once.

Who shapes skills, and who runs them

Three things decide what a record offers, and they are deliberately separate. Status decides which skills fit a piece of work. Visibility decides who can see a given skill. Roles decide who can author skills and curate the bindings, the people who shape how your team works with agents.

Authoring a skill, sharing it with the workspace, and wiring up the status bindings are each permissioned, so the people who decide how your team works with agents are the ones you choose. Running a skill that is offered on a record is open to anyone who can open that record, so the menu a binding defines is the menu the whole team gets. A private skill is the one narrowing that is not about roles: it is scoped to its author by visibility.

The effect is a surface that is consistent rather than personal. The same plan in the same status offers the same set of actions to everyone who opens it, shaped once by the people who curate it, so what an agent will do for a piece of work is a property of the work and your team's setup, not of who happens to be looking at it.

Curation decides which skills a piece of work offers; the model behind each skill decides what it runs on and what it costs. Together they answer the two questions an admin cares about: how a kind of work gets done, and which model does it.

Why it matters

For your team, the right action is offered at the right moment. You see the skills that make sense for a plan that is in progress, not a wall of every command the workspace has.

For prospects and for the category, skills are how the platform's behavior gets tuned to your conventions: you encode the way your team reviews code or writes a plan once, and every Flow and every launcher can reuse it. Tying skill availability to status is an uncommon idea, and it is part of what keeps an agent's work aligned with how your team actually moves work forward.

Authoring a skill, sharing it with the workspace, and wiring up the status bindings are each permissioned, so the people who curate how your team works with agents are the people you choose, and everyone else gets the benefit without the ability to rewrite it.