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 listCheck that the skill appears with the right name and description.
3. Catalog it
./tools/canon-dev.sh catalogCommit 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 lintLint has two tiers:
- Blocking structural checks fail the run. They cover the directory format, naming, required frontmatter, the category,
@-imports that resolve, and thedepends:graph. - Advisory checks print
warning:lines with a stable id and do not change the exit code. They flag candidates, not proof.
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.
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.