> 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 {% 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 plugin containing the skill you want to improve (see [Create a skill](/creating-skills-and-plugins/create-a-skill.md) 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. ```bash tessl review run ./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 stops improving: ```bash tessl review fix ./my-skill --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: ```bash tessl scenario generate ./my-skill ``` Generation runs server-side. Check progress with `tessl scenario list --mine`, then download once it completes: ```bash 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 ```bash 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: ```bash tessl review run ./my-skill --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: ```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 dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` 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 optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.