> 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/improving-your-skills/reviewing-skills.md).

# Check a skill's quality using review

{% hint style="info" %}
**Takeaway** Run a review to score how well a skill is written, read the result, and apply fixes. A review checks the skill itself in under a minute. It does not run the skill against any task.
{% endhint %}

`tessl review` reads a skill and scores it against Tessl's standard rubric. Use it for fast feedback while you are writing a skill, or to check one before you rely on it. At a high level it tells you whether the skill is well structured and formatted, and whether its description and content are clear. It does not tell you whether the skill improves what the agent produces; for that, see [Prove a skill works using evaluation](/improving-your-skills/evaluate-skill-quality-using-scenarios.md).

A review runs through an agent that reads your whole skill bundle, not just `SKILL.md`. References, scripts, and assets are all in scope. It runs server-side: `tessl review run` polls until it finishes and prints the score, so a single command feels synchronous.

{% hint style="info" %}
All the steps on this page are also available through your agent. Install Tessl's Skill Optimizer to run reviews, apply fixes, and check scores without leaving your editor: `tessl install tessl/skill-optimizer`
{% endhint %}

{% hint style="info" %}
Still using `tessl skill review`? `tessl review` replaces it. See [Migrate from skill review](/improving-your-skills/migrate-from-skill-review.md).
{% endhint %}

## Run a review

```bash
tessl review run ./my-skill --workspace engteam
```

The command packs the skill, uploads it, runs the review pipeline, and prints the score when it finishes. Pressing Ctrl+C detaches from the run; the review continues server-side and you can check on it later.

`tessl review run` scores quality. To scan a skill for security issues instead, run `tessl review run security ./my-skill --workspace engteam` — see [Protect against insecure skills](/tutorials/protecting-against-insecure-skills.md).

```bash
# View the most recent run
tessl review view --last

# View a specific run by ID
tessl review view <run-id>

# List recent runs
tessl review list

# Re-run a failed review
tessl review retry --last
```

## Read the score

A review produces an overall score from 0 to 100, a weighted average of three components:

|                 |                                                                                                                                                                                                                 |
| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Validation**  | Deterministic checks that the skill follows the [Agent Skills specification](https://agentskills.io/specification): line count, frontmatter, schema, licence, and metadata. Each check passes, warns, or fails. |
| **Description** | An LLM judge on the description, scoring how likely an agent is to load the skill at the right time. Graded on specificity, completeness, trigger term quality, and distinctiveness.                            |
| **Content**     | An LLM judge on the `SKILL.md` body, scoring how well it guides the agent once loaded. Graded on conciseness, actionability, workflow clarity, and progressive disclosure.                                      |

Each component comes with specific recommendations, for example tightening a vague description or adding trigger terms a user would naturally say. As a rough guide:

* **90% and above**: the skill conforms well to best practices.
* **70% to 89%**: a good skill, with minor improvements available.
* **Below 70%**: likely needs work before you rely on it or share it.

Example output:

```
Validation Checks

  ✔ skill_md_line_count - SKILL.md line count is 9 (<= 500)
  ✔ frontmatter_valid - YAML frontmatter is valid
  ✔ name_field - 'name' field is valid: 'format-commit-messages'
  ✔ description_field - 'description' field is valid (70 chars)
  ✔ body_present - SKILL.md body is present

Overall: PASSED (0 errors, 0 warnings)

Judge Evaluation

  Content: 85%
    A tightly written, token-efficient body that gives clear and unambiguous
    guidance for a simple task. Adding one complete worked commit-message
    example would lift actionability from good to fully concrete.

    Suggestions:
      - Add a short worked example showing a complete commit message to
        make the guidance copy-paste concrete.

  Description: 90%
    A concise, well-triggered description that clearly states both capability
    and usage conditions with natural user-facing language.

Review Score: 90%
```

## Apply fixes

`tessl review fix` runs an improve-and-review loop: it reviews the skill, applies improvements, and re-reviews, up to `--max-iterations` times (default 3, maximum 10) or until the score reaches a target you set with `--threshold`.

```bash
tessl review fix ./my-skill --workspace engteam
```

It prompts before applying changes, since the loop edits the skill content directly. Pass `--yes` (or `-y`) to apply without a prompt, which is useful in CI or batch workflows. Review the changes before you publish.

## Score against your own standards

By default a review scores against Tessl's standard rubric, based on Anthropic's best practices. To score against your organisation's own bar instead, with your own judges and weights, run the review against a custom reviewer plugin. Pass a local directory or a `workspace/plugin` registry reference with `--review-plugin`:

```bash
tessl review run ./my-skill --workspace engteam --review-plugin <reviewer-plugin>
```

The same `--review-plugin` flag works with `tessl review fix`. To build a reviewer, see [Define your own quality standards](/codifying-and-enforcing-your-skill-standards/define-your-own-quality-standards.md).

## Gate a pull request on a review score

You can run the same review in CI and fail the build when the score is too low. Combine `--json` with `--threshold`:

```bash
tessl review run ./my-skill --workspace engteam --json --threshold 80
```

The command exits non-zero when the score is below the threshold, so the CI step fails. For a complete GitHub Actions workflow, see [Gate skill quality in CI](/codifying-and-enforcing-your-skill-standards/gate-skill-quality-in-ci.md).

## Reviews when you publish

You do not have to run a review by hand. When you publish a plugin to the registry, Tessl lints and reviews it automatically, and the score appears on the registry. See [Distributing via registry](/distribute/distributing-via-registry.md).

## Prerequisites

`tessl review run` and `tessl review fix` need authentication and a workspace. The companion commands `view`, `list`, and `retry` need authentication only.

* Authentication, either a logged-in session, confirmed with `tessl whoami` and started with `tessl login`, or a `TESSL_TOKEN` API key in the environment. Any workspace member can run a review.
* A workspace to attribute the run to, passed with `--workspace`. It is required when `--json` is set, because a non-interactive run cannot prompt for one.

## Next

* [Prove a skill works using evaluation](/improving-your-skills/evaluate-skill-quality-using-scenarios.md) - measure whether a skill changes an agent's output, not just how it reads.
* [Codifying and enforcing your skill standards](/codifying-and-enforcing-your-skill-standards/overview.md) - build a custom rubric, set an organisation-wide quality bar, and gate pull requests on it.


---

# 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/improving-your-skills/reviewing-skills.md?ask=<question>&goal=<endgoal>
```

`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.