Lesson 1 — Reviewing skills with review evals

In Workshop 1 you authored a skill, installed it, and published it for your team. It works; you watched it fire. But "it installs and runs" is not the same as "it's good." A SKILL.md can pass lint, follow the spec, and still produce bad output because the body is missing one key instruction. So how do you actually know a skill is any good?

This lesson is the cheapest answer to that question: a review eval. You'll put a number on your skill's structural quality, learn to read the report it gives you, and meet the --threshold gate that keeps a sloppy skill from slipping past review.

What you'll build

By the end you'll have:

• A review eval score for your commit-conventions skill, with a clear read on what to fix.
• A working sense of the two quality signals, review evals and task evals, and which question each one answers.
• The --threshold gate that fails the moment a skill drops below your quality bar: the primitive you'll wire into a production CI pipeline in Lesson 5.

Two kinds of eval

A skill can be well-formed but wrong, and it can produce great output despite being scruffy. Structural quality and behavioral quality are different things, so you need a separate signal for each.

• Review evals answer: is the skill built well? They look at structure, frontmatter, instruction clarity, missing fields, ambiguous descriptions. Cheap to run, always-on, run automatically on publish.
• Task evals answer: does the skill do the job? They run the skill against scenarios and grade the output against a rubric. Slower, deeper, run when you ask for them.

Review evals get you from "it builds" to "it's not embarrassing" for almost no cost. Task evals are the heavier signal you reach for before rolling a skill out widely, and they're the next lesson. This one stays on the cheap, always-on signal.

What review evals can't see. They look at structure, not behavior. A skill can score 100/100 on review and still produce wrong output. That's what task evals, with scenarios, are for.

Before you start

You need one thing: a skill to review. The examples use the commit-conventions skill you authored in Workshop 1, sitting at ./skills/commit-conventions, but any SKILL.md works, so point the commands at your own. You'll also need the Tessl CLI you installed earlier (tessl login if you haven't this session).

Step-by-step

1. Run a review eval

From your skill directory, kick off a review:

tessl review run ./skills/commit-conventions

Reviews are async: run queues the review and hands you a run ID. Read the report once it finishes, with --last for the most recent run so you don't have to copy the ID:

tessl review view --last

You'll see a structured report:

Reviewing skills/commit-conventions...

Overall score: 78 / 100

Structure         ✓ 95 / 100
Frontmatter       ✓ 88 / 100
Description       ⚠ 60 / 100  — could be more specific about when to use
Body clarity      ⚠ 70 / 100  — type table is good; subject rules could be tighter
Examples          ✓ 90 / 100

Suggestions:
  - Description: name the trigger phrases users actually say ("commit message", "summarize changes")
  - Subject rules: collapse the four bullets into a single rule block

2. Read the report for the pattern, not the number

That overall score is your structural quality signal, but don't fixate on the digits. Review evals call a real model, so the exact numbers shift run to run. What's stable is the pattern of suggestions: which sections score low and what the reviewer keeps asking for.

In the report above, the two weak spots are the description and the subject rules. Both are fixable in a minute, and both are the kind of thing that makes a real difference to whether the agent reaches for the skill at the right moment. Make the edits, re-run, and watch the pattern of suggestions shrink. That loop of review, fix, re-review is the whole point.

3. Make the bar stick with a threshold

Reading a score by hand is fine while you're iterating. To make the bar stick, so a sloppy skill can't slip through even when nobody's looking, you want it enforced automatically. tessl review run accepts a --threshold flag and exits non-zero if the score falls below it. Reviews are async, but passing --threshold makes the command wait for the score and set the exit code:

tessl review run --threshold 85 ./skills/commit-conventions
# exits non-zero below 85 — the gating primitive a CI check is built on

That one line is the whole gating mechanism. Any pipeline that fails on a non-zero exit will now block a skill that drops below your bar. Turning it into a production GitHub Actions workflow (authenticating the runner, diffing only the changed skills on each pull request, and watching a check go red then green) is Lesson 5, Continuous review in CI. For now you've got the primitive; that lesson makes it real.

What you keep

You walk away with a review eval score on your commit-conventions skill, a feel for reading the report by its pattern rather than its precise number, and the --threshold gate that holds the line on structural quality. That's the cheap, always-on half of skill quality. The next lesson adds the deeper signal, task evals and scenarios, that tells you whether the skill actually does its job.