Lesson 3 — Optimizing a skill

You now have two numbers on your commit-conventions skill: a review score for how well it's built, and a task-eval lift for whether it actually works. Numbers are only useful if you act on them. This lesson closes the loop: you'll raise the review score automatically with the optimizer, then do the one thing no eval can do for you, which is use the skill against real work before you publish it.

It's a short lesson with a sharp point. The optimizer is fast and the dogfooding is cheap; together they're the difference between a skill that scores well and a skill you'd actually ship to your team.

What you'll build

By the end you'll have:

• A commit-conventions skill the optimizer has improved in a review-eval loop, with a recorded before-and-after lift to show for it.
• A dogfooding pass that proves the skill fires on the right prompts and doesn't tread on its siblings.
• A clear read on what the optimizer can and can't fix, so you know what's left to do by hand.

Optimize the review score

Before you change anything, record where you're starting. Run a plain review and read the score:

tessl review run ./skills/commit-conventions
tessl review view --last
# Overall score: 82 / 100

That baseline is what makes the improvement provable later. Now run the optimizer with tessl review fix, which loops the review eval and applies improvements each round until it converges or hits the iteration cap:

tessl review fix --max-iterations 5 ./skills/commit-conventions

It'll show you each round of changes before applying them. Accept them, reject them, or use --yes to auto-apply. When it finishes, run a plain review again and compare against the baseline you wrote down:

tessl review run ./skills/commit-conventions
tessl review view --last
# Overall score: 94 / 100

A lift you can read off two runs is the proof the optimizer earned its keep; "it feels better" is not. That's the loop in a sentence: "good enough to exist" → "good enough to push wider" in under a minute, without you writing more prose.

What the optimizer can't fix. It only touches what review evals can see: structure, frontmatter clarity, body shape. It won't fix a skill that scores 100/100 on review but still produces wrong output; that's a task-eval problem, and it's why the next step matters.

Dogfood before you publish

A passing lint and a review score in the 90s are necessary but not sufficient. Before you publish, install the plugin from your filesystem and put the skill through its paces against your real workflow:

tessl install file:./plugins/git-hygiene

For the git-hygiene library you've been building around commit-conventions: make a commit (does commit-conventions fire?), open a PR (does pr-description fire?), cut a release (does release-notes fire?). For any other library, run through whatever workflow it claims to support.

Two things to watch for:

• Triggering. Does each prompt load the right skill? If a prompt loads the wrong skill, or nothing, the descriptions need tightening.
• Tripping. Do the skills tread on each other? A skill loading when a sibling should have is the classic symptom of overlapping descriptions.

Fix what you find, then publish. A bad first release on the registry costs more to recall than ten minutes of dogfooding.

Verify

Two checks close the loop on this lesson's own work:

• The optimizer raised the score. The plain review you ran after optimizing reads higher than the baseline you recorded before it. If the score didn't move, the skill was already near the structural ceiling the optimizer can reach, and the remaining gap is behavioral, which is exactly what dogfooding is for.
• Dogfooding cleared triggering and tripping. Every prompt that should fire commit-conventions fires it, and no prompt that belongs to a sibling pulls it in instead. A "give me a commit message" prompt loads commit-conventions; an "open a PR" prompt loads pr-description; an unrelated prompt loads neither. If a prompt triggers the wrong skill or nothing at all, tighten the descriptions so the words a user would actually reach for appear in the right one, then dogfood again.

This is also the last of three lessons on measuring and improving skills, so before you call the skill done, confirm the whole review → task → optimize arc is in place:

• tessl review run returns a score in the 90s, read with tessl review view --last.
• evals/ contains a generated scenario set you've edited by hand.
• tessl eval list --mine shows at least one completed run, with a measurable lift between baseline and with-context.
• Your edited rubric item shows up in the per-rubric breakdown, proof your changes flowed all the way through.

If the per-rubric breakdown doesn't show your edited rule, the most common cause is that tessl eval run is picking up a different evals/ directory than the one you edited. Run it with an explicit path.

What you keep

You walk away with a commit-conventions skill that's been optimized for structure and dogfooded for behavior: measured, improved, and proven against real work. That's the full quality loop: review evals for how it's built, task evals for whether it works, the optimizer to close the structural gap, and your own hands on the keyboard to catch what numbers can't. With both signals green and a clean dogfooding pass, the skill is ready to publish to your team, exactly the move you learned in Workshop 1.