Codifying and enforcing your company's skill standards

Capture your team's quality bar as a custom review rubric and enforce it on every skill in CI.

Takeaways

• How to gate pull requests on a review score using --threshold.
• How to authenticate CI with an API key so reviews run without manual login.
• How to fork the default rubric to encode your organisation's own quality bar.
• How to apply a custom reviewer consistently across local reviews and CI.

When a team shares skills, quality stops being a personal matter. A weak skill that one person tolerates becomes everyone's problem once it is in the shared repository, shaping how every agent on the team behaves. This tutorial shows you how to hold a quality line automatically, first by setting a score threshold that blocks substandard skills from merging, and then by forking the default rubric to encode what your organisation actually cares about.

The core workflow

1. Run tessl review run --threshold locally to confirm the score gate works
2. Create an API key and add it as a CI secret so reviews can run non-interactively
3. Add a review step to your pull request workflow
4. Install tessl/review-plugin-creator and build a custom reviewer plugin
5. Apply the custom reviewer via --review-plugin in local reviews and CI

Prerequisites

• Tessl installed and initialised (tessl init)
• Authenticated (tessl login)
• A workspace to attribute reviews to
• A GitHub repository with Actions enabled (for the CI steps)

Step 1: Test the threshold locally

Before wiring anything into CI, confirm the score gate behaves as expected:

tessl review run ./my-skill --workspace <workspace> --threshold 80

--threshold takes a 0-100 integer. The command exits non-zero when the score falls below it, which is what fails a CI step. The default is 0, which never fails. Any value above 0 enforces the gate.

Add --json when you need machine-readable output in a script that parses the result:

tessl review run ./my-skill --workspace <workspace> --json --threshold 80

--workspace is required when --json is set, because a non-interactive run cannot prompt for one.

Step 2: Authenticate CI

A review runs against your workspace, so CI needs to authenticate without an interactive login. Create an API key for the workspace:

tessl api-key create --workspace <workspace>

Copy the key and add it as a repository secret named TESSL_TOKEN in your GitHub repository settings (Settings → Secrets and variables → Actions → New repository secret).

Step 3: Add the review step to CI

Tessl publishes a GitHub Action that installs the CLI. Add a job to your pull request workflow:

name: Skill review

on:
  pull_request:

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: tesslio/setup-tessl@v2
        with:
          token: ${{ secrets.TESSL_TOKEN }}
      - name: Review skill
        run: tessl review run ./my-skill --workspace <workspace> --json --threshold 80

The step fails when the score falls below 80. Adjust the path, workspace, and threshold to match your repository. For a full reference of flags and options, see Review, lint & publish with GitHub Actions.

Step 4: Build a custom reviewer

The default rubric scores against general best practices. To score against your organisation's own standards, build a custom reviewer plugin with the create-review-plugin skill:

tessl install tessl/review-plugin-creator

Ask your agent to create a reviewer. It scaffolds the plugin structure, helps you define judges and their weights, writes the rubric files, and validates the finished plugin by running a test review.

A reviewer plugin is a standard Tessl plugin. Its key components are a config.json that sets the weight each judge contributes to the score, and one rubric file per judge that defines the scoring dimensions. The weights across validation and all judges must sum to 1.0.

The default rubric is worth forking rather than building from scratch. It scores a skill's description on specificity, completeness, trigger term quality, and distinctiveness, and the content on conciseness, actionability, workflow clarity, and progressive disclosure. Forking lets you adjust those weights or add judges for concerns specific to your team.

Step 5: Apply the custom reviewer

Point any review at your reviewer with --review-plugin, passing a local path or a workspace/plugin registry reference:

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

The same flag works in tessl review fix and in your CI gate, so the standard you define in the rubric is the standard you enforce everywhere:

tessl review run ./my-skill --workspace <workspace> --review-plugin <reviewer-plugin> --json --threshold 80

Pass --review-plugin explicitly on each run. There is no workspace-level default; passing the flag consistently is how you apply your standard.

Next steps

• Gate skill quality in CI - full reference for --threshold, --json, and tessl api-key create.
• Define your own quality standards - deeper coverage of reviewer plugin structure and the weight invariant.
• Review, lint & publish with GitHub Actions - complete GitHub Actions workflow for skill CI.