> For the complete documentation index, see [llms.txt](https://docs.tessl.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.tessl.io/tutorials/improving-a-skill.md). # 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. {% hint style="info" %} **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. {% endhint %} 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 --workspace engteam`; see [Projects overview](/projects/overview.md). If you belong to more than one Organization, add `--org ` 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](/creating-skills-and-plugins/create-a-skill.md#import-an-existing-skill). 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. ```bash tessl review run ./my-plugin/skills/my-skill --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: ```bash tessl review fix ./my-plugin/skills/my-skill --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: ```bash 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: ```bash 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: ```bash 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 `. 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](/improving-your-skills/reading-evaluation-results.md) 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: ```bash tessl review run ./my-plugin/skills/my-skill --workspace tessl eval run ./my-plugin --label "after-edits" ``` Compare the two runs with `tessl eval compare `. See [Compare separate runs](/improving-your-skills/reading-evaluation-results.md#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: ```bash 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](/improving-your-skills/reviewing-skills.md) - full reference for `tessl review run`, all flags, and score interpretation. * [Prove a skill works using evaluation](/improving-your-skills/evaluate-skill-quality-using-scenarios.md) - deeper coverage of scenario generation, agent selection, and reading eval output. * [Codifying and enforcing your company's skill standards](/tutorials/codifying-and-enforcing-skill-standards.md) - gate future changes in CI so the bar you set here holds for everyone. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.tessl.io/tutorials/improving-a-skill.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.