# Extending a skill
Add your team's rules to a skill Plansmith already runs, without rewriting it.
Four built-in skills are written to be extended. Your skill names one of them, adds your rules at
the points that skill opens up, and Plansmith delivers both together on every turn that skill runs.
Yours does not replace ours. The built-in procedure is still there, your text sits beside it with
your name on it, and the agent can tell which is which.
## What an extension is [#what-an-extension-is]
A skill you write under **Settings → Skills** becomes an extension the moment it says which
built-in skill it extends:
```text
---
name: Payments review
description: Before any spec that moves money goes to the core banking team
extends: readiness-review
---
```
**The form writes that header.** Name, description and **Extends** are fields on the form. Paste
the body only. A pasted header gives you two, and the inner one quietly becomes body text.
From then on, the readiness review the agent runs in your workspace is one document: our ten-row
pass, with your rules merged in at the points you filled.
## The extends field [#the-extends-field]
Before this field, a skill declared what it extended in a sentence, and nothing checked it. A
wrapper that lost the sentence quietly replaced the built-in instead of adding to it, and the only
symptom was worse output. `extends` makes the relationship something Plansmith can act on.
| You set | What happens |
| ------------------------------------ | ----------------------------------------------------------------- |
| `extends: spec-writer` | Accepted. Your rules reach every spec-writing turn. |
| `extends: spec-wrtier` | Refused, and the message lists the skills you can extend. |
| `extends: deep-research` | Refused. Deep research is a real skill, but it is not extendable. |
| An extension point with no `extends` | Refused. Points belong to a skill, so name the skill. |
| `extends`, and no points filled | Accepted. It means "run the built-in, then my additions". |
## Extension points [#extension-points]
A point is a **named place** in the skill, not a line number, so your extension keeps working when
we reword the step around it. You write the marker on a line of its own, and your text follows it
until the next marker:
```text
Read our scheme rules in Context before you score.
[HOOK: extra-rows]
Add a row "Scheme rules": every requirement that moves money names the rulebook
section it follows.
[HOOK: ready-bar]
No spec that moves money is Ready without a reversal path.
```
Anything you write **before the first marker** becomes the opening of the composed document, so a
team whose extension is all preamble and no markers loses nothing.
Each skill's points are listed on its own page:
## A worked extension [#a-worked-extension]
A payments team wants every spec that moves money reviewed against their scheme rules.
**Write the skill.** Settings → Skills → New skill. Name it `Payments review`, describe when the
agent should use it, and set **Extends** to `Readiness review`. The form then shows you that
skill's points, so you know the markers before you write a word.
**Fill the points you care about.** Paste this as the body:
```text
Read context/scheme-rules/ before you score a spec that moves money.
[HOOK: extra-rows]
Add a row "Scheme rules": every requirement that moves money names the SEPA
rulebook section it follows. Red when the spec names none.
[HOOK: ready-bar]
No spec that moves money reaches Ready without a reversal path.
```
**Save.** Plansmith checks that every point you used belongs to Readiness review, and refuses the
save with the right list if one does not.
**Use it.** Ask for a readiness review, or type `/payments-review`. Either way the agent opens one
document: our pass, your extra row, your bar. The review it writes has eleven rows, and Ready needs
your reversal path.
## What an extension can and cannot do [#what-an-extension-can-and-cannot-do]
It adds rules and raises bars. It cannot lower one, remove a step, or send output somewhere the
workspace does not recognize.
Ask for one of those and the agent follows the built-in skill and says plainly that it did, naming
your skill. That is possible because your text arrives labelled with where it came from, rather
than blended into ours.
## Why isn't mine firing? [#why-isnt-mine-firing]
| What you see | Why |
| ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| Nothing changed at all | No **Extends** set. The skill is standalone: it is invocable by name, and nothing else. |
| The save is refused | A point that belongs to a different skill. The message names the right ones. |
| Two extensions, neither runs | Two skills in the same scope extend the same built-in. Plansmith composes neither rather than picking one silently. Keep one. |
| A company extension stopped | A project skill extends the same built-in. The nearer one wins, whole: they are not merged. |
| The bottom of my extension is missing | The composed document has a size limit. Whole blocks are dropped from the last backwards, and the document says which. Shorten the extension. |
| `--extends` is not a flag | The CLI is below 0.4.0. Run `npm i -g plansmith.co`. |
## Where it applies [#where-it-applies]
An extension is a skill like any other, so it obeys the same scoping rules: a **company** skill
applies across the workspace, a **project** skill applies to its project, and the nearer one wins.
Only an owner can write a company skill.
Extensions are also readable through the API and the CLI, where `extends` is a field on the skill:
```bash
plansmith skill set payments-review --file skill.md --extends readiness-review
plansmith skill show payments-review --json # → "extends": "readiness-review"
plansmith skill set payments-review --file skill.md --no-extends # back to standalone
```