Check a skill's quality using review

Run a review to score how well a skill is written, read the result, and apply fixes.

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.

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.

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.

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

Still using tessl skill review? tessl review replaces it. See Migrate from skill review.

Run a review

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.

# 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: 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.

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:

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.

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:

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.

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.

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 - measure whether a skill changes an agent's output, not just how it reads.
• Codifying and enforcing your skill standards - build a custom rubric, set an organisation-wide quality bar, and gate pull requests on it.