Improving a skill

Use reviews and evals to measure a skill's impact, find what's holding it back, and ship an improvement with evidence.

Takeaways

• How to run a review to get a quality score and identify what to fix.
• How to apply automated improvements with tessl review fix.
• How to generate evaluation scenarios and measure whether a change actually helps.
• How to use Skill Optimizer to run the full cycle automatically.

A skill can look well-written and still fail to improve what an agent does. This tutorial walks through both checks: a review, which tells you whether the skill is well-formed; and an evaluation, which tells you whether it actually changes agent behaviour. Together they give you the evidence to ship a skill with confidence.

The core workflow

1. Run a review to get a quality score and see what to fix
2. Apply automated fixes and re-run until the score is in good shape
3. Generate evaluation scenarios from the skill
4. Run an evaluation to measure the before/after delta
5. Edit, re-run, and confirm the improvement holds

Prerequisites

• Tessl installed and initialised (tessl init)
• Authenticated (tessl login)
• A workspace to run reviews against
• A plugin containing the skill you want to improve (see Creating plugins if you have a standalone SKILL.md)

Step 1: Run a review

A review scores the skill on how well it is written: whether the description is specific enough for an agent to load it at the right moment, and whether the content is concise, actionable, and complete.

tessl review run ./my-skill --workspace <workspace>

The output shows a score out of 100 broken down by dimension:

Judge Evaluation
  Description: 72%
    specificity: 2/3 - names the domain but lists variations of one action
    completeness: 2/3 - trigger present but capability understated
    ...
  Content: 85%
    conciseness: 3/3
    actionability: 2/3 - steps present but no worked example
    ...
Review Score: 79%

A score above 90 means the skill conforms well to best practices. 70-89 is good. Below 70 needs work. The dimension breakdown tells you where to focus: a low description score usually means the skill is not activating reliably; a low content score usually means the instructions are not specific enough for the agent to act on.

Step 2: Apply fixes

tessl review fix runs an automated improve-and-review loop. It applies edits, re-runs the review, and iterates until the score stops improving:

tessl review fix ./my-skill --workspace <workspace>

Pass --threshold 85 to keep going until it hits that score, --max-iterations 5 to allow more rounds, or --yes to apply changes without prompting. Re-run tessl review run afterwards to confirm the final score.

Step 3: Generate evaluation scenarios

A review measures whether the skill reads well. An evaluation measures whether it actually changes what an agent does. Generate scenarios from the skill:

tessl scenario generate ./my-skill

Generation runs server-side. Check progress with tessl scenario list --mine, then download once it completes:

tessl scenario download --last

By default the generator targets three scenarios. Pass --count 5 for broader coverage. Only scenarios that pass a feasibility check are saved, so you may get fewer than you ask for on a narrowly scoped skill.

Step 4: Run an evaluation

tessl eval run ./my-skill

The agent solves each scenario twice, once without the skill and once with it, and a judge scores both. The summary shows the baseline average, the with-skill average, and the difference:

Summary
  Scenarios:         3 completed
  Baseline avg:      71%
  With context avg:  92%

A large positive difference means the skill reliably moves the agent toward the right behaviour. Little or no difference usually means the skill is not activating, or the instructions are not specific enough to change what the agent does. Run with --runs 3 to average out model variance before drawing conclusions.

Step 5: Edit and confirm

If the evaluation shows little impact, the most common causes are a description that is too vague to trigger the skill reliably, content that tells the agent what to do without showing how, or instructions that are ambiguous enough for the agent to ignore. Make your edits, re-run the review to confirm the score held, then re-run the evaluation:

tessl review run ./my-skill --workspace <workspace>
tessl eval run ./my-skill --label "after-edits"

Compare the two runs with tessl eval list --mine. The scenarios from the first run are saved in the plugin's evals/ directory and become a regression test you can re-run after every future change.

Shortcut: Skill Optimizer

If you want the full cycle handled automatically, install Skill Optimizer and ask your agent to improve a skill:

tessl install tessl/skill-optimizer

Skill Optimizer runs review, applies fixes, escalates to scenario generation and evaluation, diagnoses failures, and re-runs until scores improve. Use it when you want results fast; use the manual commands when you want to understand what is happening or debug a specific dimension.

Next steps

• Check a skill's quality using review - full reference for tessl review run, all flags, and score interpretation.
• Prove a skill works using evaluation - deeper coverage of scenario generation, agent selection, and reading eval output.
• Codifying and enforcing your company's skill standards - gate future changes in CI so the bar you set here holds for everyone.