Skill lifecycle

This page is for writing a skill for canon. To use skills in a project, see Registering skills. The rules for names, frontmatter and length live in the Skill Setup Standard (standards/skill-setup-std.md), and the contribution steps in CONTRIBUTING.md, both in the canon-skills repository. This page is the order to follow them in. The commands run from a checkout of the canon-skills repository.

1. Write it one job per skill

Create skills/<name>/SKILL.md. Add hidden: true if only other skills invoke it. Decide first whether you are editing an existing skill or adding a new one: a change to how a skill does its one job is an edit, and a distinct job is a new skill.

2. List it

skills.sh list

Check that the skill appears with the right name and description.

3. Catalog it

./tools/canon-dev.sh catalog

Commit the regenerated CATALOG.md. If an existing skill imports yours, add it to that skill's depends: list.

4. Add evals at least three cases

Write the cases in skills/<name>/evals/evals.json. The standard asks for at least 3 cases covering at least 3 case types, and the tools warn below that: lint reports SP-EVALS-MISSING when there is no file and SP-EVALS-COUNT when it has fewer than 3 cases, and the skill checker reads "minimum is 3". CONTRIBUTING.md still says at least 2; the standard and the tools say 3, so write 3.

5. Run the evals

In your agent, run /skill-eval <name>. It runs your cases against the skill.

6. Lint it

./tools/canon-dev.sh lint

Lint has two tiers:

Add --strict to turn every advisory warning into a blocking error. The advisory layer needs python3; without it that layer is skipped with a notice and the structural checks still run.

Check before you continue

The standard's pre-ship checklist has four groups: Discovery (a specific, third-person description that says what the skill does and when to use it), Content (under 500 lines, one term per concept, defaults and not menus), Behavior (a validate-fix-repeat loop for complex workflows) and Testing (at least 3 eval cases that pass, tried on real use and not only the happy path). The full list is in the standard.

7. Register it and try it

In a project, register the skill and say the phrase that should trigger it:

skills.sh add <name>

Then check it does what it should. For sprint, "Start a sprint for X" should pick a tier, produce a brief, wait for your approval, and then write plan.md.

8. Before you open the pull request

CONTRIBUTING.md lists three checks: run lint (step 6), run npm test, and regenerate the catalog (step 3) if you added or renamed a skill. npm test runs lint together with the core workflow tests, so a skill that fails the blocking lint checks fails the suite.