#Improving a skill

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 Tessl project. Create one with tessl project create <name> --workspace engteam; see Projects overview. If you belong to more than one Organization, add --org <name> or set TESSL_ORG; a non-interactive shell cannot prompt you to pick one.
• Publisher access or higher in the workspace
• A plugin containing the skill you want to improve. A Tessl plugin is a folder with a .tessl-plugin/plugin.json manifest; a Claude Code plugin's .claude-plugin/plugin.json does not count. If you have a standalone SKILL.md, import it.

The examples use ./my-plugin for the plugin root (the directory that contains .tessl-plugin/plugin.json) and ./my-plugin/skills/my-skill for the skill. If you made the plugin with tessl skill import, the skill folder is also the plugin root, so use the same path for both.

#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-plugin/skills/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 reaches 90% or it has run three improve rounds:

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

Pass --threshold 80 to stop at a lower score, or --max-iterations 5 to allow more rounds. In a terminal it asks before applying the changes. In CI or a piped shell it applies nothing unless you pass --yes. 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 plugin:

tessl scenario generate ./my-plugin

Generation runs server-side and usually takes several minutes. In an interactive terminal, the CLI waits for it to complete. In CI or with piped output, it submits the generation and exits immediately; pass --wait to wait for it. Check its progress with tessl scenario list --mine, then download once it completes:

tessl scenario download --last --output ./my-plugin/evals

Without --output, download writes to the plugin's evals/ folder only when you run it from inside the plugin folder. Elsewhere it writes to ./evals, where tessl eval run ./my-plugin does not look. --last downloads your most recent generation from any plugin or folder. If you started another generation since, pass the generation ID that scenario generate printed instead of --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

Run the evaluation against the plugin root, not its evals/ directory:

tessl eval run ./my-plugin

In an interactive terminal, the CLI waits for the run to finish. In CI, with piped output, or with --json, it submits the run, prints its ID, and exits 0 without waiting, so a pipeline would pass before the result exists. Pass --wait to wait up to two hours, or --wait-timeout 30m to set your own limit. If the run finishes within the limit, the exit code reports its result. If the limit runs out first, the CLI exits non-zero with "reached the wait limit", but the eval keeps running on the server. Don't start another run; check the existing one with tessl eval view <id>.

By default the agent solves each scenario twice, once without the plugin and once with it, and a judge scores both. The summary shows the lift between the two variants:

Lift: Δ +26pp (Without this plugin 67% → With this plugin 93%)

In the per-variant tables, baseline is the run without the plugin and usage-spec is the run with it.

A large positive difference means the skill reliably moves the agent toward the right behavior. 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. See Read an evaluation's results for more detail.

#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-plugin/skills/my-skill --workspace <workspace>
tessl eval run ./my-plugin --label "after-edits"

Compare the two runs with tessl eval compare <run-id> <run-id>. See Compare separate runs for the output. 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.