#Codifying and enforcing your company's skill standards

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 organization 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
6. Set organization and workspace policy so your standard applies by default

#Prerequisites

• Tessl installed and initialized (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 organization'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, or set your reviewer as the workspace default so every review in that workspace uses your standard without the flag. The next step covers how that default fits into wider policy.

#Step 6: Set policy across your organization

The steps so far enforce your standard one run at a time: a threshold on a command, a reviewer flag you pass, a CI job you maintain. Policy is how that standard scales beyond a single run, so it applies by default across an organization or a workspace without anyone having to remember a flag.

Policy is set in the app under Settings → Policy. Setting organization-level policy is an organization admin action, so if you do not see it, ask your admin.

#Organization-level policy

An organization is the top-level entity, and policy set there applies to every workspace and project inside it. This is where you set a single standard for the whole company, so a workspace inherits it by default rather than starting from nothing. For a security admin, this is the broadest and most impactful control.

#Workspace-level scoping

Each workspace inherits the organization policy and can tighten it for its own skills. A workspace can raise the bar above the organization default, but it cannot loosen what the organization sets: lower levels only tighten, never relax, and when levels disagree the strictest one wins. Projects can tighten a workspace policy further in the same way. This lets a stricter team hold a higher bar without weakening the company-wide floor.

The workspace default reviewer is a separate workspace setting, configured under Settings → Reviews rather than in the policy editor. As covered in Step 5, setting it means every review in that workspace applies your rubric without passing --review-plugin. For more on reviewer defaults, see Define your own quality standards.

#Require a minimum skill review score before publishing

An organization or workspace can require every skill in a plugin version to meet a minimum review score before that version becomes available. This is a publish-time quality check, not an install-time check or an eval-score check. Tessl evaluates every skill separately: it does not average their scores. A score equal to the threshold passes.

To set the organization-wide floor, open Settings → Policy → Publish policy → Skill review score policy. Turn on Enable minimum skill review score, then enter an integer from 0 to 100 in Minimum skill review score. Changes save automatically.

You can set the same policy in workspace settings. Open Effective policy to see the threshold that applies and where it came from. When both levels set a threshold, the higher threshold wins. A workspace can raise the organization floor, but it cannot weaken it.

For example, a threshold of 80 blocks a plugin version with skill scores of 91 and 78. Scores of 91 and 85 satisfy the review-score rule. The version must also pass every other enabled publication check.

The policy applies to versions published after you enable it. It does not re-check versions that are already published. For help with a blocked version, see Publication checks and blocked versions.

#Public-skill controls

Publishing skills publicly is controlled at both levels. An organization can block public publishing across all its workspaces, and an individual workspace can block it for itself. A workspace can only add restriction, so when the organization blocks public publishing, a workspace cannot re-enable it. To let only some workspaces publish public skills, leave public publishing allowed at the organization level and block it in each workspace that must stay private.

#Install gating

An install policy stops a skill that fails your security bar from being installed at all. It gates on the Snyk-powered security score, not the review quality score: choose the severity at which an install is warned and the severity at which it is blocked, so a skill that meets the block threshold is refused with the offending finding shown and no override. You can also restrict installs by source and require a minimum release age for git sources. For the full walkthrough of install policy, see Protecting yourself from insecure skills.

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