What a skill is for
Instructions stay on. Skills appear when a task matches or you name them, and they hold checklists, commands, and examples.
If you have already walked the agent through the same job twice, extract a skill instead of pasting a twenty-line prompt again.
A stale skill is worse than none: expired commands fail with confidence.
Where skills live and how they are found
Project-level and user-level both work. Directories follow official skill docs and inspect.
User-invocable skills often appear as slash commands. On a name collision, use the qualified form.
Marketplaces and plugins can bring skills too. More sources means inspect matters more.
- Start with one project-level skill.
- Confirm discovery with inspect.
- Qualify names when they collide.
What a skill must contain
A name, when to use it, steps, a verify command, and what not to do. Short beats complete.
Steps are commands and paths, not “mind the quality”.
Write assumptions that are only true in this repo, such as the package manager and test entry.
- Write a trigger.
- Write a verify command.
- Write bans.
- Name the skill once on a small task.
When /skillify helps
After a turn you actually liked, /skillify can draft a skill from the work. It is an accelerator, not a review skip.
Delete stale paths, add a verify command, then invoke it by name next time. Drafts are not policy.
- Extract only from a turn you trust.
- Review before you commit.
- Invoke by name next round to prove it loads.
How plugins and marketplaces meet skills
A plugin may ship skills, hooks, or tools. A marketplace is discovery. Week one still adds one thing.
If you cannot review the source, do not install. inspect, then decide whether the team keeps it.
- Local skills before marketplaces.
- Every source should have a path you can name.
How to call a skill
Name it, use the slash command, or write a task that matches the description. Do not assume it will jump out.
The TUI usually has a skills panel or slash list. Headless: put the name in the prompt or use a documented flag.
On failure, inspect first, then check collisions.
- Name it in week one; do not rely on implicit match.
- Use the qualified form on collisions.
- inspect when it does not appear.
How skills and instructions split work
Instructions hold bans and test entry that are always true. Skills hold steps for a class of tasks.
If both repeat the same sentence, delete it from the skill so it cannot drift.
- Always-true facts go in instructions.
- Repeated flows become skills.
- One-off steps stay out of skills.
Skill-chapter mistakes
Cramming a whole style guide into one skill, then wondering why it never triggers.
Never naming the skill and hoping for a match.
- Committing an unreviewed /skillify draft.
- Expired test commands inside the skill.
- Installing ten marketplace items at once.
Done looks like this
The repo has one short skill you will name, and inspect can see it.
- Trigger and verify are written.
- inspect lists it.
- You invoked it by name once.
- Instructions did not balloon with a copy of the skill.
Next: add one MCP server
The MCP chapter adds a capability the repo does not have, read-only first.
Do not wire tools while the skill is still unstable.