# Skills

Short playbooks that teach the agent how your team does a particular job, read when they are relevant.



A **skill** is a short guide that teaches the agent how your team does something: how you write
release notes, how you size work, what your readiness review covers.

Each one has a name, a line describing when it should be used, and a body. The agent only sees that
one line until it decides the skill is relevant, then it opens it. So a skill can be as long as it
needs to be without slowing down every conversation.

## Using one [#using-one]

Type `/` in the message box and pick a skill to apply it deliberately. Otherwise the agent reaches
for one on its own when the situation matches its description.

That description is the whole interface. "Whenever drafting release notes or launch announcements"
gets opened at the right moment; "notes" does not.

## Three tiers [#three-tiers]

Open a skill's **Comments** panel to discuss its wording or suggest an edit. Readers can
participate; accepting the edit follows the source's maintenance permission in the table below.
See [Comments and suggested edits](/docs/comments-and-suggestions) for review threads and mentions.

| Tier             | Who it is for                    | Who can write it       |
| ---------------- | -------------------------------- | ---------------------- |
| **Built in**     | Ships with Plansmith, read-only. | Nobody, they are ours. |
| **Company**      | Everyone in the workspace.       | Owners.                |
| **This project** | Only that project.               | Members and owners.    |

## What ships built in [#what-ships-built-in]

<Cards>
  <Card title="Plan structure">
    Where new work belongs: Specs here, a sub-plan, or beside this plan.
  </Card>

  <Card title="Spec writer">
    How a spec gets written here: what to ask first, and the coverage walk before it is ready.
  </Card>

  <Card title="Epic writer">
    How the plan's epic gets written, confirmed and corrected.
  </Card>

  <Card title="Readiness review" href="/docs/readiness-review">
    Scores how build-ready one spec is; findings land in a file.
  </Card>

  <Card title="Acceptance review" href="/docs/acceptance-review">
    Checks what was built against one spec, criterion by criterion; the report lands in a file.
  </Card>

  <Card title="Prototype builder" href="/docs/prototypes">
    Builds a clickable prototype of the plan.
  </Card>

  <Card title="Deep research">
    Sends parallel research agents at a question; the report lands in Context.
  </Card>

  <Card title="Adversarial review">
    Argues the other side of one spec before you commit to it; findings land in its review file.
  </Card>

  <Card title="Push to your issue tracker" href="/docs/push-to-your-issue-tracker">
    Sends the plan to your issue tracker, and stops without writing if a teammate changed one of
    the issues first.
  </Card>

  <Card title="Resolve push conflicts" href="/docs/push-to-your-issue-tracker">
    Works through what your team changed, one item at a time, so a stopped push can go.
  </Card>

  <Card title="Open questions" href="/docs/core-concepts">
    Raises a question only your team can answer onto the spec, records the answer with who gave it,
    and retires a question that turned out not to apply.
  </Card>
</Cards>

<Callout>
  **Spec format and Epic format are edited under [Formats](/docs/formats), not here.** They appear in
  this list because that is how the agent reaches them, and if your team customizes either one, the
  agent reads your version instead of ours.
</Callout>

## Extending a built-in skill [#extending-a-built-in-skill]

A company or project skill can **extend** a built-in one instead of replacing it: it says which
skill it extends, adds your rules at the points that skill opens up, and Plansmith delivers both
together. Five skills can be extended: **Readiness review**, **Acceptance review**, **Prototype
builder**, **Spec writer** and **Epic writer**.

[**Extending a skill**](/docs/extending-a-skill) is the whole story: the field, the extension
points, a worked example, what an extension may and may not do, and what to check when yours is not
firing.

<Callout>
  **Looking for your spec or epic format?** A format is not a skill. It decides the sections each
  spec and each epic is written in, it lives in **Settings → Formats**, and the two writer skills
  read it every time. See [Formats](/docs/formats).
</Callout>

## The agent never writes a skill [#the-agent-never-writes-a-skill]

At any tier. It can propose an [instruction](/docs/agent-instructions) and it can adjust a project
[format](/docs/formats) when you ask it to in conversation, but a skill is always written by a
person.

That is deliberate: skills are procedures the agent then follows, so a skill it could write itself
would be a loop with nobody in it.

Write one under **Settings → Skills**.

Building a repository skill for a coding agent instead? [Build a skill around a
plan](/docs/developers/build-a-skill) shows how to pull structured plan data, keep local work
separate, check coverage, run a fresh review and publish the result through the CLI.