¶Writing skills

A skill is the thing you would otherwise explain to a new colleague, and then explain again.

¶What a skill is

A markdown document, optionally with extra files. Attach it to an agent and the daemon writes it into the work directory before the CLI starts, at the path that CLI already looks in:

The CLI discovers it on its own. There is no prompt template, no token budget and no injection step at run time.

A skill is not code, and not a prompt. It is documentation with a specific reader.

¶Writing one

Admin → Skills → New skill. The name becomes the folder name — Deploy Checklist becomes deploy-checklist — so two skills cannot share one, even with different display names.

Write it the way you would write onboarding notes:

## Deploying

1. Run the full test suite. Do not deploy on a red suite, even if the failure looks unrelated.
2. Run migrations before restarting workers, never after.
3. Watch the log for 60 seconds. A boot failure shows up immediately.

## Rolling back

`php artisan migrate:rollback --step=1`, then redeploy the previous tag.
Rolling back a migration that dropped a column does not bring the data back.

Good skills are specific, ordered, and say what not to do. Vague ones ("write clean code") cost tokens and change nothing.

¶Extra files

Attach examples, templates or reference material with a relative path like examples/rollback.md. They are written beside SKILL.md, keeping their structure.

Paths are validated on both sides — the server when you save, the daemon before it writes. Absolute paths, .. and hidden segments are rejected: these files land on a real filesystem on someone else's machine.

¶Attaching

Tick the agents that should have it. A skill can be attached but switched off, which keeps the pairing while silencing it — useful when narrowing down whether a skill is helping.

Only enabled skills travel in the task envelope. An agent with no skills gets an empty list.

¶Verifying that it worked

The run's output shows the agent reading the file, since it appears in the work directory before anything starts. If it does not:

• Check the skill is attached and enabled for that agent
• Check the run started after you attached it — envelopes are built at claim time
• Check the daemon log: it reports skills=N when starting a task

¶What this replaces

Without skills, the same knowledge has three bad homes: pasted into each prompt (forgotten half the time), baked into agent instructions (duplicated across agents), or nowhere at all (relearned by every run).

A skill is written once, versioned in one place, and applies to every agent that carries it. That is the whole idea behind compounding: the team gets better at something permanently, rather than one conversation at a time.