# What is Tessl?
The core components of the Tessl platform, the agentic-development problems they solve, and why teams choose Tessl.
{% hint style="info" %}
**Takeaways**
* What are the core components of the Tessl platform?
* What problems do those components solve?
* Why choose Tessl over the alternatives?
{% endhint %}
Tessl is an open platform for managing agentic development across your organization. It takes you from scaling skills to building your software factory, one workflow at a time.
Tessl works with every popular coding agent and is made up of six components:
| Component | What it is |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Registry & package manager** | Discover, install, version, and roll back skills and plugins like any other dependency. One searchable index of public and private context, agent-agnostic. |
| **Governance** | Scan and score every skill against best practices and your own company standards, with Snyk security scoring built in. RBAC controls who can create, publish, and view skills, while install and publish policies and required skills enforce your standards across every workspace, backed by a full audit trail. |
| **Evals** | Measure a skill or plugin's actual impact by running your agent on real-world tasks with and without the context. Every change ships with evidence instead of a guess. |
| **Observability** | See where skills actually activate across agent sessions, not just where they're installed. Mine agent logs to find recurring mistakes. |
| **Context and Findings** | Connect SCM accounts to map skills and configuration across repositories, then inspect reported drift, overlap, and unmanaged copies at the Organization level. |
| **Tessl Agent** | A conversational agent that drives the platform and autonomously monitors and improves your agentic setup. Runs alongside your existing agents (open beta). |
## What problems does Tessl solve?
See how Tessl solves the most common agentic development problems:
* Installing skills from public sources exposes you to new supply-chain and prompt-injection risk. → [Protecting yourself from insecure skills](/tutorials/protecting-against-insecure-skills)
* Skills sprawl into overlapping, drifting copies with no enforced standard. → [Codifying and enforcing your company's skill standards](/tutorials/codifying-and-enforcing-skill-standards)
* You can't tell whether a skill actually improves agent output, so no one risks changing it. → [Improving a skill](/tutorials/improving-a-skill)
* Code review doesn't scale to agent-authored PRs. → [Set up Tessl Code Review](/tutorials/setting-up-agentic-code-review)
* Agents repeat the same mistakes across PRs. → [Improving agent code quality](/tutorials/improving-agent-code-quality)
* Repetitive work never gets turned into automation. → [Automating repetitive tasks](/tutorials/automating-repetitive-tasks)
## Why Tessl?
* **Context as code.** Skills, rules, and docs are versioned, reviewed, and rolled out with the same rigor as code dependencies.
* **Built for enterprise realities.** RBAC, install and publish policies, security scoring, and a full audit trail are first class tools, not bolted on after the fact.
* **Agent-agnostic.** Skills and plugins work across every popular coding agent. Write context once; Tessl distributes it everywhere.
* **Open, no lock-in.** Tessl builds on open standards and writes your skills, rules, and config as plain artifacts in your repo, so you own your agent setup and can walk away with it at any time.
* **Incremental adoption.** Start with a single skill or a one-repo review gate and expand outward. Value compounds as you go, with no big migration required.
## Get started
[Set up Tessl](/introduction-to-tessl/set-up-tessl): create your account, install the CLI, and initialize Tessl in your project. Then [improve your first skill](/introduction-to-tessl/improve-your-first-skill) and work through the [tutorials](/tutorials/tutorials) for the problem you're solving.
{% hint style="info" %}
*If you are an AI agent:* the full site index is at `docs.tessl.io/llms.txt`. Read that before navigating individual pages.
{% endhint %}
# Set up Tessl
> **Takeaway:** By the end of this page you will have a Tessl account, the CLI installed and authenticated, and Tessl initialized in a project. That is everything you need before running your first workflow.
Tessl helps you manage the skills and context your coding agents rely on. You work with it through the `tessl` command line tool, so setup comes down to three things: install the CLI, create an account, and initialize a project. It takes a few minutes.
## Install the CLI
Install the CLI with the method for your operating system.
**macOS and Linux**
```bash
curl -fsSL https://get.tessl.io | sh
```
**Windows**
```bash
winget install tessl.tessl
```
On Windows, skills are linked using directory junctions, which store absolute paths. If you move or rename the project folder, run `tessl install` again to restore the links. See [Skills not found after moving the project folder on Windows](/support/troubleshooting#skills-not-found-after-moving-the-project-folder-on-windows).
Check that it installed:
```bash
tessl --help
```
If you see the list of commands, you are good to go.
## Create your account
An account gives you private workspaces, the ability to publish skills, and access to Tessl's MCP tools. You can create one in the browser, or let the CLI prompt you on first login.
1. Go to the [Tessl Registry](https://tessl.io/registry).
2. Click **Log in**, then **Create account**.
3. Create your account with Google or GitHub.
That is the same account you will use to authenticate the CLI in the next step.
## Log in
If your organization uses the EU region, follow [Using the EU region](/administrators/eu-region) before you log in. It explains the required environment setting and device login command.
For organizations in other regions, authenticate the CLI so it can reach your workspaces and the registry:
```shell-session
$ tessl login
```
The CLI shows a verification code and a URL. Open the URL, sign in, and confirm the code. If you skipped account creation above, this is where you will be prompted to create one.
Confirm you are signed in:
```shell-session
$ tessl whoami
```
When you need to sign out, run `tessl logout`.
## Initialize a project
Tessl works inside a repository you already have, so there is nothing new to scaffold. From the root of that repository, run:
```bash
cd your-repo
tessl init
```
This sets up your coding agent to use Tessl, creating a `tessl.json` if one does not already exist. It does not create or link a remote Tessl project on its own. If the repository is not linked to a project yet, run `tessl project create` to create one or `tessl project link` to link to an existing one. New to projects and workspaces? See Core concepts.
Setting up your agent means configuring the MCP connection so it can talk to Tessl. This is automatic for Claude Code, Cursor, Gemini, Codex, Copilot CLI, and Copilot in VS Code; see [Custom agent setup](/reference/custom-agent-setup) for anything it does not detect.
## Keep the CLI updated
The CLI updates itself in the background, so most of the time you do not need to think about it. Updates run only when you invoke a command, and they never block your work. If you want to update on demand, pin a version, or remove the CLI entirely, the [Installation reference](/introduction-to-tessl/set-up-tessl/installation) covers every option.
## Next
You have an account, an authenticated CLI, and an initialized project. Next, put it to work: scan your real skills, find one that needs improvement, and publish a better version in **Improve your first skill**.
# Installation
A step-by-step guide on how to install, update or remove the Tessl CLI.
## Install
{% stepper %}
{% step %}
**Download the CLI**
The CLI can be installed using Curl (native), Homebrew or npm (deprecated).
{% tabs %}
{% tab title="Native" %}
```
curl -fsSL https://get.tessl.io | sh
```
{% endtab %}
{% tab title="Homebrew" %}
```
brew tap tesslio/tap # Recommended as of Homebrew 6.0.0
brew trust tesslio/tap # Recommended as of Homebrew 6.0.0
brew install tesslio/tap/tessl
```
{% endtab %}
{% tab title="winget" %}
```sh
winget install tessl.tessl
```
{% endtab %}
{% tab title="npm (deprecated)" %}
```
npm install -g @tessl/cli
```
{% endtab %}
{% endtabs %}
{% endstep %}
{% step %}
**Test the CLI**
Run the following command to check that everything is working.
```shell-session
tessl --help
```
{% endstep %}
{% step %}
**Authenticate with Tessl \[optional]**
If your organization uses the EU region, follow [Using the EU region](/administrators/eu-region) before you log in. Set the EU environment in your shell and use device login as described there.
```shell-session
$ TESSL_ENV=app-eu tessl login --device
```
For organizations in other regions, log in to Tessl to access all CLI functionality:
```shell-session
$ tessl login
```
* This will display a verification code and URL
```
Please log in at the URL below (if your browser didn't open automatically):
https://auth.tessl.io/device
Then confirm the following code:
XYZA-BCDE
⠏ Waiting for confirmation…
```
* Open the URL in your browser and login to Tessl with either your GitHub or Google account.
* Once authenticated, you can enter the device code in your browser window.
You can now verify your authentication status with:
```shell-session
$ tessl whoami
```
To log out when needed:
```shell-session
$ tessl logout
```
{% endstep %}
{% endstepper %}
## Automatic Updates
The Tessl CLI automatically checks for updates and installs them in the background. Updates run silently without interrupting your workflow.
* Updates check every 3 hours by default
* Updates only occur when you run CLI commands; they might briefly delay command exit
* To disable automatic updates, set `TESSL_AUTO_UPDATE_INTERVAL_MINUTES=0`
* Update logs are saved to `~/.tessl/auto-update.log` for troubleshooting
{% hint style="info" %}
Automatic updates are disabled in CI environments and on `winget`
{% endhint %}
## Manual Update
To manually update your CLI to the latest version:
{% tabs %}
{% tab title="Native" %}
```shell-session
tessl cli update
```
This command will update your CLI to the latest version for your current release channel.
{% endtab %}
{% tab title="Homebrew" %}
```shell-session
tessl cli update
```
This command will update your CLI to the latest version for your current release channel.
{% endtab %}
{% tab title="winget" %}
```sh
winget upgrade tessl.tessl
```
Running `tessl cli update` will provide a hint to use `winget upgrade tessl.tessl` instead
{% endtab %}
{% tab title="npm (deprecated)" %}
```shell-session
npm update -g @tessl/cli
```
{% endtab %}
{% endtabs %}
## Update to Specific Version
You can find all releases in the [changelog](/changelog-cli). To install/upgrade to a specific version:
{% tabs %}
{% tab title="Native" %}
Example to update to a specific version:
```sh
tessl cli update --target 0.86.0
```
{% endtab %}
{% tab title="Homebrew" %}
Installing a specific version is not supported in `brew`. To update to a specific version execute:
```sh
tessl cli update --target 0.84.0
```
{% endtab %}
{% tab title="winget" %}
Example to update to a specific version:
```sh
winget upgrade tessl.tessl --version 0.84.0
```
Running `tessl cli update` will provide a hint to use `winget upgrade tessl.tessl` instead
{% endtab %}
{% tab title="npm (deprecated)" %}
Example to install a specific version:
```sh
npm install -g @tessl/cli@0.84.0
```
{% endtab %}
{% endtabs %}
## Uninstall
{% tabs %}
{% tab title="Native" %}
```sh
rm -rf ~/.local/bin/tessl ~/.local/share/tessl
```
To remove Tessl config files, delete the `~/.tessl` directory
{% endtab %}
{% tab title="Homebrew" %}
```sh
brew uninstall tessl
rm -rf ~/.local/bin/tessl ~/.local/share/tessl
```
To remove Tessl config files, delete the `~/.tessl` directory
{% endtab %}
{% tab title="winget" %}
```sh
winget uninstall tessl.tessl
```
{% endtab %}
{% tab title="npm (deprecated)" %}
Determine which `npm` Tessl package you have:
```sh
npm ls -g | grep tessl
```
To uninstall `@tessl/cli`
```sh
npm uninstall -g @tessl/cli
```
To uninstall `tessl`
```sh
npm uninstall -g tessl
```
Remove the native binaries:
```sh
rm -rf ~/.local/bin/tessl ~/.local/share/tessl
```
To remove Tessl config files, delete the `~/.tessl` directory
{% endtab %}
{% endtabs %}
# Improve your first skill
> **Takeaway:** You will connect an SCM account, explore your Organization's Context and Findings, improve a local skill, and publish a new version your team can install.
This is the end-to-end loop you will repeat with Tessl: see what context your Organization has, find what needs attention, make it better, and ship it. A few terms show up along the way, namely skills, plugins, Organizations, workspaces, reviews, and evals. You can follow every step without reading ahead; each term links to a fuller explanation in [Core concepts](/introduction-to-tessl/core-concepts). As a quick orientation: an Organization owns SCM connections and reporting, a workspace controls private publishing, and a project ties Tessl to a single repository.
Before you start, make sure you have completed [Set up Tessl](/introduction-to-tessl/set-up-tessl): create an account, install and authenticate the CLI, and initialize a project. An Organization admin must connect the SCM account.
## Step 1: Connect an SCM account
In the Tessl web app, select your Organization, then open **Settings** and **Integrations**. Under **Source control**, add your provider and authorize the repositories Tessl should scan. See [Connect Tessl to GitHub](/distribute/connect-tessl-to-github) for the GitHub flow.
Tessl starts an account scan after the SCM connection is created. The connection can succeed before the scan starts or finishes, so use the connection page to check scan status, retry a failed scan, or change its **Scan scope**.
## Step 2: Explore Context
Select your Organization, then open **Context** in the sidebar. Context shows the skills and configuration Tessl observed, including their repositories and paths. You can search the collection and filter it by state, score, security result, and other attributes.
After scan analysis succeeds, Tessl starts indexing the repository skills it found. There is no separate private-indexing switch or first-party approval step. Indexing, review, and security scoring are background work with separate failure paths, so a Context item can appear before it has scores, and not every item is guaranteed to receive a score.
## Step 3: Inspect Findings and results
Open **Findings** to see issues reported from the latest account scans. Use the filters to narrow the list by category, priority, repository activity, status, or workspace. Select a finding to review its evidence and suggested next step. Some advanced finding details depend on your Organization's plan.
A skill can need attention for different reasons, and a single skill can have more than one result. They are worth telling apart because each has its own fix.
The first is a **low review score**. A review measures the quality of the skill itself: how clear and actionable its instructions are, and how well its description tells an agent when to use it. This is the kind of problem you fix by improving the skill.
The second is a **security finding**. Tessl scans skills and plugins for risky or malicious patterns in their content and behavior, such as prompt injection hidden in the instructions, hardcoded secrets, suspicious download URLs, or obfuscated text, and warns you about anything critical or high severity. This is about safety rather than quality, so it is separate from the review score.
For this walkthrough, pick a skill with a low review score, a security result, or a Finding such as drift, overlap, or stale content. If the skill has no score yet, you can still review it directly in the next step. Check out the repository that contains the skill and change into it before you run the review.
## Step 4: Improve it
Run a review to see the detailed breakdown:
```bash
tessl review run ./ --workspace engteam
```
The review runs server-side against your workspace and returns three scores: validation (structure and formatting), description (how well the description triggers the skill at the right time), and content (how well the instructions guide the agent once loaded). Each comes with specific suggestions.
To apply those suggestions automatically, run a fix:
```bash
tessl review fix ./ --workspace engteam
```
`tessl review fix` runs an improve-and-review loop, applying changes and re-reviewing until the score is high enough or it reaches its iteration limit, improving the skill in place. Run a review once more to confirm the score went up. Aim for 70% or higher before you publish.
A security finding is handled differently, because it is about safety, not quality. Tessl never blocks you; it warns you before installing a skill or plugin with critical or high severity findings so you can decide whether to proceed. If it is your own skill, fix the flagged content, for example by removing a hardcoded secret or a suspicious URL. If it is someone else's, treat a serious finding as a reason not to install, since it can signal a compromised skill. You can read more in Core concepts.
## Step 5: Publish a new version
Once the skill passes review, publish it to your workspace and bump the version in one step:
```bash
tessl skill publish ./ --workspace engteam --bump patch
```
Use `patch`, `minor`, or `major` depending on the size of the change. Skills publish as **private** by default, so only members of your workspace can install them, and a review runs automatically on publish. Teammates pick up your new version by installing it:
```bash
tessl install engteam/
```
That is the full loop. You connected or uploaded repository context, found a skill to improve, checked its quality, improved it against best practices, and shipped a better version to your team.
## Where to go next
* Improve skills in more depth, including evaluating them against real tasks, in the Tutorials section.
* Roll context out across your repositories automatically with the [repository integration](/distribute/distribute-plugins-across-multiple-repositories).
* Understand the building blocks you just used in Core concepts.
# Core concepts
> **Takeaway:** Understand the building blocks of Tessl, namely the kinds of context, how they are packaged, where they live, and how Tessl measures quality, so the rest of the docs make sense.
If you have worked through the getting started flow, you have already used most of these ideas. This page names them and explains how they fit together.
## Context as software
Giving an agent good context is useful, but on its own it does not last. Libraries change, APIs evolve, and conventions drift, and static instructions quietly go stale. Tessl treats agent context the way you treat code: something you build, evaluate, distribute, and keep up to date. That single idea, context managed with a real lifecycle, is what everything below supports.
## The two kinds of context
Tessl works with two types of context, each suited to a different job.
| Type | When it is used | Purpose |
| ------ | --------------- | -------------------------------------------------- |
| Rules | Always | Your team's standards, applied to every task |
| Skills | When relevant | Procedural workflows, loaded when the task matches |
Rules and skills are where Tessl starts, not where it stops. Plugins can also carry other agent capabilities alongside context; see the [Plugins](#plugins) section below.
## Skills
A skill is a folder of instructions, and sometimes scripts, that teaches an agent how to do something: a specific workflow, a procedure, or a way of using a tool correctly. An agent loads a skill when its description matches the task at hand. Skills are the primary unit of context in Tessl, and they are agent-agnostic, so the same skill works across Claude Code, Cursor, Gemini, Codex, and others.
## Plugins
A plugin is a versioned bundle. It packages skills and rules, and can also carry MCP servers, which connect agents to external tools and services, and hooks, which run deterministic commands in response to specific agent events: `PreToolUse`, `PostToolUse`, `UserPromptSubmit`, `SessionStart`, and `Stop`. Everything in a plugin is installed, versioned, and updated as one unit, much like a package in npm or pip. When you want to share a coherent set of context and capabilities rather than a single skill, you publish a plugin.
## The Registry
The [Tessl Registry](https://tessl.io/registry) is where context is discovered and distributed. Your team's private context lives in your workspace; the public registry, with thousands of evaluated skills and plugins you can browse and install, is there when you want to reach beyond it. It is also where your published quality scores appear, so others can judge whether a skill is worth installing.
## Organizations
An Organization is the account-wide boundary for people, SCM connections, and reporting. Its **Context** view shows skills and configuration observed across connected or uploaded repositories. Its **Findings** view shows issues derived from the latest account scans. Organization members can view Context and Findings, while Organization admins manage SCM connections and scan settings.
## Workspaces
A workspace is the shared, private publishing boundary for a team. It holds the skills and plugins you publish privately and controls who can view, install, and publish them. Workspace context stays with your team unless you choose to share it.
## Projects
A project is the stable anchor for Tessl inside a repository. It identifies the repository and gives Tessl a fixed place to attach repository-connected data, such as evaluation runs, so your results stay tied to the right codebase over time even as branches and checkouts come and go.
## How Organizations, projects, workspaces, and plugins fit together
These concepts are easy to mix up because each one groups things, but they work on different axes. A plugin is content and capability: the skills, rules, MCP servers, and hooks you package. An Organization is account-wide access, SCM connections, Context, and Findings. A workspace is the team boundary for private publishing. A project is location: the tie between Tessl and one repository, so project results stay attached to the right codebase.
In practice, your Organization connects SCM accounts and reports Context and Findings across repositories. Teams publish private plugins to workspaces, and each project maps one repository into a workspace. An Organization can contain many workspaces, and a workspace can hold many plugins and back many projects.
## Reviews and evals
Tessl offers two ways to judge context quality, and they answer different questions. It is worth being clear on the distinction, because the names sound similar.
A **review** checks a single skill against best practices. It is fast and cheap, it runs automatically when you publish, and it produces a score across three areas: validation (structure and format), description (how well the description triggers the skill at the right time), and content (how well the instructions guide the agent once loaded). It is also where a team enforces its own skill-authoring standards, much like static analysis for code. Use a review for quick, structural feedback on the skill itself.
A **scenario eval** measures impact rather than structure. It runs an agent on real tasks, once with your context and once without, and compares the results, so you can see how much the context actually improves performance. Each scenario pairs a task with a rubric of weighted criteria used to grade the result. Evals are slower and more involved, and they attach to a project. Use an eval when you want evidence that context helps, not just that it is well formed.
In short: a review tells you whether a skill is well written; an eval tells you whether it works.
## Security checks
Alongside quality, Tessl checks the safety of skills and plugins. A security scan looks for risky or malicious patterns in a component's content and behavior, such as prompt injection buried in instructions, hardcoded secrets, suspicious download URLs, unverifiable external dependencies, or hidden and obfuscated text. Findings are graded by severity. Tessl surfaces critical and high severity findings when you install, warning rather than blocking and leaving the decision to you. A serious finding on a third-party skill can signal a supply-chain attack, so treat it with care.
## Next
With the vocabulary in place, the Tutorials section goes deeper on creating, improving, and distributing context.
# Overview
End-to-end walkthroughs for the most common agentic-development workflows on Tessl.
{% hint style="info" %}
**Takeaways**
* Which workflow solves the problem you're facing?
* Which Tessl components and commands each workflow uses.
{% endhint %}
Each tutorial walks through one common agentic-development workflow from start to finish. Start with the one that matches the problem you're solving.
| Tutorial | Use it when |
| ------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------- |
| [Using Tessl as a package manager](/tutorials/using-tessl-as-a-package-manager) | You want to install, version, and publish skills like code dependencies. |
| [Protecting yourself from insecure skills](/tutorials/protecting-against-insecure-skills) | Installing skills from public sources exposes you to supply-chain and prompt-injection risk. |
| [Codifying and enforcing your company's skill standards](/tutorials/codifying-and-enforcing-skill-standards) | Skills sprawl into overlapping, drifting copies with no enforced standard. |
| [Improving a skill](/tutorials/improving-a-skill) | You can't tell whether a skill actually improves agent output, so no one risks changing it. |
| [Set up Tessl Code Review](/tutorials/setting-up-agentic-code-review) | Code review doesn't scale to agent-authored PRs. |
| [Improving agent code quality](/tutorials/improving-agent-code-quality) | Agents repeat the same mistakes across PRs. |
| [Automating repetitive tasks](/tutorials/automating-repetitive-tasks) | Repetitive work never gets turned into automation. |
# Using Tessl as a package manager
Use Tessl as a package manager for agent context: find and install skills, keep them up to date, and publish your own to a workspace.
{% hint style="info" %}
**Takeaways**
* How to find, install, and update skills from the registry or a git repo.
* How to publish your own skill to a workspace, public or private.
* How to develop a plugin locally and reinstall it on every change.
{% endhint %}
Tessl manages agent context the way npm or pip manages code dependencies. Skills, rules, and docs are versioned packages you install into a project, update when new versions ship, and publish for others to consume. This tutorial covers the basics of using Tessl: the day-to-day package-manager flows you reach for most.
## Find and install a skill
Search the registry for skills and plugins. Tessl search is intelligent: instead of matching literal keywords, it interprets the meaning of your query and evaluates it against each result's name, description, and source, then ranks them by how closely they fit what you described. So you can search in plain language by what a skill does, as well as by its package name:
```bash
tessl search "react testing"
```
You can also browse the registry UI, open a skill, and copy its install command straight from the page.
Many commands take a workspace name. Run `tessl workspace list` first to see the workspaces you have access to, then use one of those names wherever a command shows the `` placeholder.
Install a skill or plugin by its registry name, a GitHub repo, or a local path:
```bash
tessl install / # from the registry
tessl install github:acme/skills # from a GitHub repo
tessl install file:./local-plugin # from a local directory
```
By default Tessl installs into the current project and records the dependency in your `tessl.json` manifest. Pass `--global` to install into `~/.tessl` for every project, and `--skill` to pick specific skills from a multi-skill source. Without `--agent`, Tessl installs for every coding agent it detects in the project; pass `--agent` to target a specific one instead.
## Keep installed skills up to date
See which installed dependencies have newer versions:
```bash
tessl outdated
```
This lists each dependency with its current, compatible-update, and latest version. Apply the updates:
```bash
tessl update
```
`tessl update` selects the compatible updates and lets you choose which to apply. A new major version that could break compatibility is held back until you pass `--force`. Pass `--yes` to apply all compatible updates without prompting. Remove a dependency you no longer want with `tessl uninstall /`.
## Publish your own skill
If you have a `SKILL.md` that is not yet a package, turn it into one:
```bash
tessl skill import ./path-to-skill --workspace
```
This writes a `.tessl-plugin/plugin.json` manifest under the skill directory. If you omit `--workspace`, the manifest is written with the workspace set to `"local"` and you will need to update `.tessl-plugin/plugin.json` to replace `"local"` with your workspace name before you can publish.
Publish the skill to your workspace:
```bash
tessl skill publish ./path-to-skill --workspace
```
The first publish starts at version `0.1.0`. On later publishes, pass `--bump patch`, `--bump minor`, or `--bump major` to increment the version. Use `--dry-run` to validate what would be published without publishing.
## Choose public or private
A skill is published privately by default: it goes to its workspace, where only members can find and install it. If you expect to see it in the public registry and do not, this is usually why. Add `--public` to publish it for anyone to install:
```bash
tessl skill publish ./path-to-skill --workspace --public
```
Workspaces are how Tessl scopes who can see and install a package. List the workspaces you belong to with `tessl workspace list`. A skill's full name includes its workspace, for example `/`, so workspace names are visible to anyone who can see the package.
## Develop a plugin locally
A plugin is a bundle of skills, rules, commands, and hooks described by a `.tessl-plugin/plugin.json` manifest. You can install one straight from a local directory and iterate on it before publishing.
First add the local plugin to your project:
```bash
tessl install file:./my-plugin
```
Then run install in watch mode, which re-syncs every local source in your manifest whenever its files change:
```bash
tessl install --watch-local
```
Leave it running while you edit `./my-plugin`. Each save reinstalls the updated plugin into your project, so you can test changes against a real codebase before you publish. When it is ready, publish the whole bundle with `tessl plugin publish`:
```bash
tessl plugin publish ./my-plugin --workspace
```
Like `tessl skill publish`, it accepts `--bump patch|minor|major` to increment the version and `--dry-run` to validate without publishing.
## Where to go next
* [Creating skills](/creating-skills-and-plugins/create-a-skill) and [Creating plugins](/creating-skills-and-plugins/create-a-plugin) to go deeper on authoring.
* [Distributing via registry](/distribute/distributing-via-registry) to share with your team or publicly.
* [Protecting yourself from insecure skills](/tutorials/protecting-against-insecure-skills) to review what you install for security.
# Protecting yourself from insecure skills
Inspect skills across your Organization, read their Snyk-powered security scores, and use install policies to block risky skills before they reach a developer.
{% hint style="info" %}
**Takeaways**
* How to inspect skills across your Organization and tell first-party skills from matched third-party ones.
* How Snyk-powered security scores appear in Context, and how to review any skill on demand.
* How an admin sets org, workspace, or project install policies to block risky skills.
{% endhint %}
Skills run inside your agent with access to your code, your shell, and your secrets. A skill pulled from a public source can carry a prompt-injection payload or instructions that exfiltrate data, and the risk compounds once a skill spreads across repos. The danger is not only external: a first-party skill can leak credentials through an honest mistake by the developer who wrote it, or carry a deliberate payload from an insider. This tutorial maps what is already installed, reads each skill's security score, and gates future installs against a policy.
## Find skills across your Organization
The primary path is to [connect an SCM account](/use/understand-your-skill-estate), then open your Organization's **Context** page. Tessl scans the repositories in scope and shows the skills and configuration it observed.
You can also upload a GitHub scan through your local `gh` CLI:
```bash
tessl inventory import --org your-org --workspace engteam
```
This relies on the [GitHub CLI](https://cli.github.com/) being installed and authenticated locally, and on being logged in to Tessl for the upload, so run `gh auth login` and `tessl login` first. The workspace selects the reporting Organization and checks your publishing access. Upload results remain owned by that workspace, so only people who can view the workspace can view those Context and Findings results. The upload does not establish SCM ownership and does not require an SCM connection.
Without `--repo`, the scan selects eligible repositories and scans up to the 100 most recently pushed. It does not provide complete repository coverage. Within the repositories it scans, it collects the `SKILL.md` files and manifests it finds. Skills that match a published registry skill are third-party; skills unique to your repositories are first-party. Open your Organization's **Context** page to browse the result and **Findings** to inspect reported issues. Use `--repo` to choose a specific subset, or `--dry-run ./inventory.json` to write it to disk without uploading.
## Read the security scores
Security scores are powered by Snyk. Each score is a severity: `LOW`, `MEDIUM`, `HIGH`, or `CRITICAL`.
Indexing and security scoring run as separate background work after scan analysis. A skill can appear in Context before its security score is available, and not every skill is guaranteed to receive a score. Use the available scores and Findings to prioritize investigation, then run an on-demand review when you need a current result for one skill.
## Review a single skill on demand
You do not need an Organization scan to check one skill. Review any skill directly from its directory:
```bash
tessl review run security ./path-to-skill --workspace engteam
```
This is the quickest way to vet a skill before you install it, or to gate a skill in CI. The review is powered by Snyk and returns the same severities. Add `--json` for machine-readable output, or `--fail-on high` to make the command exit non-zero when a finding meets or exceeds a severity. The `--fail-on` values are lowercase: `low`, `medium`, `high`, `critical`.
## Gate risky installs with a policy
Context, Findings, and security scores help you identify risk. An install policy stops a risky skill from being installed at all. As a security admin, this is your main lever.
Policies can be set at three levels, and the tightest one wins:
* Org level: the broadest reach and your most impactful control as a security admin. It applies to every workspace and project in the org.
* Workspace level: tightens the org policy for a single workspace.
* Project level: tightens it further for a single project.
Set policy in the app under `Settings → Policy`. Setting org-level policy is an organization admin action, so if you do not see it, ask your admin. A policy combines three kinds of rule:
* Security threshold: choose the severity at which an install is warned and the severity at which it is blocked, for example warn at `MEDIUM` and block at `HIGH`.
* Source restriction: limit the registry to your own org, or to Tessl plus your org, and choose whether installs from git sources are allowed at all. When git sources are allowed, add a git source allowlist to permit only specific hosts and orgs, for example `github.com/your-org`, so developers can still install public skills from your trusted vendors while everything else is blocked.
* Minimum release age: for git sources, require a release to be a minimum number of days old before it can be installed.
Once a policy is in place, `tessl install` evaluates every source against it:
* A source under the warn threshold installs without interruption.
* A source that hits the warn threshold prompts for confirmation. A developer can proceed, or pass `--accept-warnings` to skip the prompt in automation.
* A source that hits the block threshold cannot be installed. There is no override.
```bash
tessl install your-org/some-skill
```
When the skill's score meets the block threshold, the install is refused and the offending finding is shown. The headline uses a severity label: `Passed` for `LOW`, `Advisory` for `MEDIUM`, `Risky` for `HIGH`, and `Critical` for `CRITICAL`. A `Risky` headline below therefore means a `HIGH` score that met the block threshold:
```
Blocked by install policy (not added to tessl.json):
✖ Security Risky · Do not use without reviewing
your-org/some-skill
W011 Third-party content exposure detected.
View full report: https://app.tessl.io/...
```
{% hint style="info" %}
You can also set a publish policy that blocks publishing a skill whose security score is under a threshold, so risky skills never enter your registry in the first place. See [Codifying and enforcing your company's skill standards](/tutorials/codifying-and-enforcing-skill-standards).
{% endhint %}
## Where to go next
* [Understand your organization's context](/use/understand-your-skill-estate) for SCM connections, Context, and Findings.
* [Administrating organizations, workspaces, and roles](/administrators/administrating-organizations-workspaces-and-roles) to control who can install and publish.
* [Codifying and enforcing your company's skill standards](/tutorials/codifying-and-enforcing-skill-standards) to extend governance from security to quality.
# 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.
{% hint style="info" %}
**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 organization's own quality bar.
* How to apply a custom reviewer consistently across local reviews and CI.
* How to scale your standard from per-run flags to organization and workspace policy.
{% endhint %}
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:
```bash
tessl review run ./my-skill --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:
```bash
tessl review run ./my-skill --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:
```bash
tessl api-key create --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:
```yaml
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 --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](/distribute/review-and-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:
```bash
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:
```bash
tessl review run ./my-skill --workspace --review-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:
```bash
tessl review run ./my-skill --workspace --review-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](/codifying-and-enforcing-your-skill-standards/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](/creating-skills-and-plugins/publish-and-update#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](/tutorials/protecting-against-insecure-skills).
{% hint style="info" %}
Install policy gates on the security score. Publish policy can gate on both the security score and a minimum skill review score. You can also use `--threshold` in CI to check skill quality before publishing. A review score is not an eval result and does not guarantee runtime performance.
{% endhint %}
## Next steps
* [Gate skill quality in CI](/codifying-and-enforcing-your-skill-standards/gate-skill-quality-in-ci) - full reference for `--threshold`, `--json`, and `tessl api-key create`.
* [Define your own quality standards](/codifying-and-enforcing-your-skill-standards/define-your-own-quality-standards) - deeper coverage of reviewer plugin structure and the weight invariant.
* [Review, lint & publish with GitHub Actions](/distribute/review-and-publish-with-github-actions) - complete GitHub Actions workflow for skill CI.
# Improving a skill
Use reviews and evals to measure a skill's impact, find what's holding it back, and ship an improvement with evidence.
{% 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) 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
```
By default 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
Without this plugin avg: 71%
With this plugin 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) - 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) - 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) - gate future changes in CI so the bar you set here holds for everyone.
# Set up Tessl Code Review
Install the Tessl Review GitHub App, enable a repository, choose when reviews run, ask for a review by comment, and configure lenses with .tessl-code-review\.yml.
{% hint style="info" %}
**Takeaways**
* Install the Tessl Review GitHub App from the Tessl web app, then enable each repository you want reviewed. Installing and enabling are two separate steps.
* Choose a trigger policy, set the review behavior, and ask for a review by mentioning `@tessl-code-review` in a comment.
* Route lenses and set the finding policy with an optional `.tessl-code-review.yml` file.
{% endhint %}
For GitLab merge requests, use the CLI locally or integrate it into your own GitLab CI pipeline. This isn't a GitLab app. See [Run Code Review with GitLab](/tutorials/setting-up-agentic-code-review/code-review-in-gitlab).
The Tessl Review GitHub App is the supported way to run Tessl Code Review on GitHub pull requests. It reviews the exact head of a pull request and publishes one native GitHub review, running on Tessl's own infrastructure. There is no workflow to write, no token to store, and no runner to configure: you install the App, enable a repository, and reviews run from there.
Reviews run on Tessl's infrastructure. Each run mints a GitHub token scoped to the single repository it reviews, so no long-lived credential sits in your repository.
## Install and enable are two separate steps
Getting reviews on a repository takes two distinct actions, and both are required:
1. **Install the App** on a GitHub account or organization. This grants Tessl access to the repositories you select.
2. **Enable the repository** in Tessl. This decides whether reviews actually run.
Installing the App does not start any reviews. A repository the App can reach but that you have not enabled is reviewed by nothing. This is the most common point of confusion, so confirm both steps are done before you expect a review.
## Step 1: Install the App
1. Sign in to [tessl.io](http://tessl.io).
2. Select your organization, then open **Code reviews** in the sidebar.
3. Select **Connect GitHub**.
4. On GitHub, choose the account or organization to install into, and choose whether Tessl may access all repositories or a selected list.
You can install Tessl Reviewer more than once, for example on a personal account and one or more organizations. The repositories they reach share one table on **Code reviews**, each row naming the account it came from.
{% hint style="info" %}
Start every install from the Tessl web app. Do not follow a `github.com/apps/...` install link copied from elsewhere: the web app builds each install link for one person and expires it within minutes, so a shared or copied link fails by the time you use it.
{% endhint %}
## Step 2: Enable a repository
After the App is installed, return to **Code reviews** and select a repository to enable. A repository stays unreviewed until you enable it, even when the App already has access to it.
Enabling a repository is where the review policy below is set: its trigger policy and review behavior.
## Choose a trigger policy
The trigger policy decides when a review runs. Two policies are available:
| Policy | Label | When it reviews |
| ------------------ | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `open-and-command` | When opened or requested | When a pull request is opened or reopened, when a draft is first marked ready for review, and when someone requests a review by comment. This is the default. |
| `every-push` | After every update | The same as above, plus when the pull request is pushed to. |
Start with **When opened or requested**. It reviews a pull request once when it opens and again whenever someone asks, without spending a review on every commit.
Under **After every update**, closely spaced pushes are debounced onto the latest head rather than each starting its own review. A burst of commits collapses to one review of the newest commit, so an intermediate head you pushed and quickly replaced may never be reviewed on its own. Expect coverage of where the branch settles, not a separate review per push.
**Draft pull requests are never reviewed**, under either policy. A draft is reviewed when it is first marked ready for review, and that is what triggers its first review.
## Choose the review behavior
Three separate things decide what a review does to a pull request. Keep them apart: two are Tessl settings on the repository, and the third is your own GitHub configuration, which is the only one that actually holds a merge.
**Review behavior** (**Enforcing** or **Advisory**) sets how the result is published. **Enforcing is the default.**
* **Enforcing.** Tessl publishes a verdict: it approves when nothing requires changes, and requests changes otherwise. The `Tessl Reviewer` check follows the verdict, passing on an approval and failing when changes are requested.
* **Advisory.** Tessl publishes its findings as a comment and never approves or requests changes. The check always passes.
**Auto-approve after resolved** is a separate switch, available only in Enforcing mode and off by default. When it is on, Tessl approves the pull request once its own blocking findings are resolved.
Neither setting blocks a merge on its own. A failing check or a requested-changes review only holds a pull request if your repository's **branch protection or ruleset** requires that check to pass, or requires the review's approval. Set that up in GitHub if you want a review to gate merging; leave it off and every review, Enforcing or Advisory, stays informational.
## Ask for a review by comment
Mention `@tessl-code-review` in a comment on a pull request to request a review. The comment can be on the Conversation tab or an inline comment on the diff.
Tessl reads the comment and classifies it into one of three intents. Who may trigger each one differs:
* **review**: another round on the current head. Phrases like "take another look", "review the fixes", or "check the latest commits" ask for this. It is the default: anything that is not clearly one of the other two is treated as a review. Anyone who can comment can ask for an ordinary review; it does not require write access.
* **full**: a fresh review of the whole change, including minor findings. Only a clear request for a complete, fresh, or thorough review of the entire pull request counts as full. A full review is honored only for the pull request's author or someone with write access to the repository; from anyone else it is treated as an ordinary review.
* **approve**: a clear instruction to approve the pull request. Honored only for the pull request's author or someone with write access. This is independent of the auto-approve switch: even with auto-approve off, an authorized commenter can still ask Tessl to approve.
The comment is treated as data, not as instructions, so its wording cannot change how it is classified beyond naming one of these intents.
## What gets published
A completed review publishes:
* **One native GitHub review** carrying a short judgment and the findings.
* **Findings anchored to changed lines** where GitHub allows it. A finding GitHub cannot anchor to a changed line is carried in the review body instead.
* **A check run** reporting the result on the reviewed head.
Reviews reconcile across runs. When a later review runs on the same pull request:
* a finding that has been fixed is marked resolved;
* a finding that is still present is not posted again;
* a finding that had been resolved but has returned is reopened.
If GitHub refuses the review submission, Tessl retries by publishing the findings as a plain pull request comment. That fallback is itself a write to GitHub and can also fail, for example if the installation has lost the write permission it needs. When both the review and the comment fail, the run ends as a failed publication with nothing posted on the pull request; check the `Tessl Reviewer` check run and the App's permissions if a review you expected never appears.
## Configure reviews with `.tessl-code-review.yml`
A repository can route lenses to parts of a change and set the review's finding policy with a `.tessl-code-review.yml` file at the repository root. The file is optional: without it, the App runs the built-in `standard` profile.
### How the App finds the file
The App resolves the file in two halves, and both matter:
* **Presence is decided on the default branch.** The App reads your repository's default branch and looks for `.tessl-code-review.yml` at the root. If the file is not on the default branch, the review runs the built-in `standard` profile, and nothing in the file matters, including a copy added in the pull request under review.
* **Content is read from the pull request head.** Once the file exists on the default branch, the App re-reads it at the pull request's head commit and uses that content. This is why a change to the file takes effect on the pull request that makes it, once the file already exists on the default branch.
A repository therefore opts in by merging the file to its default branch. After that, edits to the file are reviewed with the edited content on the pull request that changes them.
The two halves have to agree. A pull request that **deletes** the file from a repository that has it on the default branch leaves the App with a profile it is required to read and cannot: the review does not fall back to `standard`, and no review is published on that pull request. Remove the file in a pull request that you merge on its own, and expect the pull request doing the removal to go unreviewed.
{% hint style="warning" %}
Because the App reads the file's content from the pull request head, a contributor who can push to a pull request can change the effective review policy in the same change. Protecting only `.tessl-code-review.yml` is not enough: a lens that points at a repository-local skill (like the local lenses in the worked example below) is read from the pull request head too, so an author who cannot touch the profile can still weaken the review by editing the skill it references.
That is the whole skill, not just its entrypoint. A skill's `SKILL.md` can pull in files beside it, such as `references/`, `scripts/` and `assets/`, and those instructions carry the same weight as the ones in the entrypoint, so protecting `SKILL.md` alone leaves the rest of the bundle open.
To require separate approval for review-policy changes, protect **every repository-local source the profile trusts** with `CODEOWNERS`, not just the profile file: the `.tessl-code-review.yml` file, and the whole directory of each local lens it references rather than that lens's `SKILL.md` on its own. Then enable required code-owner approval in your branch protection or ruleset. A lens pinned to a registry reference is fixed by its version and needs no such protection. See the [`.tessl-code-review.yml` reference](/reference/configuration#tessl-code-review-yml).
{% endhint %}
### A worked example
```yaml
schemaVersion: 1
effort: adaptive
reviewMode: standard
requestChangesAt: major
ignore:
- '**/*.generated.ts'
- vendor/**
lenses:
- ref: ./review-lenses/backend/SKILL.md
effort: high
globs:
- apps/backend/**
- '!apps/backend/**/*.generated.ts'
- ref: tessl/code-review@0.2.0#review-security-and-privacy
globs:
- infra/**
- ref: ./review-lenses/general/SKILL.md
```
`schemaVersion: 1` and a non-empty, ordered `lenses` list are required. Everything else is optional. The keys, in brief:
* `lenses[].ref`: a local `SKILL.md` path, an installed skill name, or a pinned registry reference such as `tessl/code-review@0.2.0#review-security-and-privacy`. Pin every registry reference so the review does not change when a plugin publishes a new version.
* `lenses[].globs`: repository-relative POSIX patterns selecting the files the lens sees. Patterns are evaluated in order; a `!` prefix excludes a previous match. A lens without `globs` applies to the whole change.
* `lenses[].effort`: a fixed `low`, `medium`, or `high` for that one lens.
* `effort`: how hard every lens thinks: `low`, `medium`, `high`, or `adaptive`. `adaptive` uses `medium` on a full review and `low` on a re-review.
* `ignore`: up to 64 positive patterns excluded from every lens. Each pattern excludes what it matches, so a leading `!` is rejected. `ignore` overrides lens selection.
* `reviewMode`: `strict`, `standard` (the default), or `relaxed`, the blocking strength an eligible finding needs.
* `requestChangesAt`: `critical`, `major` (the default), `minor`, or `nit`, the minimum consequence eligible to block. Low-confidence fresh findings never block, and pre-existing findings never block.
At most eight lenses run. A lens whose globs match no changed file does not run and does not count toward that limit. If no lens matches the change, the review is **skipped, which is not an approval**.
For the exhaustive key list and every edge case, see the [`.tessl-code-review.yml` reference](/reference/configuration#tessl-code-review-yml).
## Permissions the App holds
The Tessl Review GitHub App requests exactly these repository permissions:
| Permission | Level | Why |
| ------------- | ----- | -------------------------------------------------------------------------------------------------------------------- |
| Metadata | read | Read basic repository information. |
| Pull requests | write | Publish the native review and its comments. |
| Issues | read | GitHub serves a pull request's conversation comments through its issue endpoints, so reading them needs issues read. |
| Checks | write | Report the review result as a check run. |
| Contents | write | Reconcile review threads across runs. |
The App does not request Actions, Workflows, Statuses, Administration, or Members access. It reviews code; it does not take other actions in your repository.
Reviews run on Tessl's infrastructure. Each run uses a token minted for that run and scoped to the single repository under review, so nothing long-lived is stored in your repository.
## Troubleshooting
| Symptom | What to check |
| -------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| The App is installed, but no reviews run | Enabling is a separate step from installing. Enable the repository in the Tessl web app. |
| A repository cannot be enabled, or shows a permissions request | The installation may be waiting for an organization owner to approve the App's requested permissions. Ask an owner to approve the request on GitHub. |
| A review was published as a comment instead of a native review | GitHub refused the review submission, so Tessl published the findings as a plain comment instead. |
| A review you expected never appeared | Both the native review and the comment fallback can fail, for example when the installation has lost write access. Check the `Tessl Reviewer` check run and the App's permissions, then request the review again. |
| A pull request was not reviewed | Draft pull requests are never reviewed; mark it ready for review. A run is also skipped when no lens matches the change, which is not an approval. |
| A mention did nothing | Confirm the comment names `@tessl-code-review` in its text, rather than quoting it or wrapping it in backticks. Asking for a full review or an approval also needs write access to the repository, unless you opened the pull request; an ordinary review request does not. |
## Run Code Review in your own CI
For GitLab, add the CLI directly to a pipeline you own. See [Run Code Review with GitLab](/tutorials/setting-up-agentic-code-review/code-review-in-gitlab) for credentials, a job example, and publication behavior.
For GitHub, if you cannot install a GitHub App, an unsupported GitHub Action can run Tessl Code Review from a workflow you own. It is not maintained and may fall behind the CLI. See [Running Code Review in your own CI](/tutorials/setting-up-agentic-code-review/code-review-action).
## Related capabilities
The [`tessl code review`](/reference/cli-commands#tessl-code-review) CLI command runs a review locally and prints the result, and its `--publish` flag can post that review to the pull request or merge request it reviewed. Use it to try a review on a diff you already understand. The GitHub App remains the supported way to review pull requests automatically.
To turn recurring review feedback into skills, rules, tests, or verifiers, continue with [Improving agent code quality](/tutorials/improving-agent-code-quality).
# Run Code Review with GitLab
Review GitLab merge requests locally or integrate the Tessl CLI into your own GitLab CI pipeline.
GitLab support is part of the Tessl CLI, available in version 0.113.0 and later. It isn't a GitLab app or a managed integration. You run `tessl code review` locally or add it to a GitLab CI pipeline you own. You configure the runner, credentials, and review cadence.
## Review locally
Install the [Tessl CLI](/introduction-to-tessl/set-up-tessl/installation), sign in with `tessl login`, and authenticate GitLab with `glab`:
```sh
$ glab auth login --hostname gitlab.com
```
From a checkout of the repository, review a merge request by URL:
```sh
$ tessl code review --pr https://gitlab.com/engteam/my-project/-/merge_requests/42
```
The CLI collects the title, description, commits, notes, inline discussions, replies, and discussion resolution state. It reviews the merge request's source commit, including when a CI checkout contains a merged result.
In a GitLab checkout, you can also use its merge request number:
```sh
$ tessl code review --pr 42
```
`--pr` selects both GitHub pull requests and GitLab merge requests. An explicit URL selects the provider and project. If your local fetch or push remotes include both GitHub and GitLab, use a full URL instead of a number. In GitLab merge request pipelines, `GITLAB_CI=true` and `CI_MERGE_REQUEST_PROJECT_PATH` select GitLab even with mixed remotes. Outside those pipelines, use a full URL when remotes are mixed.
For self-managed GitLab, use the full URL for your host, or set `GITLAB_HOST` to the checkout's host when using a number. Authenticate `glab` against that same host. Explicit Git ranges with `--base` and `--head` remain available without GitLab access.
## Publish findings and review again
By default, the review prints its result without publishing. Add `--publish comment` to post a summary and inline discussions:
```sh
$ tessl code review --pr 42 --publish comment
```
Findings GitLab can't anchor to the diff stay in the summary. Answer a finding in its discussion: addressed, refuted, or declined. Later reviews read the replies, reconcile earlier findings, and resolve or reopen discussions where appropriate. Rerunning against the same source commit and target diff reuses existing finding threads. Replies are read when you run the CLI again; comments alone don't trigger another review.
Publication checks the source and target revisions before writes. If either changes during the review, run a fresh review against the current merge request. When a review is asked to consult linked documents, its summary includes a collapsed record of which sources were fetched and which weren't.
`--publish verdict` currently falls back to a comment with an explicit notice. It doesn't submit native GitLab approvals or request-changes decisions, create a Tessl-owned status check, or configure merge gating. Your CI job decides whether the review result should fail the pipeline.
## Add a job to your GitLab CI pipeline
Configure these variables in **Settings > CI/CD > Variables** before adding the job:
| Variable | Purpose |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `TESSL_TOKEN` | A [Tessl API key](/reference/cli-commands#tessl-api-key-create) for the workspace running the review. |
| `GITLAB_TOKEN` | A GitLab access token that can read the merge request and publish discussions. Use the `api` scope for publication. `GL_TOKEN` is also accepted. |
A read-only review can use `read_api` instead of `api`. Fetching missing Git objects also requires repository read access through the checkout's Git credentials or the token. `CI_JOB_TOKEN` alone can't provide the full merge request context and discussion publication.
{% hint style="warning" %}
**This example is for trusted code only.** A merge request pipeline reads its CI configuration from the source branch. Starting a job manually and masking its output don't prevent that configuration from sending tokens elsewhere.
Store both tokens as **masked and protected** variables. Protect both the source and target branches, and restrict permission to push to them to people you trust with these credentials. Don't expose either token to fork pipelines or unprotected source branches. The job rules below select the intended pipelines; GitLab's protected-variable permissions enforce the credential boundary even if someone changes those rules.
For untrusted merge requests, use a separate review workflow whose CI configuration and runner setup come from a trusted branch. Supply the merge request URL as data. The example below doesn't implement that workflow.
{% endhint %}
This example requires GitLab 18.1 or later and the **Allow merge request pipelines to access protected variables and runners** setting. GitLab permits that access only when both branches are protected and belong to the same project, and the triggering user has push or merge access to the target branch. See [Control access to protected variables and runners](https://docs.gitlab.com/ci/pipelines/merge_request_pipelines/#control-access-to-protected-variables-and-runners).
Add this job to `.gitlab-ci.yml`, and add the `review` stage to your existing `stages` list:
```yaml
stages:
- review
tessl_code_review:
image: node:22
stage: review
variables:
GIT_DEPTH: '0'
rules:
- if: >-
$CI_PIPELINE_SOURCE == "merge_request_event" &&
$CI_MERGE_REQUEST_SOURCE_BRANCH_PROTECTED == "true" &&
$CI_MERGE_REQUEST_TARGET_BRANCH_PROTECTED == "true" &&
$CI_MERGE_REQUEST_SOURCE_PROJECT_ID == $CI_MERGE_REQUEST_TARGET_PROJECT_ID
when: manual
allow_failure: true
before_script:
- curl -fsSL --connect-timeout 10 --max-time 120 https://install.tessl.io/scripts/0.113.0.sh -o /tmp/install-tessl.sh
- timeout --kill-after=10s 120s sh /tmp/install-tessl.sh
- export PATH="$HOME/.local/bin:$PATH"
script:
- tessl code review --publish comment --json > tessl-code-review.json
artifacts:
when: always
paths:
- tessl-code-review.json
```
This example makes the job manual and optional for protected source and target branches in the same project, so it doesn't hold a merge while waiting for a run. Start it from GitLab when you want a review. Remove `when: manual` to run it on every matching trusted pipeline. Keep the protected-branch and same-project restrictions. Your GitLab configuration must allow [merge request pipelines](https://docs.gitlab.com/ci/pipelines/merge_request_pipelines/).
No `--pr` is needed in a GitLab merge request pipeline: the CLI selects the MR from GitLab's predefined metadata. An explicit URL remains useful for jobs outside an MR pipeline. The job calls the CLI directly and doesn't use the GitHub Action or install a GitLab app.
The installer-script download has a 10-second connection limit and a 120-second transfer limit. The installer, including its own binary downloads, has a 120-second limit with a 10-second termination grace period. An installation failure can occur before the review JSON artifact exists.
`GIT_DEPTH: '0'` supplies complete history for merge-base calculation. In shallow checkouts, the CLI retrieves the selected ancestry without a depth limit; fetching has a 60-second timeout.
A completed review with findings can still exit successfully. This example publishes comments without gating on findings. If you want a gate, set `allow_failure: false`, inspect the JSON `status` first, then `outcome.approved` and `outcome.findings[].requiresChanges`, and configure the job's failure behavior yourself. A skipped review isn't an approval. A publication failure exits nonzero and preserves the completed outcome alongside its failure details.
To configure lenses and finding policy, pass `--profile ./.tessl-code-review.yml` in the job. The CLI doesn't discover that file automatically. See the [Code Review configuration reference](/reference/configuration#tessl-code-review-yml) and the [CLI reference](/reference/cli-commands#tessl-code-review).
# Running Code Review in your own GitHub CI
Unsupported. Inputs and outputs of the tesslio/code-review-action GitHub Action, kept for people who cannot install the Tessl Review GitHub App.
For GitLab merge requests, call the Tessl CLI directly from your own pipeline. See [Run Code Review with GitLab](/tutorials/setting-up-agentic-code-review/code-review-in-gitlab).
{% hint style="warning" %}
The GitHub App is the supported way to run Tessl Code Review. This page is kept for people who cannot install a GitHub App. It is unsupported and not maintained, and it may fall behind the CLI.
{% endhint %}
The [`tesslio/code-review-action`](https://github.com/tesslio/code-review-action) GitHub Action runs Tessl Code Review on a pull request and publishes one native GitHub review. This page is the input and output reference. To set up reviews the supported way, see [Set up Tessl Code Review](/tutorials/setting-up-agentic-code-review).
The Action owns pull request resolution, checkout of the exact head, Tessl CLI setup, its own check run, and result artifacts. The Tessl CLI the Action installs runs the review and publishes it. The caller workflow owns when reviews run, the permissions the job holds, the token secrets, and whether findings block merging.
## Advisory versus gate
One input decides the consequence of a review, and it appears throughout this reference: `mode`. In `advisory` mode the review is published as a GitHub `COMMENT` and no review outcome fails the `Tessl Code Review` check. In `gate` mode the review publishes the verdict it reached (approving when nothing requires changes, requesting changes otherwise) and the check follows it, so branch protection can hold the pull request on a blocking finding. A technical failure to run or publish fails the job in both modes. In gate mode, `requestChangesAt` sets the consequence baseline, `reviewMode` sets the strength required to block, `mode` decides whether the check then fails, and branch protection decides whether a failing check holds the pull request.
## Inputs
| Input | Required | Default | Purpose |
| ---------------------- | -------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `tessl-token` | yes | none | Tessl API token the CLI uses. Pass it from a repository secret; never inline it. |
| `mode` | no | `advisory` | Publication policy: `advisory` or `gate`. See [Advisory versus gate](#advisory-versus-gate). |
| `profile` | no | `standard` | Named review profile, or a repository-relative path to a `.yml`/`.yaml` profile. See [Configuration files](/reference/configuration#tessl-code-review-yml). |
| `lenses` | no | `''` | JSON array with the complete ordered lens selection. Replaces the profile's default lenses rather than adding to them. At most eight lenses. |
| `effort` | no | `''` | Reasoning effort for every lens: `low`, `medium`, `high`, or `adaptive`. Overrides any profile effort. Empty lets the profile and CLI resolve it. |
| `cli-version` | no | `latest` | Tessl CLI version to install. `latest` tracks the current release. Pin an exact version to fix review behavior alongside the Action reference. |
| `github-token` | no | `${{ github.token }}` | The identity that authors the published review. See [`github-token`](#github-token). |
| `allowed-associations` | no | `''` | Comma-separated author associations whose comments may request a review, for example `OWNER,MEMBER,COLLABORATOR`. Empty accepts any commenter. Applies to comment events only, and never refuses the pull request's own author. |
| `approver-logins` | no | `''` | Comment-author logins, separated by commas or newlines, permitted to ask the review to approve instead of reviewing. See [`approver-logins`](#approver-logins). |
| `pr-number` | no | `''` | Pull-request number for events that carry no pull-request context, such as a comment or a manual dispatch. Empty on `pull_request` events, where the Action resolves the pull request itself. |
### `github-token`
Left at its default, the review is authored by the workflow's own token, which posts as `github-actions[bot]`, the same identity as the repository's other jobs. Pass a token that carries its own identity to author the review distinctly:
* a GitHub App installation token minted per run with [`actions/create-github-app-token`](https://github.com/actions/create-github-app-token), so reviews arrive as the App's `[bot]` login; or
* a dedicated machine user's personal access token.
A supplied token needs `pull-requests: write` to publish. `contents: write` is optional and buys exactly one thing: reopening a resolved thread whose finding still requires changes. GitHub files thread resolve and unresolve under Contents, so without write there the reviewer republishes the finding as a new comment. Whether an App's approving review satisfies a required-approving-review rule is decided by the App installation's write access, not by the token's scopes. Mint the token in a step before the Action, for example with [`actions/create-github-app-token`](https://github.com/actions/create-github-app-token), and pass its output as `github-token`.
### `approver-logins`
A comment can instruct Tessl to approve a pull request rather than review it, which skips the review. The same allowlist also permits requesting a full re-review of the whole change instead of the narrower incremental round, so a login named here gains both privileged intents. Repository owners, members, and collaborators may already do both, by the association `allowed-associations` reads. A GitHub App cannot: it comments with association `NONE` whatever its permissions, so no association names one. List a login here, carrying the `[bot]` suffix the event payload spells (capitalization does not matter), to permit that specific commenter. Naming a login here also admits it past `allowed-associations` for an ordinary review, so read the two inputs together. Empty names no one and does not stop a member using either.
## Outputs
A later step in the same job can read these once the Action step has an `id`. Give the `uses:` step `id: review`, then reference `steps.review.outputs.`.
| Output | Meaning |
| ----------------- | ---------------------------------------------------------------- |
| `status` | Terminal Action status. |
| `head-sha` | Exact reviewed pull-request head SHA. |
| `review-id` | Created or reused GitHub review ID, when available. |
| `result-path` | Absolute path to the structured CLI result on the runner. |
| `result-artifact` | Name of the retained public result artifact on the workflow run. |
Use the outputs for reporting and workflow coordination. Do not add a second review publisher: publication, retry reconciliation, and duplicate prevention belong to the Tessl CLI the Action runs, and a second publisher gives the repository two paths that can disagree.
# Improving agent code quality
Turn recurring agent mistakes into fixes. Mine PRs and session logs with the Tessl Agent, then prove the fix with evals.
{% hint style="info" %}
**Takeaways:** After reading this page you will know how to identify concrete quality problems in agent-written code using the `find-optimizations` skill, how to turn those findings into actionable tickets, how to fix the issues, and how to set up a weekly automated scan so the process runs continuously — all driven through the `tessl agent`.
{% endhint %}
This tutorial starts from a concrete symptom: agents are getting something wrong repeatedly. It covers finding what the pattern is, filing tickets, fixing the root cause, and automating the scan so it runs on its own.
## The core workflow
1. Identify the problem area (e.g. "agents are getting the frontend layout wrong")
2. Run `find-optimizations` to extract patterns from PR review history
3. File tickets for the findings
4. Fix the issues by improving skills, rules, or verifiers
5. Set up a scheduled scan to catch new patterns before they accumulate
## Prerequisites
* Tessl installed and initialized (`tessl init`)
* Authenticated (`tessl login`)
* Access to a workspace with at least one repository connected
## Step 1: Find optimization opportunities
The `find-optimizations` skill reads PR review history and CI run results to extract patterns where agents needed corrections, then proposes improvements that would prevent those corrections in the future.
The `tessl agent` ships with the `tessl/harness-engineering` plugin pre-bundled, so `find-optimizations` is available without installing anything.
{% hint style="info" %}
Prefer your own coding agent? Install the plugin with `tessl install tessl/harness-engineering` and the skill becomes available there too. The rest of this tutorial assumes the `tessl agent`.
{% endhint %}
Give the agent a description of the mistake you are seeing plus a specific PR or time range to look at:
> Agents keep breaking our frontend layout. Look over PRs from the last 2 weeks and tell me the pattern.
The skill collects PR review comments, review summaries, CI run results, and the diffs of commits that addressed them. It categorizes each piece of feedback into an improvement type and proposes a concrete next step.
A typical output looks like this:
```
1. Type: rule
Summary: Agents are not checking for null session before accessing user properties
Evidence: PRs #1189, #1201, #1218 — reviewer corrected undefined access three times
Suggested approach: Add a rule in plugins/frontend/rules/ that instructs agents to
always check session?.user before accessing nested properties
...
```
The skill does not make any changes. It only produces output for you to review.
## Step 2: File tickets for the findings
Once you have the numbered list of findings, create tickets for the ones worth fixing. The `tessl agent` can create them directly. Refer back to the findings by number:
> Create a ticket from item 2.
For each ticket, the agent includes the evidence (PR numbers), the proposed improvement type, and the suggested approach. This gives whoever implements the fix enough context to act without re-running the analysis.
The `tessl agent` builds up memory about how you like to create and assign tickets — which issue tracker you use, how you format titles, who things get assigned to. It records this under `.tessl/memory/preferences/` (run `/setup-memory` if it has not been initialized yet), so after the first ticket you rarely have to repeat yourself. The next time you say "file a ticket from item 1," it already knows where it goes.
## Step 3: Fix the issues
Each ticket identifies the improvement type. Ask the `tessl agent` to implement the fix — it uses its `plugin-creator` skill to decide where the change belongs and to scaffold and validate it:
> Implement the fix from item 1 — a rule that makes agents check `session?.user` before accessing nested properties.
The approach the agent takes depends on the type:
**Rule** — an always-on instruction that every agent reads on every task. Rules are the right tool for conventions and constraints that apply without exception.
**Skill** — a procedural workflow the agent activates for specific tasks. Skills are the right tool when the fix involves a multi-step process (e.g. "when creating a route, first check the registry, then create the route, then register it").
**Verifier:** an LLM-as-judge check on committed files. Verifiers are the right tool when the fix is a binary, observable invariant about file structure (e.g. "component files must export at least one element with data-testid"). See [Verifiers overview](/codifying-and-enforcing-your-skill-standards/verifiers-overview) to compare verifiers with rules, skills, and linters, then [Verify agent changes in CI](/codifying-and-enforcing-your-skill-standards/verify-agent-changes-in-ci) to set up the check.
**Refactor** — structural code changes that make the right pattern easier to follow, paired with a rule or verifier to enforce the resulting convention going forward.
## Step 4: Verify the improvement
After implementing a fix, confirm it helps. Use evals to measure the impact of your context changes on agent task completion. Ask the `tessl agent` to set this up — it generates scenarios from commits in the problem area and runs the eval with and without the new context:
> Generate eval scenarios from PRs #1189, #1201, and #1218, then run the eval with and without my new frontend-skills plugin and compare the scores.
Under the hood the agent runs `tessl scenario generate` to build scenarios from those commits, then `tessl eval run` twice — once as a baseline and once with `--context` pointed at the new plugin. If the with-context variant scores higher on the criteria that correspond to the problem area, the fix is working.
To gate skill quality in CI so regressions are caught automatically, ask the agent to wire `tessl review run --json --threshold 80` into a check — it exits non-zero if the skill quality score drops below 80%.
## Step 5: Automate the weekly scan
Once the manual process is familiar, automate it so the scan runs without prompting. Ask the `tessl agent` to set up the schedule — it uses its `workflow-automator` skill to build the CI workflow and pick sensible defaults:
> Set up a weekly job to find future optimizations.
The agent runs `find-optimizations` headlessly with `tessl launch skill find-optimizations --agent tessl-agent`, passing a short static `--instructions` string (any dynamic content like date ranges is handled by the agent reading repository files). The defaults it chooses, and how you might change them:
* **A weekly schedule plus manual dispatch** — a Monday-morning cron with a `workflow_dispatch` trigger so you can also run it on demand. Adjust the cadence to match how fast your PR volume grows.
* **Findings written to an artifact** — the scan output is uploaded so the team can review it without re-running the analysis. Point it at a file, an issue, or a Slack message depending on where your team looks.
* **`TESSL_TOKEN` and `ANTHROPIC_API_KEY` from repository secrets** — the agent confirms these exist and walks you through creating any that are missing.
Review the weekly output. When findings recur across multiple weeks, escalate them to tickets and implementation work. This creates a continuous feedback loop: agents write code, the scan surfaces patterns, you improve the skills and rules, agents get better.
## Next steps
* Catch issues at pull request time before they accumulate into patterns by [setting up Tessl Code Review](/tutorials/setting-up-agentic-code-review). Add `tessl change verify` separately when a recurring problem can be expressed as a targeted, observable invariant.
* Discover other manual workflows in your repository that can be automated with the [Automating repetitive tasks](/tutorials/automating-repetitive-tasks) tutorial and the `find-automations` skill.
# Automating repetitive tasks
Identify repetitive work in your development loop and turn it into repeatable, automated workflows with the Tessl Agent.
{% hint style="info" %}
Looking for the easiest way to automate recurring work? See [Schedules](/automations/overview/overview), no CI configuration needed.
{% endhint %}
{% hint style="info" %}
**Takeaways:** After reading this page you will know how to use the `find-automations` skill to identify manual workflows in your repository that should be automated, how to turn findings into implementation tickets, and how to have the `tessl agent` build a CI workflow that runs an agent on a schedule to handle recurring work.
{% endhint %}
Every repository accumulates manual chores: the same kind of dependency update PR every week, a maintainer who manually applies the same changelog format to every release, a reviewer who leaves the same comment about a missing label. These are automation candidates. The `find-automations` skill reads your PR history to surface them.
## The core workflow
1. Run `find-automations` to identify manual workflows in your repository
2. Review the numbered list of automation candidates
3. File tickets for the ones worth building
4. Have the `tessl agent` build the automation as a CI workflow
5. Run `find-automations` on a schedule to catch new candidates as they emerge
## Prerequisites
* Tessl installed and initialized (`tessl init`)
* Authenticated (`tessl login`)
* `gh` CLI installed and authenticated (for reading PR data)
* Access to a workspace
## Step 1: Find automation opportunities
The `find-automations` skill reads recent PR history to identify manual workflows, recurring chores, and coordination patterns that could be automated.
The `tessl agent` ships with the `tessl/harness-engineering` plugin pre-bundled, so `find-automations` is available without installing anything.
{% hint style="info" %}
Prefer your own coding agent? Install the plugin with `tessl install tessl/harness-engineering` and the skill becomes available there too. The rest of this tutorial assumes the `tessl agent`.
{% endhint %}
Ask the agent to run it:
> Run find-automations on this repo and show me the candidates.
The skill inspects the last 90 days of PR history. For each candidate it finds, it produces a structured output entry. A typical output looks like this:
```
Summary: Found 4 clear automation candidates across 3 months of PR history.
1. Title: Automate weekly dependency updates
Summary: The same contributor opens a dependency update PR every Monday morning.
Pattern Type: established
Why Automate: Predictable, low-judgment, repeating chore.
Evidence: PRs #1180, #1190, #1202, #1215, #1223 — all titled "chore: update deps",
all opened by @alice between 9am and 10am UTC on Mondays.
Suggested Execution Mode: scheduled
Suggested Trigger: Weekly on Monday morning
Manual Trigger: none
Implementation Direction: Run npm outdated, apply compatible updates, run tests,
open a PR if anything changed. Skip major bumps.
...
```
The skill is read-only. It does not modify any files, create commits, or open issues.
## Step 2: File tickets for the candidates
Review the numbered list and pick the candidates worth building. The `tessl agent` can create the tickets directly — refer to findings by number:
> Create a ticket from item 1.
For each ticket, the agent includes the evidence, the suggested execution mode, and the implementation direction from the finding. This gives the implementer enough context to act without re-running the analysis.
The `tessl agent` builds up memory about how you like to create and assign tickets — which issue tracker you use, how you format titles, who things get assigned to. It records this under `.tessl/memory/preferences/` (run `/setup-memory` if it has not been initialized yet), so after the first ticket you rarely have to repeat yourself.
## Step 3: Build the automation
Each finding includes an implementation direction. Ask the `tessl agent` to build it — it uses its `workflow-automator` skill to classify the task, create any plugin it needs, set up CI secrets, and write the workflow. It runs the underlying commands and reports them back; you stay in control of the design decisions.
### Recurring chores
For purely mechanical tasks — applying a label, posting a comment, running a script — no agent is needed at runtime. Ask the `tessl agent` to set up a standard GitHub Actions workflow:
> Build the stale-PR automation from item 3 as a scheduled GitHub Actions workflow.
The agent wires a plain Action (for example, `actions/stale`) on a daily schedule. The settings it chooses — the stale label, the inactivity window, the message — come straight from the finding's implementation direction, and you can adjust any of them.
### Agent-driven tasks
For tasks that require judgment — writing changelog entries, reviewing code, updating documentation — the automation runs an agent headlessly with `tessl launch skill`.
`tessl launch skill --agent ` is the entrypoint for agent workflows: it runs an installed plugin skill through an agent in a CI environment, with per-run inputs passed via a short `--instructions` string. The `--agent` flag selects the backend.
The pattern is:
1. Create a plugin that encodes what the agent should do
2. Run the plugin with `tessl launch skill` in a CI workflow
Ask the `tessl agent` to do both:
> Build the release-notes automation from item 2: create a plugin that generates a formatted changelog block, then run it from a GitHub Actions workflow on release-branch pushes.
As it works, the agent runs the relevant CLI commands and names what it creates:
* `tessl plugin new` — scaffolds the plugin and skill ([reference](/reference/cli-commands#tessl-plugin-new))
* `tessl plugin lint` and `tessl review` — validate the plugin and skill ([reference](/reference/cli-commands#tessl-plugin-lint))
* `tessl plugin publish` — publishes it so CI can install it ([reference](/reference/cli-commands#tessl-plugin-publish))
* `tessl install` — installs the plugin in the workflow ([reference](/reference/cli-commands#tessl-install))
* `tessl launch skill --agent tessl-agent --yolo` — runs the skill headlessly in CI
The defaults the agent chooses for the workflow, and how you might change them:
* **`--agent tessl-agent`** — the workflow runs the Tessl built-in agent. The `tessl agent` is particularly good at harness and repo-maintenance tasks like these. For automations that build product features, you may prefer a coding agent backend (`claude-code`, `codex`, `cursor`); pass it to `--agent` instead.
* **`--yolo`** — lets the agent apply edits without prompting, which a headless CI run requires.
## Step 4: Run find-automations on a schedule
As your repository grows, new patterns emerge. Set up a weekly scan so new automation candidates surface before they become entrenched manual chores. Ask the `tessl agent` to schedule it:
> Set up a weekly GitHub Actions job that runs find-automations over the last 7 days and saves the candidate list where the team can review it.
The agent runs `find-automations` headlessly with `tessl launch skill find-automations --agent tessl-agent` on a weekly cron plus `workflow_dispatch`, and uploads the findings as an artifact for the team to review. Adjust the cadence and the output destination to fit your team.
Review the weekly artifact. When candidates appear across multiple weeks, escalate them to tickets. This prevents the backlog of manual chores from growing quietly.
## Next steps
* Use [Improving agent code quality](/tutorials/improving-agent-code-quality) and the `find-optimizations` skill to find recurring patterns in PR review feedback that suggest improvements to skills and rules, not just workflows.
* Use [Tessl Code Review](/tutorials/setting-up-agentic-code-review) for pull request findings, and add `tessl change verify` separately to enforce structural invariants automatically.
* Combine both scans into a single scheduled workflow that runs both skills and aggregates their findings.
# Automations overview
Automate recurring work by declaring schedules in your tessl.json and pushing them to your default branch.
Automations run plugins on a schedule so recurring work happens without CI or GitHub Actions configuration.
## Define an automation in tessl.json
The primary way to create an automation is to declare a schedule in your project's `tessl.json`. Add a `schedules` block and push it to your default branch. Tessl syncs the manifest and creates the schedule when it can resolve the project and apply the entry. The schedule lives next to the code it runs against, so it is reviewed and version-controlled like any other change.
See [Schedules](/automations/overview/overview) for prerequisites, the `schedules` block reference, validation, and schedule behavior.
## Example schedules
{% content-ref url="/pages/jqRZh2ForMPs2Jpj4zox" %}
[Example Schedules](/automations/overview/overview/example-schedules)
{% endcontent-ref %}
# Schedules
No CI setup, no GitHub Actions config. Declare a schedule in your tessl.json, push to your default branch, and Tessl runs it for you.
{% hint style="info" %}
**Takeaways:**
* A schedule runs a plugin against a repo on a cron, with no CI or GitHub Actions config needed.
* The primary way to create one is a `schedules` block in your `tessl.json`. Push to your default branch and Tessl syncs it.
* An unparseable or invalid file never deletes anything. Removing a schedule from a valid file is what deletes it.
* Run `tessl schedule validate` before you push to catch errors locally.
* When repo-defined schedules are enabled for your organization, they are read-only in the web app and CLI. Change the file to change them.
{% endhint %}
## What is a schedule?
A schedule runs a plugin on a cron. You pick a plugin, a repo, and a time, and Tessl runs the plugin against that repo on that schedule. Each time the schedule fires, Tessl starts a cloud run and reports the result back so you can see what happened.
Tessl skips a tick if the previous run from the same schedule is still active when the next one would start. There is no queue: a skipped tick does not run later.
Think of it as two parts working together. The **plugin** describes the task: it tells the agent what to do. The **schedule** describes the timing: it tells Tessl when to do it.
## What you need first
* A Tessl account with a workspace.
* GitHub connected to your workspace. See [Connect Tessl to GitHub](/distribute/connect-tessl-to-github).
* A plugin that describes the task. See [Create a plugin](/creating-skills-and-plugins/create-a-plugin).
* An environment. A scheduled run cannot mint its own GitHub token, so it needs a `GITHUB_TOKEN` from its environment to check out your repo and open PRs. The environment also holds any other secrets the plugin needs. See [Environments](/automations/environments).
## Define a schedule in tessl.json
The primary way to create a schedule is to declare it in your project's `tessl.json`. Add a `schedules` block, push it to your default branch, and Tessl reads the file and creates the schedule for you. The schedule lives next to the code it runs against, so it is reviewed and version-controlled like any other change.
The `name` field helps Tessl resolve the manifest to a project. Use the `workspace/project` format, for example `"name": "my-org/my-app"`. Before schedules sync, an active project must exist in that workspace, be connected to the same GitHub repository, and use the manifest's directory as its repository subpath. The GitHub App installation must currently have access to the workspace. When Tessl resolves that binding, schedules from the manifest appear under the project's **Schedules** tab in the web app. Schedule sync does not create or reassign projects.
Tessl discovers and syncs each `tessl.json` in a repository independently. In a monorepo, a manifest such as `apps/backend/tessl.json` manages only its own schedules, without affecting the root or sibling manifests. Deleting that subdirectory manifest removes only the schedules managed by that manifest in workspaces that the GitHub App installation can still access. Schedules in workspaces it can no longer access are not reconciled by that deletion.
### Let the schedule-setup skill do it for you
If you'd rather describe the schedule in plain language than write the JSON yourself, install [tessl/schedule-setup](https://tessl.io/registry/tessl/schedule-setup).
When invoking the skill, tell your agent what you want to run and when ("run the docs audit every Monday at 9am London time using the production environment"). The skill asks clarifying questions one at a time, picks the most readable schedule format, writes and validates the entry, and explains what happens on push. It can also author a new repo-local skill for your schedule to use if you don't have one yet.
### The schedules block
`schedules` is a map of schedule key to schedule entry. The key is the schedule's stable identity: a lowercase kebab-case slug, not a display label. Renaming a key removes the old schedule from the file and adds the new one. Sync validates the complete change before deleting the old schedule and creating the new one. If the new entry fails validation, neither operation is applied.
Each entry needs `skill`, `environment`, and one timing field. Use either `cron` or its alias, `schedule`, but not both.
| Field | Required | What it is |
| -------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `skill` | Yes | The plugin to run: a registry ref `workspace/plugin[@version][#skill]`, or a repo-local `file:path`. |
| `cron` | One of two | A five-field cron expression, supported shorthand, or structured schedule object. The minimum interval between runs is 5 minutes. |
| `schedule` | One of two | Alias for `cron`. Use one timing field, not both. |
| `environment` | Yes | The workspace environment the run executes in, referenced by **name**. It supplies the GitHub token and any other secrets the plugin needs. |
| `timezone` | No | IANA timezone the cron is interpreted in (for example `America/New_York`). Defaults to `UTC`. |
| `baseBranch` | No | The branch each run checks out and opens PRs against. When omitted, each run uses the project's Loop default branch or the repository default. |
| `workdir` | No | A subdirectory of the repo the plugin runs in. |
| `agent` | No | Which agent runs the plugin (`claude-code` or `claude` (default), `cursor`, `codex`, `gemini`, `tessl` or `tessl-agent`). |
| `model` | No | Which model the agent uses (e.g. `claude-sonnet-4-6` for `claude`, `auto` for `cursor`, `gpt-5.4` for `codex`). |
| `inputs` | No | Skill input values, as a map of string keys to string values. |
| `instructions` | No | Free-text directions appended to the plugin prompt for this schedule. |
| `description` | No | A human-readable description of the schedule. |
Raw cron expressions have five fields: minute, hour, day of month, month, and day of week. `0 9 * * 5` means "at 9:00 on every Friday". `0 8 * * *` means "at 8:00 every day".
You can also use these shorthand strings:
* `hourly`
* `daily at HH:MM`
* `weekdays at HH:MM`
* `weekly on DAY at HH:MM`
* `monthly on Nth at HH:MM`
* `every N minutes` or `every N hours`, when `N` divides evenly into 60 or 24
* `every N minutes between HH:MM-HH:MM`; the start is inclusive and the end is exclusive, and multi-hour windows use whole-hour endpoints
* `every N minutes on weekdays`
For schedules that don't fit those patterns, use an object with `minute`, `hour`, `day`, `month`, and `weekday` fields. Omitted fields mean every value. Numeric fields accept a number, a list of numbers, `{ "every": N }`, or `{ "between": [N, M] }`. `month` and `weekday` also accept names or lists of names.
```json
{
"cron": {
"minute": { "every": 15 },
"hour": { "between": [9, 17] },
"weekday": ["mon", "tue", "wed", "thu", "fri"]
}
}
```
Tessl compiles shorthand strings and objects to cron before validation and storage. The timezone and 5-minute minimum apply to every input form.
### A complete example
```json
{
"name": "my-org/my-repo",
"schedules": {
"weekly-changelog": {
"skill": "tessl/changelog-writer",
"schedule": "weekly on friday at 09:00",
"environment": "production",
"timezone": "America/New_York",
"description": "Draft the weekly changelog every Friday morning."
},
"api-docs-audit": {
"skill": "tessl/docs-audit",
"cron": "weekly on monday at 08:00",
"environment": "production",
"instructions": "Focus on the API reference section only."
}
}
}
```
This declares two schedules. `weekly-changelog` runs the `changelog-writer` plugin every Friday at 9:00 New York time. `api-docs-audit` runs the `docs-audit` plugin every Monday at 8:00 UTC, steered at the API reference by its `instructions`.
### Behaviors to know
Schedule identity is the key name. Renaming a key is therefore a delete and a create, not an update. For example, changing `nightly-scan` to `nightly-check` deletes the old schedule and its Temporal schedule, and creates a new schedule with the new key. Prior launch runs are preserved but are no longer linked to a schedule. If the new entry fails validation, neither the deletion nor the creation is applied.
The `schedules` block is the source of truth. Removing the block from `tessl.json`, or setting it to `{}`, means “no schedules” and deletes all schedules managed by that manifest. To recover from an accidental removal, revert the commit and push again.
### Validate before you push
Run `tessl schedule validate` before you push to catch errors locally. You can also [run the validator in your CI workflow](/automations/overview/overview/validate-in-ci):
```bash
tessl schedule validate
```
It reads your `tessl.json`, checks the `schedules` block, and reports every problem against the schedule key it belongs to. It exits non-zero when the block is invalid, so it also works as a CI check. A file with no `schedules` block is valid.
`validate` checks the file only: its shape, its cron expressions, and the minimum interval. It cannot check what your workspace decides when the file syncs, so a file that passes here can still be rejected at sync time. It does **not** check:
* whether the plugin reference resolves to a plugin your workspace can use
* whether the named environment exists in your workspace, or carries a GitHub token
* whether the agent and model are in your organization's catalogue
* the limit on active schedules per workspace
## How the sync works
When you push to your default branch, Tessl reads the `schedules` block and reconciles schedules across every workspace reachable through your GitHub App installation. For each workspace where the named environment resolves:
* A key in the file that has no schedule yet is **created**.
* A key whose entry changed is **updated**.
* A key that was removed from the file is **deleted**.
If an entry cannot be applied in a given workspace (for example, the named environment does not exist there, or the workspace has reached its active-schedule limit), that entry is skipped for that workspace. Other entries and other workspaces are still reconciled.
Tessl only reads the `schedules` block. Changes to other parts of `tessl.json` are ignored. Most pushes that do not touch `tessl.json` are also ignored. A force push, branch creation, or push with an empty or truncated commit list bypasses that optimization. Tessl reads the manifest at the pushed revision and attempts reconciliation; individual entries can still be skipped if they cannot be applied.
The sync runs off the default branch only. A schedule declared on a feature branch does not sync until the change reaches your default branch.
## The safety model
Tessl never deletes a schedule because it could not understand your file. Deletion only ever follows from a file it read cleanly.
* **Unparseable or invalid: nothing changes.** If the file is malformed JSON, cannot be read, or its `schedules` block fails validation, Tessl makes no changes at all. A typo in the block does not delete your schedules; it leaves them exactly as they are. Fix the file and push again.
* **Valid and read cleanly: the file wins.** Once Tessl reads a valid file, the file is the source of truth. Remove one key and that schedule is deleted. Remove the whole `schedules` block, or delete a `tessl.json`, and every repo-defined schedule managed by that manifest is deleted.
So the only way to delete a repo-defined schedule is to remove it from a valid file and push. An error in the file is always safe.
## Read-only in the web app and CLI
When repo-defined schedules are enabled for your organization, a schedule defined in `tessl.json` is read-only from the web app and the CLI. Attempts to edit, pause, resume, or delete it through those surfaces return an error telling you it is defined in `tessl.json`. To change it, change the file and push.
You can still watch a repo-defined schedule and its runs in the web app and CLI. Only mutations are blocked.
A repo-defined schedule reflects the file for entries that were successfully applied at sync time. A skipped new entry is absent until the next sync reconciles it. A skipped update leaves the existing schedule at its previous configuration, and it can continue running until a later sync applies the update.
## Create from the CLI or web app (alternative)
You can also create a schedule directly from the CLI or the web app, without a `tessl.json` block. This is the older path and is not version-controlled. It may be disabled for some users.
{% tabs %}
{% tab title="CLI" %}
Use `tessl schedule create`. Pass the plugin as the first argument, then the repo, the cron, and the environment:
```bash
tessl schedule create tessl/changelog-writer \
--repo my-org/my-repo \
--cron "0 9 * * 5" \
--environment production
```
This runs the `changelog-writer` plugin against `my-org/my-repo` every Friday at 9:00 UTC.
Common flags:
| Flag | What it does |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--repo` | The repository the plugin runs against. Required. |
| `--cron` | When the schedule fires, as a cron expression. Required. |
| `--environment` | The workspace environment the run executes in. It supplies the GitHub token and any other secrets or API keys the plugin needs. Required when you specify the plugin, repo, and environment directly. |
| `--timezone` | The timezone for the cron expression. Optional; defaults to UTC. |
| `--agent` | Which agent runs the plugin (for example `claude-code`, `cursor`, `codex`, `gemini`, or `tessl-agent`). Optional. |
| `--model` | Which model the agent uses. Optional. |
| `--instructions` | Extra directions layered on top of the plugin for this schedule. Optional. |
| `--base-branch` | The branch to check out and open PRs against. Optional. |
The cron expression has five fields: minute, hour, day of month, month, and day of week. `0 9 * * 5` means "at 9:00 UTC on every Friday". `0 8 * * *` means "at 8:00 UTC every day".
Use `--instructions` to point a generic plugin at a specific job:
```bash
tessl schedule create tessl/docs-audit \
--repo my-org/my-repo \
--cron "0 8 * * *" \
--environment production \
--instructions "Focus on the API reference section only"
```
{% endtab %}
{% tab title="Web app" %}
Open **Projects > \[project] > Schedules** and choose **Create schedule**. The form asks for the schedule (cron), a name, a description, and an environment. These are the primary fields.
Below the environment and mode selection is an **Advanced options** control. Expand it to set the agent, model, inputs, instructions, and base branch. Leave it collapsed to accept the defaults.
{% endtab %}
{% endtabs %}
## How instructions work
The `instructions` field layers extra directions on top of whatever the plugin already says. The plugin is the base recipe; instructions are the per-schedule customization. The plugin still runs its normal task. The instructions steer it for this one schedule.
This lets you reuse one plugin for several jobs. The same `docs-audit` plugin, pointed two ways in one `schedules` block:
```json
{
"schedules": {
"audit-api-reference": {
"skill": "tessl/docs-audit",
"cron": "0 8 * * 1",
"environment": "production",
"instructions": "Focus on the API reference section only."
},
"audit-getting-started": {
"skill": "tessl/docs-audit",
"cron": "0 8 * * 3",
"environment": "production",
"instructions": "Focus on the getting-started guide and its code samples."
}
}
}
```
Same plugin, two schedules, two different jobs.
## Monitoring your runs
Each schedule keeps a table of its past runs. Open a schedule in the web app to see its full run history, including output and duration. From the CLI, `tessl schedule runs ` lists runs with their ID, status, skill, repo, workspace, creator, and creation time.
| Status | What it means | What to do |
| ------------ | ------------------------------------------------------------ | ---------------------------- |
| In Progress | Still running | Wait |
| Completed | The skill finished and reported a result | Nothing. Check the output. |
| Agent failed | The skill reported that it could not complete the task | Check the output for why |
| Error | The platform failed, or the run ended without a skill result | Check the run's error detail |
| Cancelled | Someone stopped the run | Nothing |
## Next steps
* [Environments](/automations/environments)
* [Connect Tessl to GitHub](/distribute/connect-tessl-to-github)
* [Create a plugin](/creating-skills-and-plugins/create-a-plugin)
* [Keep docs in sync](/automations/overview/overview/example-schedules/use-case-docs-audit)
* [Weekly changelog](/automations/overview/overview/example-schedules/use-case-changelog)
* [Review pattern mining](/automations/overview/overview/example-schedules/use-case-review-miner)
* [Test health monitor](/automations/overview/overview/example-schedules/use-case-test-health)
* [Release readiness check](/automations/overview/overview/example-schedules/use-case-release-check)
# Validate schedules in CI
Add tessl schedule validation to your continuous integration workflow.
Add `tessl schedule validate` to your CI workflow to catch errors in the `schedules` block of `tessl.json` before a change is merged. This is a manual setup: add the step to your own CI configuration.
## What it checks
The command reads `tessl.json` and validates the file without connecting to a Tessl workspace. It checks:
* The shape of the `schedules` block and each schedule entry.
* Schedule field names, including required fields and the rule that each entry uses either `cron` or `schedule`, but not both.
* Field types, including structured schedule values and string-only input values.
* Cron syntax and supported human-readable or structured schedule forms.
* The minimum interval between runs, which is five minutes.
The command reports every problem it finds and exits with a non-zero status when the file is invalid. CI uses that status to fail the check.
## What it does not check
This command validates the file only. It does not check server-side resources or workspace limits, including:
* Whether the named environment exists or contains the required secrets.
* Whether the referenced skill or plugin is installed and available to the workspace.
* Whether the workspace has capacity for another active schedule.
Those checks happen when Tessl syncs the file for a project and workspace.
## GitHub Actions
The following workflow installs the Tessl CLI and runs the validator on pull requests that change `tessl.json`:
```yaml
name: Validate Tessl schedules
on:
pull_request:
paths:
- tessl.json
- .github/workflows/validate-tessl-schedules.yml
jobs:
validate-schedules:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Install Tessl CLI
uses: tesslio/setup-tessl@v2
- name: Validate Tessl schedules
run: tessl schedule validate
```
The validation step does not need a Tessl token because it checks the local file. The CLI's non-zero exit status fails the GitHub Actions job when a schedule is invalid.
## File checks and server checks
This check catches file-level issues before merge, such as a misspelled field, an invalid cron expression, or a schedule that runs too often. After a valid file is merged and synced, Tessl performs server-side checks. For example, a nonexistent environment can still cause a validation error on the project's **Schedules** page after sync.
For the full schedule format, see [Schedules](/automations/overview/overview).
# Example Schedules
The following are examples of schedules you can get started with easily.
{% content-ref url="/pages/JLlCkfiAtjCVwoVPJGTN" %}
[Keep docs in sync](/automations/overview/overview/example-schedules/use-case-docs-audit)
{% endcontent-ref %}
{% content-ref url="/pages/HWaXqt9Dn6xIrkqsbmHh" %}
[Weekly changelog](/automations/overview/overview/example-schedules/use-case-changelog)
{% endcontent-ref %}
{% content-ref url="/pages/EaQxQY9dCJ7W5ygVmXG5" %}
[Review pattern mining](/automations/overview/overview/example-schedules/use-case-review-miner)
{% endcontent-ref %}
{% content-ref url="/pages/T7JswwvbhpNItJlwIBtN" %}
[Test health monitor](/automations/overview/overview/example-schedules/use-case-test-health)
{% endcontent-ref %}
{% content-ref url="/pages/zXsGx4834tQhkrWfh6yg" %}
[Release readiness check](/automations/overview/overview/example-schedules/use-case-release-check)
{% endcontent-ref %}
# Keep docs in sync
Keep your docs in sync with your code, automatically. A scheduled docs audit checks whether the docs still match the code and opens a PR when they have drifted.
{% hint style="info" %}
**Goal:** Keep your docs in sync with your code, automatically.
{% endhint %}
## What it does
Every morning, a schedule checks whether the docs still match the code. If they have drifted and no audit PR is already open, it opens a PR with the fix. This catches the common kind of rot where someone changes an API but forgets to update the docs, so the docs quietly go stale.
## The plugin
[`tessl/docs-audit`](https://tessl.io/registry/tessl/docs-audit) reads the code and the docs, finds where they disagree, and opens a PR that reconciles them. Install it with:
```bash
$ tessl install tessl/docs-audit
```
## Define the schedule
Run it every day at 7:00 UTC. Add this entry to the `schedules` block in your project's `tessl.json`, and keep any other entries already in that block. Replace `production` with the name of your environment (see the [Schedules overview](/automations/overview/overview) for the prerequisites).
{% stepper %}
{% step %}
**Add the schedule entry**
```json
{
"schedules": {
"docs-audit": {
"skill": "tessl/docs-audit",
"schedule": "daily at 07:00",
"environment": "production"
}
}
}
```
{% endstep %}
{% step %}
**Validate and push**
Validation always checks the local file. For an authenticated linked project that can reach Tessl, it also gives an advisory warning when current workspace capacity may not accommodate additional schedules. Commit and push the change, then confirm Tessl applied the schedule in your workspace before checking its run history.
```bash
$ tessl schedule validate
$ git add tessl.json
$ git commit -m "chore(docs): add docs audit schedule"
$ git push
```
{% endstep %}
{% step %}
**Check the runs**
Open the schedule in the web app, or run `tessl schedule runs ` to see its run history.
{% endstep %}
{% endstepper %}
## Customize with instructions
Scope the audit to the part of the docs that drifts most by adding `instructions` to the same schedule entry. Keep all other entries in the `schedules` block:
```json
{
"schedules": {
"docs-audit": {
"skill": "tessl/docs-audit",
"schedule": "daily at 07:00",
"environment": "production",
"instructions": "Only check the API reference against the route handlers in src/api"
}
}
}
```
## Create your own
Want a different behavior? [Create your own plugin](/creating-skills-and-plugins/create-a-plugin) that reads the code and the docs and reconciles them your way.
# Weekly changelog
Get a changelog draft every week without anyone remembering to write it. A scheduled changelog writer scans the week's merged PRs and opens a PR with the draft.
{% hint style="info" %}
**Goal:** Get a changelog draft every Friday without anyone remembering to write it.
{% endhint %}
## What it does
Every Friday, a schedule scans the pull requests merged since the last changelog entry (falling back to the last 7 days if no entry exists) and drafts the next one. The plugin reads the merged work and writes the entry in your changelog's style, then opens a PR with the draft. If a draft PR from a previous run is still open, it skips opening another one.
## The plugin
[`tessl/changelog-writer`](https://tessl.io/registry/tessl/changelog-writer) scans the PRs merged since the last entry, drafts the next one, and opens a PR with it. Install it with:
```bash
$ tessl install tessl/changelog-writer
```
## Define the schedule
Run it every Friday at 16:00 UTC. Add this entry to the `schedules` block in your project's `tessl.json`, and keep any other entries already in that block. Replace `production` with the name of your environment (see the [Schedules overview](/automations/overview/overview) for the prerequisites).
{% stepper %}
{% step %}
**Add the schedule entry**
```json
{
"schedules": {
"weekly-changelog": {
"skill": "tessl/changelog-writer",
"schedule": "weekly on friday at 16:00",
"environment": "production"
}
}
}
```
{% endstep %}
{% step %}
**Validate and push**
Validation always checks the local file. For an authenticated linked project that can reach Tessl, it also gives an advisory warning when current workspace capacity may not accommodate additional schedules. Commit and push the change, then confirm Tessl applied the schedule in your workspace before checking its run history.
```bash
$ tessl schedule validate
$ git add tessl.json
$ git commit -m "chore(docs): add weekly changelog schedule"
$ git push
```
{% endstep %}
{% step %}
**Check the runs**
Open the schedule in the web app, or run `tessl schedule runs ` to see its run history.
{% endstep %}
{% endstepper %}
## Customize with instructions
Match your changelog's house style by adding `instructions` to the same schedule entry. Keep all other entries in the `schedules` block:
```json
{
"schedules": {
"weekly-changelog": {
"skill": "tessl/changelog-writer",
"schedule": "weekly on friday at 16:00",
"environment": "production",
"instructions": "Group entries under Added, Fixed, and Changed. Skip dependency bumps."
}
}
}
```
## Create your own
Want a different format? [Create your own plugin](/creating-skills-and-plugins/create-a-plugin) that reads the git log and writes an entry your way.
# Review pattern mining
Stop repeating the same code-review comment. A scheduled review miner reads recent reviews, finds the feedback that keeps coming up, and proposes a lint rule for it.
{% hint style="info" %}
**Goal:** Stop reviewers repeating the same comment by turning it into a rule.
{% endhint %}
## What it does
Weekly, a schedule reads the last 50 code reviews and looks for feedback that keeps coming up. If reviewers keep saying the same thing, the plugin proposes a lint rule, an automated check, or a documented convention to address it. Reviewers spend less time repeating the same comment and more time on the decisions that need their judgment.
## The plugin
[`tessl/review-miner`](https://tessl.io/registry/tessl/review-miner) reads recent review comments, groups the recurring ones, and proposes a rule, check, or convention for each. Install it with:
```bash
$ tessl install tessl/review-miner
```
## Define the schedule
Run it every Monday at 9:00 UTC. Add this entry to the `schedules` block in your project's `tessl.json`, and keep any other entries already in that block. Replace `production` with the name of your environment (see the [Schedules overview](/automations/overview/overview) for the prerequisites).
{% stepper %}
{% step %}
**Add the schedule entry**
```json
{
"schedules": {
"review-miner": {
"skill": "tessl/review-miner",
"schedule": "weekly on monday at 09:00",
"environment": "production"
}
}
}
```
{% endstep %}
{% step %}
**Validate and push**
Validation always checks the local file. For an authenticated linked project that can reach Tessl, it also gives an advisory warning when current workspace capacity may not accommodate additional schedules. Commit and push the change, then confirm Tessl applied the schedule in your workspace before checking its run history.
```bash
$ tessl schedule validate
$ git add tessl.json
$ git commit -m "chore(docs): add review miner schedule"
$ git push
```
{% endstep %}
{% step %}
**Check the runs**
Open the schedule in the web app, or run `tessl schedule runs ` to see its run history.
{% endstep %}
{% endstepper %}
## Customize with instructions
Focus the search on one area by adding `instructions` to the same schedule entry. Keep all other entries in the `schedules` block:
```json
{
"schedules": {
"review-miner": {
"skill": "tessl/review-miner",
"schedule": "weekly on monday at 09:00",
"environment": "production",
"instructions": "Only look for repeated feedback about error handling and logging"
}
}
}
```
## Create your own
Want a different behavior? [Create your own plugin](/creating-skills-and-plugins/create-a-plugin) that reads recent review comments and proposes a rule your way.
# Test health monitor
Catch flaky tests before everyone learns to ignore them. A scheduled test health monitor finds flaky or repeatedly failing tests and files a ticket for each one.
{% hint style="info" %}
**Goal:** Catch flaky tests before everyone learns to re-run and ignore them.
{% endhint %}
## What it does
Daily, a schedule checks for flaky or repeatedly failing tests. It files a ticket for each test that either failed and then passed on a re-run with no code change (flaky), or failed more than once in the window with no code change to explain it. This catches test rot early, before a flaky test becomes something everyone just re-runs and ignores.
## The plugin
[`tessl/test-health`](https://tessl.io/registry/tessl/test-health) reads recent CI history, finds the unstable tests, and files a ticket for each one worth fixing. Install it with:
```bash
$ tessl install tessl/test-health
```
## Define the schedule
Run it every day at 6:00 UTC. Add this entry to the `schedules` block in your project's `tessl.json`, and keep any other entries already in that block. Replace `production` with the name of your environment (see the [Schedules overview](/automations/overview/overview) for the prerequisites).
{% stepper %}
{% step %}
**Add the schedule entry**
```json
{
"schedules": {
"test-health": {
"skill": "tessl/test-health",
"schedule": "daily at 06:00",
"environment": "production"
}
}
}
```
{% endstep %}
{% step %}
**Validate and push**
Validation always checks the local file. For an authenticated linked project that can reach Tessl, it also gives an advisory warning when current workspace capacity may not accommodate additional schedules. Commit and push the change, then confirm Tessl applied the schedule in your workspace before checking its run history.
```bash
$ tessl schedule validate
$ git add tessl.json
$ git commit -m "chore(docs): add test health schedule"
$ git push
```
{% endstep %}
{% step %}
**Check the runs**
Open the schedule in the web app, or run `tessl schedule runs ` to see its run history.
{% endstep %}
{% endstepper %}
## Customize with instructions
Set the bar for what counts by adding `instructions` to the same schedule entry. Keep all other entries in the `schedules` block:
```json
{
"schedules": {
"test-health": {
"skill": "tessl/test-health",
"schedule": "daily at 06:00",
"environment": "production",
"instructions": "Only file a ticket if a test failed 3+ times this week with no related code change"
}
}
}
```
## Create your own
Want a different behavior? [Create your own plugin](/creating-skills-and-plugins/create-a-plugin) that reads test results over time and flags the unstable ones your way.
# Release readiness check
Find release problems while there is still time to fix them. A scheduled release check verifies migrations, feature flags, the changelog, and the docs before each release window.
{% hint style="info" %}
**Goal:** Find release problems early, while there is still time to fix them.
{% endhint %}
## What it does
Before each release window, a schedule verifies the checklist: migrations are clean, feature flags are set correctly, the changelog is drafted, and the docs are up to date. Running it ahead of the release means problems surface early, while there is still time to fix them.
## The plugin
[`tessl/release-check`](https://tessl.io/registry/tessl/release-check) walks your release checklist against the changes since the last release and reports what is missing. Install it with:
```bash
$ tessl install tessl/release-check
```
## Define the schedule
Run it every Thursday at 10:00 UTC, ahead of a Friday release. Add this entry to the `schedules` block in your project's `tessl.json`, and keep any other entries already in that block. Replace `production` with the name of your environment (see the [Schedules overview](/automations/overview/overview) for the prerequisites).
{% stepper %}
{% step %}
**Add the schedule entry**
```json
{
"schedules": {
"release-check": {
"skill": "tessl/release-check",
"schedule": "weekly on thursday at 10:00",
"environment": "production"
}
}
}
```
{% endstep %}
{% step %}
**Validate and push**
Validation always checks the local file. For an authenticated linked project that can reach Tessl, it also gives an advisory warning when current workspace capacity may not accommodate additional schedules. Commit and push the change, then confirm Tessl applied the schedule in your workspace before checking its run history.
```bash
$ tessl schedule validate
$ git add tessl.json
$ git commit -m "chore(docs): add release check schedule"
$ git push
```
{% endstep %}
{% step %}
**Check the runs**
Open the schedule in the web app, or run `tessl schedule runs ` to see its run history.
{% endstep %}
{% endstepper %}
## Customize with instructions
Match your own checklist by adding `instructions` to the same schedule entry. Keep all other entries in the `schedules` block:
```json
{
"schedules": {
"release-check": {
"skill": "tessl/release-check",
"schedule": "weekly on thursday at 10:00",
"environment": "production",
"instructions": "Check that all migrations have a rollback and every new flag has a default"
}
}
}
```
## Create your own
Want a different checklist? [Create your own plugin](/creating-skills-and-plugins/create-a-plugin) that walks your release checklist and reports what is missing.
# Administrating Organizations, Workspaces, and Roles
{% hint style="info" %}
**Takeaways**
* How organizations, workspaces, and roles fit together in Tessl.
* How to set up your organization, create workspaces, and invite users with and without SSO.
* Which role to give a user, with worked examples for common team setups.
{% endhint %}
## How organizations, workspaces, and roles fit together
An **organization** is the top-level entity, usually your billing or corporate entity. Inside it, **workspaces** group skills and give role-based access to the people who work on them. A user is granted a **role** per workspace, and that role decides what they can do there: install, publish, run evals, manage members, or administer the workspace. Skills are published as plugins, so the [role](/administrators/roles) permission tables describe these same actions in terms of plugins.
* **Organization: Acme**
* **Org admin: Samira** manages all workspaces and users.
* **Workspace: engteam**
* **Manager: Jennifer** invites members and publishes.
* **Publisher: Eddie** publishes skills for the team.
* **Member: Joe** installs skills and runs reviews.
* **Workspace: dsteam**
Actions such as running evaluations and publishing happen from the CLI against the Tessl platform, and what a user can do depends on their role and the workspace selected for the task. Access to skills and features in the web app follows the same rule.
## Set up your organization
An organization is created automatically for you when you sign up, and it is sometimes created during the presales phase. If someone has already invited you to an organization, you are added to that organization instead when you accept the invite, so you do not need to create one.
If your organization already has workspaces, create a new one from the workspace switcher in the sidebar, below the organization dropdown. If your organization has none yet, the sidebar instead shows a "Let's set up your first workspace" card: click its **Create workspace** button.
{% hint style="info" %}
When prompted, click **Create workspace** and name it after your team, for example *engteam*. Workspace names must be unique, and they appear in the names of any plugins published from them, which is most visible for publicly published plugins.
{% endhint %}
{% hint style="info" %}
If you are in an organization with teammates but have no workspaces, you were likely invited to the organization but not to a workspace. Contact one of your organization admins, who you can see on the organization **Members** screen.
{% endhint %}
Open **Settings** for your organization from the organization dropdown at the top of the sidebar. Rename the organization to your company name, and enable public sharing if you want users to be able to share skills publicly.
## Invite users
### Without SSO
Only organization admins can invite users to the organization. Invite users from the organization's **Members** screen, which you open from the organization dropdown at the top of the sidebar, assigning the workspaces each user should access along with the workspace role they get there. Invited users join the organization as members, and you can promote them to organization admin later, as below. You can also change their workspace roles from **Settings → Members** in the workspace. A user must accept their invite before you can edit them further.
### With SAML SSO
Users are provisioned on their first login and start with the organization **member** role and no workspace access. An administrator then adds each user to workspaces with the right roles from **Settings → Members** in each workspace. See [SSO](/administrators/sso) for setup.
## Promote a user to organization admin
Once a user exists, you can elevate them to organization admin to let them create workspaces and manage users. On the organization **Members** screen, assign the admin role.
## Admin keys
Admin keys give programmatic access across workspaces, for integrations and automation. Set an expiry of up to one year.
## Manage workspace membership
Switch to a workspace from the workspace switcher in the sidebar, then open **Settings** and select the **Members** card to set [roles](/administrators/roles) for users who need more than the default access, such as running evals, publishing, or managing members. Search for a user, select a [role](/administrators/roles), and click **Add**.
## Example role setups
These examples show common [role](/administrators/roles) assignments when rolling Tessl out.
### Samira, organization admin
Samira administers Tessl and champions skills. She needs to manage every workspace, assign users, and create new workspaces. Make her an organization admin.
### Jennifer, team manager
Jennifer runs a workspace. She needs to add members, publish, and remove other managers. Give her the **manager** or **owner** role on her workspace, depending on whether she needs to remove other owners or delete the workspace.
### Eddie, lead engineer
Eddie installs published skills and publishes skills for his team in the engteam workspace. Give him the **publisher** role there. He can be a **member** of other workspaces where he only needs to search and install.
### Joe, new-hire engineer
Joe searches and installs skills from the engteam workspace and runs reviews, but does not yet publish. Make him a **member** of the engteam workspace. The **consumer** role is for pure consumption only: a consumer can install skills but cannot run reviews or see who else is in the workspace.
# Roles
Organization and workspace roles and their permissions
{% hint style="info" %}
**Takeaways**
* Organization roles govern account-wide access, Context, Findings, SCM connections, and workspace creation.
* Workspace roles govern private plugins, publishing, evals, workspace members, and CLI scan uploads.
* A user can hold different roles in different workspaces.
{% endhint %}
## Organization roles
Organization roles are assigned across the Organization. An Organization admin also inherits the owner role in every workspace in that Organization.
| Permission | member | admin |
| ------------------------------------------------------------------- | ------ | ----- |
| View Organization-owned Context, Findings, and scan history | Yes | Yes |
| View SCM connections and scan history | Yes | Yes |
| Ignore or restore Findings | | Yes |
| Manage Organization-scoped API keys | | Yes |
| Create workspaces | | Yes |
| Connect or remove SCM accounts, set scan scope, and trigger rescans | | Yes |
| Inherit owner access in every workspace | | Yes |
Context and Findings from a workspace-owned upload remain visible only to people who can view that workspace.
## Workspace roles
Workspace roles are assigned per workspace. To learn more about creating a workspace, see [Workspace management](/reference/cli-commands#workspace-management).
| Permission | consumer | member | publisher | manager | owner |
| -------------------------------------------------- | -------- | ------ | --------- | ------- | ----- |
| View and install private plugins in the workspace | Yes | Yes | Yes | Yes | Yes |
| View workspace users and permissions | | Yes | Yes | Yes | Yes |
| Generate workspace-scoped API keys | | Yes | Yes | Yes | Yes |
| Review, security-scan, and fix skills from the CLI | | Yes | Yes | Yes | Yes |
| Generate eval scenarios | | | Yes | Yes | Yes |
| Run evals | | | Yes | Yes | Yes |
| Manage eval visibility | | | Yes | Yes | Yes |
| Create and publish plugins | | | Yes | Yes | Yes |
| Unpublish a plugin within two days of publishing | | | Yes | Yes | Yes |
| Roll out plugins to repositories | | | Yes | Yes | Yes |
| Upload a scan with `tessl inventory import` | | | Yes | Yes | Yes |
| Set up and manage workspace integrations | | | | Yes | Yes |
| Invite users and change workspace permissions | | | | Yes | Yes |
| Remove other managers | | | | Yes | Yes |
| Archive plugins | | | | Yes | Yes |
| Edit or delete workspace-scoped API keys | | | | Yes | Yes |
| Add or remove workspace owners | | | | | Yes |
| Delete the workspace | | | | | Yes |
# Using the EU region
Set up the Tessl CLI for an organization using the EU region.
Use this guide if your organization was provisioned on [eu.tessl.io](https://eu.tessl.io). The web app is at `https://eu.tessl.io`, and the CLI uses the API at `https://api.eu.tessl.io`.
## Set the EU environment
Make sure `TESSL_ENV=app-eu` is set in your shell environment before you run any `tessl` command. The CLI reads it each time it starts. Unless `TESSL_API_BASE_URL` or `TESSL_WEB_BASE_URL` is also set, this selects the EU API and web app.
Add the setting to your shell profile so new terminals inherit it. Use the profile for your shell:
```shell-session
$ echo 'export TESSL_ENV=app-eu' >> ~/.zshrc
$ source ~/.zshrc
```
```shell-session
$ echo 'export TESSL_ENV=app-eu' >> ~/.bashrc
$ source ~/.bashrc
```
On Windows PowerShell, persist the setting for your user, then open a new PowerShell window:
```powershell
[Environment]::SetEnvironmentVariable('TESSL_ENV', 'app-eu', 'User')
```
If you prefer not to change your profile, set the variable inline on each command instead:
```shell-session
$ TESSL_ENV=app-eu tessl login --device
```
## Log in
Use device login for the EU region:
```shell-session
$ tessl login --device
```
The CLI shows a code and the shared device login URL, `https://auth.tessl.io/device`. Open the URL, sign in, and enter the code.
Confirm that the CLI is using the EU environment:
```shell-session
$ tessl whoami
```
The output includes `Environment: app-eu`. It appears whether or not you are logged in, so you can also use this to check the setting before you log in.
## CLI files and global content
Unless `TESSL_GLOBAL_DIR` is set, the EU CLI stores its data in `~/.tessl_app-eu`. This is separate from the US CLI directory, `~/.tessl`, so credentials, globally installed tiles, and globally installed plugins do not transfer between regions. Install any global tiles and plugins again after you log in to the EU region.
If your environment sets `TESSL_API_BASE_URL`, `TESSL_WEB_BASE_URL`, or `TESSL_GLOBAL_DIR`, review or remove those overrides before you use the EU region. They take precedence over the regional defaults and can select a different endpoint or storage directory.
## CI, MCP servers, and agents
Set `TESSL_ENV=app-eu` in the environment that starts the CLI. This applies to CI jobs, MCP servers, and agent integrations that run `tessl`.
For example, set the variable in a CI job environment:
```yaml
env:
TESSL_ENV: app-eu
```
Recipe sandboxes launched from the EU instance receive this setting automatically. You do not need to set it in a skill, recipe, or schedule.
## Availability
The public registry and public publishing are not available in the EU region.
The CLI will select your region at login in a future update. Until then, keep `TESSL_ENV=app-eu` set in the environment the CLI runs in.
# SSO
{% hint style="info" %}
**Takeaways**
* SAML SSO is a paid feature available on the Business and Enterprise tiers.
* Users are provisioned on first login as organization members with no workspace access.
* An administrator then grants each user workspace roles.
{% endhint %}
## Enabling SAML based SSO
To enable SAML based Single Sign On (SSO), your Tessl account manager or technical contact will provide a link for your SSO system to connect and configure Tessl.
Your account manager can also send a link to add and verify your company's email domains. Tessl sends users to your SSO provider when their email address is on a verified domain, so verify every domain your users sign in with.
## Configuring Users
{% hint style="info" %}
Users are provisioned on first login
{% endhint %}
By setting up the integration, a user will authenticate via your SSO and be assigned the “member” role of the Organization when they visit Tessl. Your Tessl Org or Tessl Workspace administrators can add the user to workspaces with the desired roles by navigating to ***Settings → Members*** in each workspace.
For information on setting roles and managing users, see:
* [Organizations, Workspaces, and Roles](/administrators/administrating-organizations-workspaces-and-roles)
* [Roles](/administrators/roles)
# Using the Tessl agent
Six things teams use the agent for, the way you'd actually ask for each one, the command it runs underneath, and what you should see back.
## 01 See what you already have
Skills are multiplying across repos, and most teams can't say how many they have or who owns them. This is free, needs no changes to your code, and is the first thing worth running.
See what skills you already have
USE WHEN You have skills spread across repos and no single view of what exists or who owns it.
**Ask your agent**
"Scan our GitHub org and upload the results to Tessl."
**Under the hood**
`tessl inventory import`
Scans your repos, collects `SKILL.md` and manifest files, and uploads a snapshot. Forked repos are skipped.
**What to expect**
The uploaded results feed the reporting Organization's Context and Findings, where you can see what exists, where it lives, and what Tessl reported. Analysis and scoring continue in the background, so results can appear at different times.
Trial it on a subset first with `tessl inventory import --repo repo-a --repo repo-b`. The flag repeats as many times as you like.
It reads only `skill.md` files and manifests. No source code, no real names or email addresses (GitHub usernames only), and no repo clones: files are fetched one at a time through the API.
{% hint style="warning" %}
**Heads up:** the default scan covers your 100 most recently active repos. Large orgs can hit GitHub's limit of 5,000 API requests per hour mid-scan. Scans are diffed, so nothing is lost: wait for the reset and run it again.
{% endhint %}
***
## 02 Bring or create skills
Three starting points, depending on what you already have.
Import a skill you already have
USE WHEN Best if you already have a skill in your repo. The agent brings it in as-is.
**Ask your agent**
"Import the skill at plugins/my-plugin into Tessl."
**You provide**
The path to a skill you already have, either a `SKILL.md` file or the directory holding it.
**Under the hood**
`tessl skill import`
Wraps a standalone skill as a plugin: `SKILL.md` plus a `.tessl-plugin/plugin.json` manifest.
**What to expect**
Your skill unchanged, now with a manifest beside it, so it can be reviewed, evaluated, versioned, and published.
Create a new skill
USE WHEN Nothing to bring yet? The agent walks you through a new one from scratch.
**Ask your agent**
"Help me create a skill."
Or name it: `"run plugin-creator"`
**Under the hood**
Built-in `plugin-creator` skill
Interviews you about the skill's scope, scaffolds the plugin and skill directory, then validates the result.
**What to expect**
An interview about what the skill should cover, then a drafted `SKILL.md`. Check the `description` carefully: it's what decides whether an agent picks the skill up at the right moment.
Create context for recurring agent mistakes
USE WHEN You have PR review history, and the same corrections keep coming up in it.
**Ask your agent**
"Agents keep getting this wrong. Look at our last 2 weeks of PR reviews."
Or name it: `"run find-optimizations on the last 2 weeks"`
**You provide**
A PR number, or a time window in plain language such as "the last 2 weeks". It will not run without one.
**Under the hood**
Built-in `find-optimizations` skill
Batch-fetches feedback from change-requested PRs, then splits it across subagents so no PR body ever crowds out the context.
**What to expect**
A deduplicated, numbered list of improvements. Each one is typed (`skill`, `review`, `skill`, `rule`, `hook`, `test`, `refactor`, or `verifier`), backed by the PR numbers and specific comments that motivate it, and pointed at an exact destination rather than a vague suggestion.
It triages before it proposes. When a linter, typechecker, or schema validator could own the pattern, it names that tool instead of reaching for a verifier. Nothing gets changed: the output is the deliverable.
It reads your source control preferences from `.tessl/memory/` first, so it may run `/setup-memory` before the analysis if this is your first time. Needs real review history to work with, so run it on a repo where people leave PR comments.
***
## 03 Automate code review
Tessl Code Review reviews the exact pull request head and publishes one native GitHub review. A review can request required changes while keeping optional suggestions visible, and later rounds account for fixes and replies.
Set up Tessl Code Review
USE WHEN You want a first review before a human starts, or a repeatable review on every merge candidate.
**The supported path is the GitHub App**
The Tessl Review GitHub App is the supported way to run Tessl Code Review. It reviews pull requests on Tessl's infrastructure, with no workflow to write and no token to store. Open **Code reviews** in the Tessl web app and select **Connect GitHub**, then enable each repository you want reviewed. Read [Set up Tessl Code Review](/tutorials/setting-up-agentic-code-review) for install, the separate enable step, trigger policies, approval, the config file, and troubleshooting.
**If you cannot install a GitHub App**
An unsupported GitHub Action can run reviews from a workflow you own instead. The `tessl/code-review` plugin carries a setup skill that writes it for you:
```sh
tessl install tessl/code-review
```
If your `tessl.json` still declares `tessl/code-review-setup` or `tessl/code-review-lens-creator`, replace it with `tessl/code-review`. Those plugins were folded into `tessl/code-review` and are being retired; while a project declares one of the old names, `tessl agent` skips its built-in copy of the merged plugin so the same skill is not loaded twice, and the project gets only what the old plugin carried.
Ask your agent to set up code review, and it points you to **Code reviews** for your organization, where you select **Connect GitHub** to install the Tessl Review GitHub App. The agent cannot install the App for you: the install starts in the browser. It also tells you that the repository has to be enabled in Tessl afterwards, since installing the App alone does not start reviews. See [Set up Tessl Code Review](/tutorials/setting-up-agentic-code-review) for the whole setup.
If you cannot install a GitHub App, an unsupported GitHub Action can run Tessl Code Review from a workflow you own. Ask for the GitHub Action by name to get it. See [Running Code Review in your own CI](/tutorials/setting-up-agentic-code-review/code-review-action) for its input and output reference.
Choose and tune review lenses
A lens is a focused set of review instructions. The `standard` profile runs the lenses from the [`tessl/code-review`](https://tessl.io/registry/tessl/code-review) plugin by default: `review-correctness-and-data-integrity`, `review-maintainability-and-code-quality`, `review-scale-and-resilience`, and `review-security-and-privacy`. Begin without overriding the selection and evaluate the results on pull requests you understand.
Ask your agent to add repository-specific lenses only when you can name the concern and show examples of what a good review should catch:
> Add our versioned API-contract and data-handling lenses to Tessl Code Review. Keep the existing cadence and advisory mode.
Passing `lenses` replaces the profile's complete default selection, and a review supports at most eight lenses. Pin every registry reference (for example `tessl/code-review@0.2.0#review-security-and-privacy`) and keep each lens responsible for a distinct concern, so findings do not repeat each other. To fork a default lens, start from its source in [`tesslio/product-plugins`](https://github.com/tesslio/product-plugins); to write one from scratch, use the `create-code-review-lens` skill in the same [`tessl/code-review`](https://tessl.io/registry/tessl/code-review) plugin.
Move from advisory to gate mode
USE WHEN Advisory reviews have earned trust and every merge candidate can receive a review.
**Ask your agent**
"Change Tessl Code Review to gate mode and tell me which GitHub repository settings and required check I need."
**What to expect**
The workflow changes to `mode: gate`. An approved review attempts a native GitHub approval and reports a successful check. A review that requires changes attempts to request changes and reports a failed check.
The agent should also tell you to:
* allow GitHub Actions to create and approve pull requests;
* require the Action-owned check named exactly `Tessl Code Review`;
* use an automatic cadence or make requested reruns part of the merge process;
* test both an approved change and a change that should be blocked.
Do not require the caller workflow job as the review gate. Mention-driven and manually dispatched jobs are associated with the default branch, while the Action reports its own check against the reviewed pull request head.
Decide separately whether a human review is required
USE WHEN You want a repository-owned risk policy to decide which pull requests still need a human reviewer.
**Ask your agent**
"Set up a PR risk gate for this repo."
**You provide**
A choice of starter policy: `conservative-starter` or `official-review-policy-parity`. Read and edit the generated policy files before you depend on the gate.
**Under the hood**
```sh
tessl change risk init
tessl change risk --base origin/main \
--fail-if-review-required --json
```
This combines deterministic git measurements with an advisory agent judgment, followed by a deterministic policy decision. It is separate from Tessl Code Review: one reviews the code, while the other decides whether repository policy requires a human.
**What to expect**
Starter files under `.github/pr-review-gate/`: a config, a policy, and a prompt. Two starters are available: `conservative-starter` is the default and requires human review for most changes; `official-review-policy-parity` tracks your existing branch protection more closely. Read and edit the policy before you rely on it.
In CI, `--fail-if-review-required` exits non-zero when the gate decides a human is needed.
{% hint style="warning" %}
**Heads up:** `change risk init` writes the policy files only. It does not create a workflow and does not touch branch protection. Add the check as advisory first, watch it on real PRs for a few weeks, and make it required once you trust the signal.
{% endhint %}
***
## 04 Enforce your standards
Verifiers check binary, observable facts about committed files. Reach for one when a reviewer keeps flagging the same structural pattern and no linter can own it.
Write your first verifier
USE WHEN A reviewer keeps flagging the same structural pattern and no linter can express it.
**Ask your agent**
"Create a verifier that checks every Fastify route file returns via our typed response helpers."
**You provide**
The rule you want enforced, in plain language and specific enough that someone could score a file pass or fail by reading it.
**Under the hood**
```sh
tessl change verify lint
tessl change verify --dry-run --all --show-files
```
Validates the structure against the schema, then previews exactly which files would be judged before spending any judge calls.
**What to expect**
A verifier JSON file plus an entry in the `verify` block of `tessl.json`. Each verifier carries a `name`, an `instruction`, a `relevant_when` eligibility test, `context` a `scope` (file, paths, or diff) with its `scope_reason`, and a `checklist` of one to three binary rules.
Severity is never in the verifier file. It's repo policy, set per group in `tessl.json` as `info`, `warn`, or `error`. That way the same verifier can be advisory in one repo and blocking in another.
{% hint style="warning" %}
**Heads up:** most bad verifiers fail for one reason: a `relevant_when` that's too broad. "Backend file", "React component", and "any TypeScript file" are all too vague to judge consistently. Name the observable trait that makes a file in scope.
{% endhint %}
Run verifiers on every PR
USE WHEN Your first verifier has earned trust and you want it enforced in CI.
**Ask your agent**
"Run verifiers on every PR."
**You provide**
The verifier group already wired into `tessl.json`, plus a base ref. Nothing else.
**Under the hood**
`tessl change verify --base origin/main --github`
`--github` emits GitHub Actions annotations, so findings appear inline in the PR even when the run exits 0.
**What to expect**
Findings in the PR UI, anchored to the lines that violate the rule. Verifiers set to `error` make the check blocking; `warn` annotates without failing, unless you add `--fail-on-warn`.
Start every new verifier at `warn` while you calibrate. Promote it to `error` only after you've confirmed it avoids false positives on real PRs.
**Widen the blast radius one rung at a time**
`tessl change verify lint` → `tessl change verify --dry-run --all --show-files` → `tessl change verify --sample 5` → full run
***
## 05 Automate the chores
The recurring work that never makes it onto a sprint board: the scan someone runs by hand, the cleanup that gets deferred, the check everyone forgets.
Find chores worth automating
USE WHEN You suspect there is repeat work in this repo but have not pinned down what.
**Ask your agent**
"There's a chore I keep doing by hand."
Or name it: `"run find-automations"`
**Under the hood**
Built-in `find-automations` skill
Reads the repo and its history for work that recurs on a predictable trigger.
**What to expect**
A numbered list of opportunities. Each one carries a ticket-style title, its pattern type (`established`, `emerging`, or `one-off`), the evidence behind it, a suggested trigger and execution mode, and a description detailed enough to implement from. The numbering is the point: you can come back and say "create a ticket from item 2".
It looks for signals like the same person filing the same maintenance PR, the same reviewer leaving the same comment, repeated CI babysitting, and release or dependency chores. Strictly read-only: it won't write a file, comment on a PR, or trigger a workflow.
Turn a chore into a CI workflow
USE WHEN You have agreed on a candidate and want it running without anyone remembering to.
**Ask your agent**
"Run this recurring task automatically in CI."
Or name it: `"run workflow-automator"`
**You provide**
The task you want automated and roughly when it should run. It interviews you for the rest: what counts as a successful run, what the agent needs as input, the exact trigger, and any secrets or admin approvals required.
**Under the hood**
Built-in `workflow-automator` skill
Builds the scheduled GitHub Actions workflow and the skill it invokes.
**What to expect**
A committed workflow on a schedule you chose, plus the auth to run it. Create the key with `tessl api-key create --workspace `, store it as a `TESSL_TOKEN` repository secret, and the `tesslio/setup-tessl@v2` action picks it up. Scheduled agent workflows need `ANTHROPIC_API_KEY` as a repository secret too.
The default shape is a weekly cron plus a `workflow_dispatch` trigger, so you can run it by hand while you're still building trust in it, with the results uploaded as an artifact you can read after each run.
Run a skill unattended
USE WHEN You want a skill to run without sitting through it, locally or in a Tessl cloud sandbox.
**Ask your agent**
"Run the find-automations skill on the payments repo."
**You provide**
The skill to run: a bare installed name such as `find-automations`, a registry ref `workspace/skill[@version]`, or `file:path/to/skill`. Plus an `--agent`. Pass per-run input with `--instructions "…"`, and add `--repo owner/name` when you use `--cloud`.
**Under the hood**
```
tessl launch skill \
--agent claude-code --yolo
```
Add `--cloud --repo owner/name` to run it in the cloud instead of on your machine.
**What to expect**
The skill runs through your chosen agent with output streaming back. `--yolo` skips permission prompts, which is what makes it usable in CI. Use `--interactive` to watch it in the foreground instead, and `tessl launch list` to see recent runs.
Hooks, when the trigger is an agent event
* **Two tiers, declared in `.tessl-plugin/plugin.json`.** Use `hooks` for the portable path that works across agents, and `nativeHooks` to pass agent-specific config straight through when you need the escape hatch.
* **Five generic events.** `PreToolUse`, `PostToolUse`, `UserPromptSubmit`, `SessionStart`, and `Stop`. A `matcher` narrows a hook to specific tools; omit it to fire on all of them.
* **Anchor every path with `${TESSL_PLUGIN_DIR}`.** It's the only reference that survives a change of working directory. Bare relative paths resolve against wherever the event fired, not your plugin.
{% hint style="warning" %}
**Heads up:** hook scripts have to live under `hooks/` in the plugin to ship at all, and only the files you actually declare are made executable at install time. A `timeout` in the manifest is accepted but not currently enforced, so don't rely on it to stop a slow hook.
{% endhint %}
***
## 06 Measure your context
Context is the skills and rules your agents load. One that reads well can still fail to fire, or fire and change nothing. Reviews score the writing. Evals measure the difference it makes.
Score a skill's quality
USE WHEN You want to know how a skill reads against a rubric before anyone depends on it.
**Ask your agent**
"Review this skill."
**You provide**
The path to the skill or plugin, plus `--workspace`. Defaults to the current directory if you omit the path.
**Under the hood**
```
tessl review run ./my-skill \
--workspace
```
Runs server-side. Ctrl-C detaches from the output; the review keeps going.
**What to expect**
A score with a per-judge breakdown, so you can see which dimension pulled it down. In CI, `--threshold ` exits non-zero below the bar you set; `0` never fails and skips score gating entirely.
For a security pass instead, run `tessl review run security` and gate it with `--fail-on low|medium|high|critical`.
Improve a skill automatically
USE WHEN The review found problems and you would rather the agent fixed them than do it by hand.
**Ask your agent**
"Optimize my skill."
**You provide**
The same path and workspace. It prompts before it edits unless you pass `--yes`.
**Under the hood**
`tessl review fix`
An improve-then-re-review loop. `--max-iterations` caps the passes (1 to 10) and `--threshold` stops it early once the score clears your bar.
**What to expect**
It prompts before it edits, then hands you a change summary of exactly what it improved. Pass `--yes` to skip the prompts and `--threshold` to stop once the score clears a bar.
Measure whether a skill helps
USE WHEN A skill reads well, but you have not proved it changes what an agent actually does.
**Ask your agent**
"Build an eval for this skill."
**You provide**
The plugin directory. `scenario generate` needs a source to generate from, and `scenario download` reads scenarios from `evals/`.
**Under the hood**
```
tessl scenario generate --count 5
tessl scenario download --last
tessl eval run
```
Keep counts low at first so runs finish while you're still watching.
**What to expect**
Each scenario runs twice, once with your skill injected and once without, so the result is a delta rather than a bare score. That's the number that tells you whether the skill earns its place. Add `--runs 3` to average out model variance.
Downloaded scenarios land as `evals/-/` with a `task.md`, a `criteria.json`, and a `scenario.json`.
{% hint style="info" %}
**Note:** `scenario download` writes to the plugin's `evals/` directory automatically when run from the plugin root or any subdirectory of it. The plugin root is the directory that contains `.tessl-plugin/plugin.json`. Evals need at least `publisher` access; `member` is enough to run a review but not an eval.
{% endhint %}
# Enhance your workflow with skills
Learn how to discover and install skills that enhance your agent's capabilities with procedural workflows
Skills provide step-by-step workflows that help your agent perform specific tasks correctly. This guide shows you how to find, install, and use skills to improve your development workflow.
## What are skills?
Skills are procedural guides that teach agents how to perform specific workflows. Unlike documentation (which explains what something is), skills explain how to do something step-by-step.
**Example skills:**
* Debug API endpoints systematically
* Review code for security issues
* Write comprehensive test suites
* Generate API documentation
When you work on tasks, your agent automatically loads relevant skills to follow best practices and team procedures.
## Prerequisites
Before installing skills, make sure you've initialized Tessl in your project:
```bash
# Initialize Tessl (auto-detects and configures your agent)
tessl init
```
See [Improve your first skill](/introduction-to-tessl/improve-your-first-skill) and [Custom agent setup](/reference/custom-agent-setup) for details.
## Discovering skills
### Browse the registry
Visit the [Tessl Registry](https://tessl.io/registry) to browse available skills. You can further filter the results by:
* plugin
* Skill
### Search from CLI
Search for skills directly from your terminal:
```bash
# Search for testing skills & plugins
tessl search testing
# Search for code review skills & plugins
tessl search "code review"
# Interactive search
tessl search
```
### Ask your agent
You can also ask your agent to find and install skills:
```
Find me a skill for debugging API endpoints
```
## Installing skills
{% hint style="info" %}
Note, if you're installing skills to your OpenClaw agent, you must install skills from your agent's workspace. Check out [OpenClaw](/reference/custom-agent-setup/openclaw) for more information.
{% endhint %}
By default, skills are installed into your current project (`.tessl/plugins/`) and tracked in `tessl.json`. Use `--global` to install a skill to `~/.tessl/` instead, making it available across all your projects without needing to reinstall it per project.
```bash
# Install into the current project (default)
tessl install tessl-labs/debug-api-endpoints
# Install globally, available in all projects
tessl install --global tessl-labs/debug-api-endpoints
```
### From the registry
Install skills by name from the Tessl registry:
```bash
# Install a specific skill
tessl install tessl-labs/debug-api-endpoints
# Install multiple skills
tessl install tessl-labs/code-review tessl-labs/testing-workflow
```
### From GitHub repositories
Many open source projects publish skills on GitHub:
```bash
# Install from GitHub with interactive skill selection
tessl install https://github.com/anthropics/skills
# Install specific skills by name
tessl install https://github.com/anthropics/skills --skill pdf --skill pptx
# Install from a specific branch or path
tessl install https://github.com/owner/repo/tree/main/skills/my-skill
```
The registry shows a commit-specific install command when security results are available for that version — use it to install the exact version that was scanned. See [Security scores](#security-scores) for details.
## Using installed skills
Once installed, skills work automatically. Your agent loads relevant skills based on:
* Your task description
* The files you're working with
* The context of your conversation
### How skills activate
Skills use "lazy push" - they're automatically loaded when relevant:
**Example: Debugging workflow**
1. You say: "Debug the failing API endpoint"
2. Agent recognizes this matches the debug-api-endpoints skill
3. Skill is loaded with its step-by-step workflow
4. Agent follows the procedure: check infrastructure → verify auth → validate I/O → test functionality
You don't need to explicitly invoke skills - they activate automatically when needed.
## Managing installed skills
### List installed skills
View all skills in your project:
```bash
tessl list
```
This shows all installed plugins, including those containing skills.
### Update skills
Check for newer versions and reinstall to update:
```bash
# Check which installed plugins have updates available
tessl outdated
# Reinstall to get latest version
tessl install tessl-labs/debug-api-endpoints
```
### Remove skills
Uninstall skills you no longer need:
```bash
# Remove from the current project
tessl uninstall tessl-labs/debug-api-endpoints
# Remove a globally installed skill
tessl uninstall --global tessl-labs/debug-api-endpoints
```
## Reviewing skill quality
Before installing skills, check their review scores and evaluations in the registry to understand their quality and effectiveness.
### Understanding review scores
Skills in the registry show multiple quality indicators:
**Review Score** (0-100%): Overall quality assessment
* 90%+: High-quality, production-ready
* 70-89%: Good quality, may have minor improvements needed
* Below 70%: Needs work before deployment
**Validation Score**: Checks for required fields, trigger hints, workflow structure, and metadata completeness
**Implementation Score**: Code quality in examples, security practices, error handling
**Activation Score**: How well agents discover and load the skill when relevant
### Viewing evaluations
Click on any skill in the registry to see:
* Detailed validation results (what passed/failed)
* Specific recommendations for improvement
* Example usage and trigger conditions
* Community feedback and ratings
Use these scores to choose skills that meet your quality standards before installing.
For more details on how skills are scored, see [Check a skill's quality using review](/improving-your-skills/reviewing-skills).
## Security scores
Skills installed from the Tessl Registry are scanned for security vulnerabilities using Snyk. Security scores are shown in the registry UI alongside quality scores so you can assess risk before installing.
Security scanning can produce false positives, and Tessl is designed to give you flexibility in how much weight you give the findings rather than blocking you outright.
### Security gating
When you run `tessl install` or `tessl update`, if a skill has critical or high security findings, the CLI will ask for your permission before continuing. You can always choose to proceed — installation is never blocked.
To skip the prompt automatically (for example in CI or automated workflows):
```bash
tessl install engteam/my-skill --accept-warnings
```
### Installing a pinned version
The registry shows a commit-specific install command alongside security results, so you can install the exact version that was scanned:
```bash
tessl install engteam/my-skill@abc1234
```
You can also install the latest version at any time by omitting the version, or run `tessl update` on an already-installed skill.
### Reporting false positives
Each security finding in the registry includes a **Report Incorrect Findings** link. Use it to flag suspected false positives — the Tessl team will investigate and feed confirmed corrections back to Snyk to improve the scanner.
## Best practices
**Start with popular skills**: Browse featured skills in the registry to find well-reviewed, widely-used workflows.
**Install skills for your tech stack**: Look for skills specific to your frameworks and tools (React, FastAPI, Docker, etc.).
**Create team skills**: Build custom skills for your team's specific workflows and procedures. See [Creating skills](/creating-skills-and-plugins/create-a-skill).
**Review before installing**: Check skill review scores in the registry to understand quality and completeness.
**Keep skills updated**: Reinstall periodically to get improvements and bug fixes.
## Troubleshooting
**Skill not activating?**
* Make sure the skill is installed: `tessl list`
* Try being more specific in your request to match skill triggers
* Check that your agent has MCP configured: `tessl init --agent `
**Multiple skills conflicting?**
* Skills are designed to work together, but if you notice issues, uninstall less relevant ones
* More specific skills usually take precedence over general ones
**Need a skill that doesn't exist?**
* Create your own: [Creating skills](/creating-skills-and-plugins/create-a-skill)
* Request it in the Tessl community
* Check GitHub for open source skills in your domain
## Next steps
* [Creating skills](/creating-skills-and-plugins/create-a-skill) - Build custom workflows for your team
* [Check a skill's quality using review](/improving-your-skills/reviewing-skills) - Understand skill quality scores
# Migrating from tiles to plugins
Guide for migrating from the legacy tile.json format to the new plugin format
Tessl is transitioning from **tiles** to **plugins** as the packaging format for shareable agent rules and skills. This document explains why, what changed, and how to migrate your existing tile packages.
## Why the change?
Tessl started with tiles: prepackaged bundles of context for agents. Since then, the wider agent ecosystem is settling on plugins as the standard format for the same idea, so we're moving Tessl onto plugins.
For you, this means what you build in Tessl travels naturally to different coding agents, and the terminology lines up with what your teams are already seeing. For us, it's a stronger foundation to build on. As agents start handling richer kinds of context, plugins give us the base to layer versioning, distribution, evaluation, and security on top of these new context types.
***
## What changed
### Manifest location and filename
| Format | File | Location |
| ------ | ------------- | --------------------------- |
| Tile | `tile.json` | Package root |
| Plugin | `plugin.json` | `.tessl-plugin/plugin.json` |
The manifest moves into a dedicated `.tessl-plugin/` directory. This keeps the root clean and makes space for sibling agent manifests (`.claude-plugin/`, `.cursor-plugin/`) without naming collisions, if and when they are added.
### Field-by-field comparison
| Concept | tile.json | plugin.json | Notes |
| ----------------- | ----------------------------------------- | ------------------------- | ---------------------------------------------- |
| Package name | `name` | `name` | Same format: `workspace/package` |
| Version | `version` | `version` | Required at publish in both |
| Short description | `summary` | `description` | Field renamed; trimmed and required at publish |
| Private flag | `private` | `private` | Identical |
| Repository URL | `repository` | `repository` | Both accept `https://` URLs |
| Package author | — | `author` | New: `{ name, email, url }` object |
| Homepage | — | `homepage` | New: URL string |
| License | — | `license` | New: SPDX identifier, e.g. `"MIT"` |
| Skills | `skills: { "name": { path: "..." } }` | `skills: "./skills/"` | Changed from keyed object to path(s) |
| Rules / Steering | `rules: { "name": { rules: "..." } }` | `rules: "./rules/"` | Changed from keyed object to path(s) |
| Commands | `commands: { "name": { script: "..." } }` | `commands: "./commands/"` | Changed from keyed object to path(s) |
| Docs file | `docs: "./README.md"` | — | Removed; move content into skills or rules |
| Describes (PURL) | `describes: "pkg:..."` | — | Removed; not carried forward |
### Skills: from keyed registry to directory discovery
In `tile.json`, each skill had an explicit key and path:
```json
{
"skills": {
"my-skill": { "path": "./skills/my-skill/SKILL.md" },
"other-skill": { "path": "./skills/other-skill/SKILL.md" }
}
}
```
In `plugin.json`, you point at a directory and Tessl discovers skills automatically. A skill's identity comes from the `name:` field in its `SKILL.md` frontmatter (falling back to the directory basename if no frontmatter is present):
```json
{
"skills": "./skills/"
}
```
You can also pass an explicit array of paths when you want precise control:
```json
{
"skills": ["./skills/my-skill/SKILL.md", "./skills/other-skill/SKILL.md"]
}
```
### Rules: from nested objects to directory paths
In `tile.json`:
```json
{
"rules": {
"style-guide": { "rules": "./rules/style-guide.md" }
}
}
```
Note: `steering` was accepted as an alias for `rules` in `tile.json` and normalised automatically. Both wrote to the same field internally.
In `plugin.json`:
```json
{
"rules": "./rules/"
}
```
All `.md` files found in the declared directory are included as rules. There are no longer named keys; the rule name is derived from the filename.
### Docs and Describes: removed
The `docs` field (a standalone markdown file) and `describes` field (a PURL for a versioned dependency) have no equivalent in `plugin.json`.
* **`docs`**: Fold the content into a rule or skill. If the doc was user-facing guidance about a tool or library, it belongs as a skill.
* **`describes`**: This field declared that a tile described a specific versioned package (e.g. a Go library). It was used as part of Docs, as Docs have not been carried forward, neither has Describes.
If you publish with `TESSL_PLUGIN=1` and your `tile.json` still has `docs` or `describes` set, the CLI will warn you at pack time that these fields will not be included.
***
## Compatibility during the transition
Tiles and plugins coexist. The CLI continues to read and publish `tile.json` packages without any changes required. No existing tile breaks.
When both a `tile.json` and a `.tessl-plugin/plugin.json` are present in the same package `.tessl-plugin/plugin.json` takes precedence for metadata (name, version, description).
{% hint style="info" %}
For new work, use plugins: `.tessl-plugin/plugin.json` and `tessl plugin ...`. Use tiles only for legacy compatibility or migration. Publish legacy `tile.json` packages with `tessl tile ...`. Publish new plugin packages with `tessl plugin ...`.
{% endhint %}
***
## How to migrate
Using the migrate command
The CLI can generate `.tessl-plugin/plugin.json` from your existing tile.json automatically:
```
tessl tile migrate
```
Run this from your package root (the directory containing tile.json). The command:
* Creates `.tessl-plugin/` if it doesn't exist
* Translates all supported fields (name, version, summary → description, repository, private, skills, commands, rules)
* Warns if your tile.json contains docs or describes — these have no plugin equivalent and will not appear in the output
If you want to migrate a package that isn't in the current directory, pass the path:
```
tessl tile migrate ./path/to/my-package
```
What the command does not do
The migrate command handles the mechanical translation. A few steps still require your attention:
* docs and describes: If your tile.json uses these fields, the command will warn you and omit them. See Docs and Describes: removed for how to fold that content into skills or rules.
* SKILL.md frontmatter: The command copies your skill paths as-is. If your SKILL.md files are missing a name: field, Tessl will fall back to the directory basename — but adding frontmatter is recommended. See Step 4: Add SKILL.md frontmatter.
* tile.json is kept: The command does not delete your existing tile.json. Once you've verified the new manifest with `tessl plugin lint` and `tessl plugin publish --dry-run`, you can remove it manually.
***
### Alternatively:
### Step 1: Create `.tessl-plugin/plugin.json`
Create the directory and manifest:
```
mkdir .tessl-plugin
touch .tessl-plugin/plugin.json
```
Translate your `tile.json` fields:
**tile.json (before):**
```json
{
"name": "myorg/my-package",
"version": "1.2.0",
"summary": "Linting rules for our TypeScript monorepo",
"repository": "https://github.com/myorg/my-package",
"skills": {
"lint-fix": { "path": "./skills/lint-fix/SKILL.md" }
},
"rules": {
"ts-style": { "rules": "./rules/ts-style.md" },
"imports": { "rules": "./rules/imports.md" }
}
}
```
**.tessl-plugin/plugin.json (after):**
```json
{
"name": "myorg/my-package",
"version": "1.2.0",
"description": "Linting rules for our TypeScript monorepo",
"repository": "https://github.com/myorg/my-package",
"skills": "./skills/",
"rules": "./rules/"
}
```
### Step 2: Check your directory layout
The path values in `plugin.json` are relative to the **package root** (i.e. the directory containing `.tessl-plugin/`). Verify that the paths you declared actually exist:
```
my-package/
├── .tessl-plugin/
│ └── plugin.json ← manifest
├── skills/
│ └── lint-fix/
│ └── SKILL.md ← discovered automatically
└── rules/
├── ts-style.md ← discovered automatically
└── imports.md ← discovered automatically
```
### Step 3: Handle docs and describes
If your `tile.json` has a `docs` field:
1. Open the file it points to.
2. If the content is a step-by-step procedure for the agent to follow, convert it to a skill: create a `SKILL.md` in your skills directory with the content.
3. If the content is constraints or style guidance, move it into your rules directory as a `.md` file.
4. Remove `docs` from `tile.json` (or skip it entirely if you're dropping `tile.json`).
### Step 4: Add SKILL.md frontmatter (recommended)
With `tile.json`, skill identity was the key in the `skills` object. With `plugin.json`, identity comes from the `name:` field in `SKILL.md` frontmatter. Add frontmatter if it's missing:
```markdown
---
name: lint-fix
description: Fix lint errors in TypeScript files using the project's oxlint config
---
# Lint Fix
...
```
If there's no frontmatter, Tessl uses the directory basename as the skill name — so existing skills continue to work without changes.
### Step 5: Verify with the CLI
Run the linter to catch any issues:
```
tessl plugin lint
```
In plugin mode (`TESSL_PLUGIN=1`), the CLI will:
* Warn if `tile.json` is still present with `docs` or `describes` fields that have no plugin equivalent.
* Validate that every path declared in `plugin.json` resolves and contains recognisable content.
Do a dry-run pack to confirm what will be included in the tarball:
```
tessl plugin publish --dry-run
```
### Step 6: Publish
```
tessl plugin publish
```
Once you're confident in the new format, you can delete `tile.json` from your repository to remove the duplication.
***
## Running evaluations after migration
`tessl eval run` works the same way it did for tiles: point it at the package root. The only change is where that root is.
Before migration, you pointed at the tile directory (where `tile.json` lives):
```
tessl eval run
```
After migration, point at the plugin directory (where `.tessl-plugin/plugin.json` lives):
```
tessl eval run
```
The plugin directory is the *parent* of `.tessl-plugin/`, not `.tessl-plugin/` itself. From a plugin root, this is usually just `.`:
```
tessl eval run .
```
***
## Quick reference
### tile.json → plugin.json field mapping
| tile.json | plugin.json |
| ------------------------------------------ | ------------------------------------------ |
| `summary` | `description` |
| `skills.X.path` | `skills` (directory or array) |
| `rules.X.rules` | `rules` (directory or array) |
| `steering.X.rules` | `rules` (directory or array) |
| `commands.X.script` | `commands` (directory or array) |
| `docs` | No equivalent — move to skills or rules |
| `describes` | No equivalent — contact us |
| `name`, `version`, `private`, `repository` | Identical |
| — | `description` (required at publish) |
| — | `author`, `homepage`, `license` (optional) |
### Minimum valid plugin.json
```json
{
"name": "workspace/package-name",
"version": "1.0.0",
"description": "One sentence describing what this plugin does"
}
```
By convention, skills will be pulled from the `./skills` directory and rules from `./rules`. If they are not set, these conventions will be used.
# Understand your organization's context
How to connect an SCM account so Tessl scans your repositories and shows your Organization's Context and Findings.
Connect an SCM account and Tessl scans your repositories, indexes the skills and configuration it finds as **Context**, and surfaces **Findings** you can act on. This is the primary way to see what exists across your Organization.
***
SCM connections are managed at the Organization level. Connecting one needs the Organization admin role. Organization members and admins can view **Context** and **Findings**. See [Roles](/administrators/roles) for the full breakdown.
### Connect an SCM account
Tessl supports these source-control providers:
* **GitHub** (GitHub App)
* **GitLab** (access token)
* **Bitbucket**
**To connect:**
1. Open the Tessl web app.
2. Select your Organization from the dropdown at the top of the sidebar, then go to **Settings**, then **Integrations**.
3. Under **Source control**, select **Add** next to your provider and follow the prompts to authorize Tessl.
Connecting authorizes Tessl to read from the provider. Depending on provisioning availability, Tessl may then start a first scan of the repositories in scope. Scan provisioning is best-effort and separate from creating the connection, so a successful connection does not guarantee that a scan has started or finished. The connection page shows scan status. An Organization admin can retry a failed scan or set the **Scan scope** there.
### See your Context and Findings
Once a scan has run:
* Open **Context** in the sidebar to see the skills and configuration Tessl found across your connected repositories, including which repository each item lives in.
* Open **Findings** to see the issues Tessl surfaced, ranked by severity.
* **Home** gives you an overview across your Organization.
To control which repositories Tessl scans, open the connection under **Settings**, then **Integrations**, and set the **Scan scope**. For GitHub-specific setup, see [Connect Tessl to GitHub](/distribute/connect-tessl-to-github).
# Overview
Create a skill or a plugin - the packaged, versioned context you share with your team and your agents.
{% hint style="info" %}
**Takeaway** A skill teaches an agent how to do something. A plugin is how you package one or more skills, together with rules, commands, MCP servers, and hooks, so you can version and share them. Start with a skill; reach for a plugin when you need to bundle more than one thing.
{% endhint %}
A skill is a folder with a `SKILL.md` that teaches an agent how to do something. A plugin is the package that holds it: a `.tessl-plugin/plugin.json` manifest plus its content. Every skill you create with `tessl skill new` is already a minimal plugin, so "skill" and "single-skill plugin" are the same thing. You only think about plugins explicitly when you bundle more: several skills, a rule, a command, an MCP server, or a hook.
Whatever you create, you create it once. Tessl makes it work across every agent it supports, Claude Code, Cursor, Codex, and more, adapting it to each agent's own format on install. You never write a per-agent version.
The examples in this section use `engteam` as the workspace name. It is a stand-in: run `tessl workspace list` to see the workspaces you belong to, and use one of those in its place.
This section covers creating that context and getting it ready to share: writing a skill, bundling a plugin, adding an MCP server, testing locally, and publishing. It does not cover improving a skill's quality once written (see [Improving your skills](/improving-your-skills/overview-improving-skills-and-plugins)), enforcing a standard in CI (see [Codifying and enforcing your skill standards](/codifying-and-enforcing-your-skill-standards/overview)), or rolling context out across many repositories (see [Distribute](/distribute/distributing-via-registry)).
{% hint style="info" %}
All of this is also available through your agent. Install Tessl's plugin creator and it will do the steps below for you, from understanding the problem to building the plugin: `tessl install tessl/plugin-creator`
{% endhint %}
## In this section
| | |
| --------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
| [Create a skill](/creating-skills-and-plugins/create-a-skill) | Write a `SKILL.md`, scaffold it, and validate it. The common starting point. |
| [Create a plugin](/creating-skills-and-plugins/create-a-plugin) | Bundle several skills, rules, and commands into one versioned package. |
| [Add an MCP server](/creating-skills-and-plugins/add-an-mcp-server) | Give a plugin live tools or data, not just instructions. |
| [Develop and test locally](/creating-skills-and-plugins/develop-and-test-locally) | Install a plugin from your filesystem and iterate before you publish. |
| [Publish and update](/creating-skills-and-plugins/publish-and-update) | Publish to the registry, control visibility, and ship new versions. |
## Next
* [Create a skill](/creating-skills-and-plugins/create-a-skill) - the fastest way to package a single capability.
* [Create a plugin](/creating-skills-and-plugins/create-a-plugin) - when one skill is not enough.
# Create a skill
Scaffold a skill, write its SKILL.md, and validate it before you share it.
{% hint style="info" %}
**Takeaway** A skill is a folder with a `SKILL.md`, packaged as a minimal plugin so you can version and share it. Scaffold one with `tessl skill new`, write a clear `SKILL.md`, and validate it with `tessl skill lint` and `tessl review`.
{% endhint %}
A skill teaches an agent how to do one thing: a workflow, a convention, a piece of specialized knowledge. It is agent-agnostic, so the skill you write here works across every agent Tessl supports, adapted to each on install. This page covers scaffolding a skill, writing it, and checking it is well formed. Improving how well it performs is a separate step, covered in [Improving your skills](/improving-your-skills/overview-improving-skills-and-plugins), and sharing it is covered in [Publish and update](/creating-skills-and-plugins/publish-and-update).
{% hint style="info" %}
Your agent can do all of this for you. Install Tessl's plugin creator with `tessl install tessl/plugin-creator`, or use Tessl Agent, which ships with those skills built in.
{% endhint %}
## Prerequisites
* The Tessl CLI installed (see [Installation](/introduction-to-tessl/set-up-tessl/installation)).
* A logged-in session (`tessl login`), or a `TESSL_TOKEN` in the environment.
* A workspace to attribute your work to. Examples use `engteam` as a stand-in; run `tessl workspace list` to see yours and use one of those instead.
## Scaffold the skill
`tessl skill new` creates a new skill and its `.tessl-plugin/plugin.json` manifest. Run it with no flags for an interactive wizard:
```bash
tessl skill new
```
Or pass flags to scaffold it directly:
```bash
tessl skill new --name database-migration-helper --description "When you need to create and manage database migrations" --workspace engteam --path ./database-migration-helper
```
| Flag | Purpose |
| --------------- | -------------------------------------------------------------------------------------------------------------------- |
| `--name` | Skill name, lowercase with hyphens. |
| `--description` | When the skill should trigger. This is what an agent reads to decide whether to load the skill, so make it specific. |
| `--workspace` | Workspace for the skill. Defaults to local. |
| `--path` | Directory to create the skill in. |
| `--install` | Install it into the current project immediately, so you can test it as you write. |
| `--public` | Make it public. Private by default. |
### Import an existing skill
If you already have a `SKILL.md`, `tessl skill import` generates the `.tessl-plugin/plugin.json` around it so it becomes an installable skill:
```bash
tessl skill import ./database-migration-helper --workspace engteam
```
Pass `--public` to make it public, or `--force` to overwrite an existing manifest.
## Write the SKILL.md
A skill follows the [Agent Skills specification](https://agentskills.io/specification). The file is named `SKILL.md`: YAML frontmatter, then a Markdown body.
```markdown
---
name: database-migration-helper
description: When you need to create and manage database migrations.
---
# Database migration helper
When creating a new migration:
1. Always include both `up` and `down` migrations.
2. Use a transaction where the engine supports it.
3. Test the migration on a copy of production data first.
## Example: adding a column
-- Up
ALTER TABLE users ADD COLUMN email_verified BOOLEAN DEFAULT FALSE;
-- Down
ALTER TABLE users DROP COLUMN email_verified;
## Best practices
- Never modify a migration that has already run in production.
- Keep migrations small and focused.
```
Two parts do the work:
* **`description`** (frontmatter) is how an agent discovers the skill. State what it does and when to use it. A vague description is the most common reason a skill never fires.
* **The body** is the instructions the agent follows once loaded. Keep it concise and actionable; push long reference material into a `references/` folder beside the `SKILL.md`.
## Understand the package structure
`tessl skill new` creates a Tessl package: your skill plus a manifest that makes it installable.
```
database-migration-helper/
├── .tessl-plugin/plugin.json
└── skills/database-migration-helper/SKILL.md
```
The manifest holds the package metadata:
```json
{
"name": "engteam/database-migration-helper",
"version": "1.0.0",
"description": "Create and manage database migrations",
"private": true
}
```
| Field | Meaning |
| ------------- | -------------------------------------------------------------------------------------- |
| `name` | `workspace/name`. Its identity on the registry. |
| `version` | Semantic version ([semver](https://semver.org/)). Bump it on each release. |
| `description` | Short summary shown on the registry. |
| `private` | `true` keeps it to your workspace; public is irreversible once published. |
| `skills` | Path, or array of paths, to your skill directories. Defaults to `./skills` if omitted. |
You rarely edit this by hand, except to bump `version`. The full reference is in [Configuration files](/reference/configuration).
## Validate
Lint checks the structure and frontmatter against the Agent Skills specification:
```bash
tessl skill lint ./database-migration-helper
```
Fix any errors it reports before moving on. Then, for a scored review of how well the skill is written, run `tessl review` and read the result:
```bash
tessl review run ./database-migration-helper --workspace engteam
```
Reviewing and improving are covered in full in [Check a skill's quality using review](/improving-your-skills/reviewing-skills).
## Next
* [Create a plugin](/creating-skills-and-plugins/create-a-plugin) - bundle this skill with others, or add rules and an MCP server.
* [Prove a skill works using evaluation](/improving-your-skills/evaluate-skill-quality-using-scenarios) - measure whether it improves the agent's output.
* [Publish and update](/creating-skills-and-plugins/publish-and-update) - share it with your team or publicly.
# Create a plugin
Bundle skills, rules, and commands into one versioned plugin, and choose what each piece should be.
{% hint style="info" %}
**Takeaway** Reach for a plugin when a single skill is not enough: several related skills, an always-on rule, a command, or an MCP server that belong together. Scaffold it with `tessl plugin new`, add content under the plugin directory, and validate with `tessl plugin lint`.
{% endhint %}
A single skill is already a minimal plugin. You create a plugin explicitly when you want to bundle more than one thing and version and share it as a unit: a set of related skills, a rule that captures a convention, a command the user invokes, an MCP server, or a hook. Keep a plugin focused on one responsibility; unrelated work belongs in separate plugins. Whatever it contains, Tessl installs it into each agent's native format, so one plugin serves your whole team across every agent Tessl supports.
This page covers scaffolding a plugin and choosing what each part should be. Adding an MCP server has its own page, and publishing is covered in [Publish and update](/creating-skills-and-plugins/publish-and-update).
{% hint style="info" %}
Your agent can decide the right shape and build it for you. Install Tessl's plugin creator with `tessl install tessl/plugin-creator`, or use Tessl Agent, which ships with it built in.
{% endhint %}
## Scaffold the plugin
`tessl plugin new` creates the plugin directory and its `.tessl-plugin/plugin.json`. Pass `--skill` or `--rules` to seed initial content, and set the workspace explicitly:
```bash
tessl plugin new --name engteam/api-conventions --summary "Conventions and workflows for our REST APIs" --workspace engteam --skill --skill-name write-endpoint --skill-description "When adding a REST endpoint" --path ./api-conventions
```
`engteam` is a stand-in workspace. Run `tessl workspace list` and use one of yours in its place.
| Flag | Purpose |
| ------------------------------------------------ | ------------------------------------------------------------------------ |
| `--name` | Plugin name, `workspace/plugin` format. |
| `--summary` | Short description of the plugin. |
| `--workspace` | Workspace for the plugin. Not inferred from `--name`, set it explicitly. |
| `--path` | Directory to create the plugin in. |
| `--skill`, `--skill-name`, `--skill-description` | Seed an initial skill. |
| `--rules`, `--rule-description` | Seed an initial rule file. |
| `--install` | Install into the current project immediately. |
| `--public` | Make it public. Private by default. |
## Anatomy of a plugin
A plugin is a directory with a manifest and one or more content types:
```
api-conventions/
├── .tessl-plugin/
│ └── plugin.json
├── skills/
│ └── write-endpoint/SKILL.md
├── rules/
│ └── api-style.md
├── commands/
│ └── new-migration.md
└── .mcp.json
```
The manifest declares what the plugin ships:
```json
{
"name": "engteam/api-conventions",
"version": "0.1.0",
"description": "Conventions and workflows for our REST APIs",
"private": true,
"skills": "./skills/",
"rules": "./rules/",
"commands": "./commands/",
"mcpServers": ".mcp.json"
}
```
`name`, `version`, and `description` are required. `skills` and `rules` each take a path or an array of paths and default to their conventional directory (`./skills/`, `./rules/`) when it exists; `commands` and `mcpServers` are declared explicitly. The full field reference, including `author`, `homepage`, `repository`, and `license`, is in [Configuration files](/reference/configuration).
## Choose what each piece should be
Match the behavior you want to the right content type. Add only what earns its place.
* **Skill** - a workflow the agent reaches for when a task matches its description. Most content is skills. See [Create a skill](/creating-skills-and-plugins/create-a-skill). To add a further skill to a plugin, author `skills//SKILL.md` directly.
* **Rule** - an always-on convention the agent follows without being asked. A plain Markdown file in `rules/`, no frontmatter. Use a rule when something should always hold ("errors return `problem+json`"), not just during one task.
* **Command** - a named action the user invokes on demand. A Markdown file in `commands/`. Use a command when the human wants a button to press rather than something the agent decides to do.
* **MCP server** - live tools or data, not just instructions. See [Add an MCP server](/creating-skills-and-plugins/add-an-mcp-server).
Hooks run a command automatically at an agent lifecycle event, such as after a tool runs or when a prompt is submitted. Declare them with a `hooks` (cross-agent) or `nativeHooks` (per-agent) field in `.tessl-plugin/plugin.json`; see [Configuration files](/reference/configuration) for the detail.
## Validate
Lint checks the plugin structure and manifest:
```bash
tessl plugin lint ./api-conventions
```
Confirm what will actually ship by packing it and inspecting the archive, not just linting:
```bash
tessl plugin pack ./api-conventions --output /tmp/check.tgz
tar tzf /tmp/check.tgz
```
## Next
* [Add an MCP server](/creating-skills-and-plugins/add-an-mcp-server) - give the plugin live tools or data.
* [Develop and test locally](/creating-skills-and-plugins/develop-and-test-locally) - install from your filesystem and iterate.
* [Publish and update](/creating-skills-and-plugins/publish-and-update) - share the plugin with your team or publicly.
# Add an MCP server
Ship an MCP server inside a plugin to give the agent live tools or data, not just instructions.
{% hint style="info" %}
**Takeaway** Bundle an MCP server in a plugin when the agent needs a live capability, a tool or a data source, rather than instructions. Declare it in a `.mcp.json` at the plugin root; on install, Tessl materializes it into each agent's native MCP config.
{% endhint %}
A skill gives an agent instructions. An MCP (Model Context Protocol) server gives it a tool or data at runtime: query an internal feature-flag service, look up your component library, fetch a live API schema from staging. Add one only when the plugin genuinely needs a capability the agent does not already have. If the job is "tell the agent how to do X", that is a skill, not an MCP server.
{% hint style="info" %}
This is also available through your agent: `tessl install tessl/plugin-creator`
{% endhint %}
## Declare the server
Point the manifest at a bundled `.mcp.json` file:
```json
{
"mcpServers": ".mcp.json"
}
```
The value is the literal `".mcp.json"` or `"./.mcp.json"`. Declaring it is optional: the file is discovered by convention at the plugin root either way, so the field just lets you be explicit. The file declares the servers the plugin ships, in two transports:
```json
{
"mcpServers": {
"feature-flags": {
"type": "http",
"url": "https://flags.internal.engteam.example/mcp"
},
"schema-linter": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@engteam/schema-linter-mcp"]
}
}
}
```
* **`http`** - a remote server at a URL (http or https), with optional `headers`.
* **`stdio`** - a local server Tessl launches, with a `command` and optional `args` and `env`.
Do not hard-code secrets in `.mcp.json`. If a server needs credentials, reference them from the environment rather than committing them.
## What happens on install
Each agent configures MCP servers in its own way, and that is exactly the work Tessl does for you. When someone installs the plugin, Tessl reads the bundled `.mcp.json` and writes the servers into each agent's own MCP configuration, adapting the shape to that agent. A server declared once is available in Claude Code, Cursor, and other supported agents, without the author writing per-agent config.
## Validate
Lint the plugin, then confirm the servers materialize by installing into a throwaway project and checking the agent's MCP config:
```bash
tessl plugin lint ./api-conventions
tessl install file:./api-conventions
```
For the local development loop, see [Develop and test locally](/creating-skills-and-plugins/develop-and-test-locally).
## Next
* [Create a plugin](/creating-skills-and-plugins/create-a-plugin) - the plugin that holds the server.
* [Develop and test locally](/creating-skills-and-plugins/develop-and-test-locally) - install and confirm the server appears.
* [Publish and update](/creating-skills-and-plugins/publish-and-update) - share the plugin once the server works.
# Develop and test locally
Install a plugin straight from your filesystem so you can test and iterate before publishing.
{% hint style="info" %}
**Takeaway** Install a plugin from your filesystem with `tessl install file:./my-plugin`, test it with your agent, then edit and reinstall to iterate. Nothing is published until you choose to.
{% endhint %}
You usually want to test a plugin before it reaches the registry. Tessl installs plugins directly from your filesystem, so you can iterate on the content and confirm it works with your agent first. This is also how you build context that stays with one codebase, or plugins for different parts of a monorepo.
{% hint style="info" %}
This whole loop is also handled by your agent: `tessl install tessl/plugin-creator`
{% endhint %}
## The loop
### 1. Create
Scaffold a plugin, seeding a first skill:
```bash
tessl plugin new --name engteam/my-plugin --workspace engteam --skill --skill-name my-skill --skill-description "When ..." --path ./my-plugin
```
`engteam` is a stand-in workspace; run `tessl workspace list` and use one of yours.
Add any further skills by authoring `my-plugin/skills//SKILL.md` directly. Use `tessl skill new` only for a standalone skill, not inside a plugin directory, where it would nest a separate package.
### 2. Install from the filesystem
```bash
tessl install file:./my-plugin
```
The plugin is now available to your agent, exactly as an installed one would be.
### 3. Test with your agent
* **Skills**: trigger the skill and confirm it runs and produces what you expect.
* **Rules**: ask the agent to write some code and check it follows the rule.
* **MCP servers**: confirm the server appears in the agent's tools.
### 4. Validate
Lint the structure, then pack it and inspect the archive to confirm every intended file ships. Lint alone can pass on a plugin that would drop content when packaged, so check both:
```bash
tessl plugin lint ./my-plugin
tessl plugin pack ./my-plugin --output /tmp/check.tgz
tar tzf /tmp/check.tgz
```
### 5. Iterate
Edit the content, reinstall, and test again. Repeat until it behaves.
## Plugin structure
```
/
├── .tessl-plugin/
│ └── plugin.json
├── skills//SKILL.md
├── rules/
│ └── standards.md
└── evals/
└── scenario-1/
├── task.md
├── criteria.json
└── scenario.json
```
* `.tessl-plugin/plugin.json` points at your content. If a skill sits at the plugin root use `"skills": ["."]`; if it sits under `skills/` use `"skills": ["./skills/"]`, or rely on the `./skills/` convention.
* `evals/` is present only once you have generated [scenarios](/improving-your-skills/overview-improving-skills-and-plugins).
The complete `.tessl-plugin/plugin.json` reference is in [Configuration files](/reference/configuration).
## Next
* [Publish and update](/creating-skills-and-plugins/publish-and-update) - share the plugin once it works locally.
* [Improving your skills](/improving-your-skills/overview-improving-skills-and-plugins) - prove and improve quality before you rely on it.
# Publish and update
Publish a skill or plugin to the registry, control who can install it, and ship new versions.
{% hint style="info" %}
**Takeaway** Publish a skill or plugin with `tessl skill publish` or `tessl plugin publish`. It goes to your workspace as private by default. Bump the version to ship an update, and request public visibility only when you want anyone to install it.
{% endhint %}
Publishing puts a skill or plugin on the [Tessl Registry](https://tessl.io/registry) so it can be installed by name. This page covers the publish command, visibility, and versioning. Rolling context out across many repositories, and the GitHub-based publishing flow, are covered in [Distribute](/distribute/distributing-via-registry).
{% hint style="info" %}
Your agent can run this step too: `tessl install tessl/plugin-creator`
{% endhint %}
## Publish
From the skill or plugin directory, or with a path:
```bash
tessl plugin publish ./api-conventions --workspace engteam
```
`engteam` is a stand-in workspace. Run `tessl workspace list` and use one of yours.
A single skill uses the same flow through `tessl skill publish`. Both publish to your workspace as **private**: only workspace members can install it.
| Flag | Purpose |
| ---------------------------- | --------------------------------------------------------------------------------- |
| `--workspace` | Workspace to publish under. Required when non-interactive. |
| `--dry-run` | Run every pre-publish check without publishing. Use it first. |
| `--bump patch\|minor\|major` | Bump the version automatically if the current one already exists on the registry. |
| `--skip-evals` | Skip publishing the eval scenarios in `evals/`. |
| `--version` | Publish a specific version (plugin publish). |
On publish, Tessl lints and reviews the content automatically, and the review score appears on the registry. See [Check a skill's quality using review](/improving-your-skills/reviewing-skills).
## Publication checks and blocked versions
An accepted upload is not necessarily available to install yet. Tessl runs publication checks asynchronously after the upload. The publish command tells you whether the version is available, blocked, still being checked, or could not be checked.
Check the exact version that you uploaded:
```bash
$ tessl plugin info engteam/api-conventions@1.2.0
```
If your organization or workspace enables a minimum skill review score policy, every skill in the plugin version must meet that score. Tessl does not average scores across the skills. For example, with a minimum score of 80, scores of 91 and 78 block the version, while scores of 91 and 85 pass this check. A score equal to the minimum passes.
The version must also pass every other publication check that applies to it. A version is unavailable while blocked and cannot be overwritten. Use `tessl plugin info` to check its publication status and the reported reason. For a score below the threshold, open the exact version in the Tessl Registry, select **Quality**, and use the per-skill findings to improve the failing skill. Then bump the version and publish the higher version.
If the publication or moderation status is pending and the version is unavailable, wait and check the same version again. An available version can still have quality or security reviews running in the background; those reviews do not delay its use.
If a required review did not run because credits were unavailable, restore credits or ask your organization administrator for help, then publish a higher version. Restoring credits does not automatically retry the review for the existing version. If a review completed without a score, contact Tessl support before publishing a higher version. These outcomes do not mean that the skill itself needs improvement. For other system errors, contact Tessl support.
Versions blocked by policy are not available for distribution, including Claude marketplace sync. The policy provides a publish-time quality gate without requiring a CI step.
## Install it
Once published, you or your workspace can install it in any project:
```bash
tessl install engteam/api-conventions
tessl install engteam/api-conventions@1.2.0
```
To let teammates install a private plugin, add them to the workspace with `tessl workspace add-member`. See [Workspaces](/reference/workspaces).
## Ship an update
1. Make your changes.
2. Bump `version` in `.tessl-plugin/plugin.json` following [semantic versioning](https://semver.org/): patch for fixes, minor for backward-compatible additions, major for breaking changes.
3. Validate with `tessl plugin lint`.
4. Publish again.
```bash
tessl plugin publish ./api-conventions --workspace engteam
```
Anyone who installed it updates by running `tessl install engteam/api-conventions` again, which fetches the latest version.
## Make it public
Public means anyone can discover and install it. It is irreversible, so it needs approval first:
1. Open your plugin or skill in the [Tessl Registry](https://tessl.io/registry) and sign in.
2. Select **Actions** then **Make Public**, and confirm the request.
Once approved, set the visibility and publish again:
* **A plugin** takes its visibility from the `private` field in `.tessl-plugin/plugin.json`. Set `"private": false` and publish.
* **A skill** can be published public directly with `--public`:
```bash
tessl skill publish ./my-skill --workspace engteam --public
```
See [Sharing with your team and publicly](/distribute/sharing-plugins-publicly) for more.
## Remove or deprecate
Published something you should not have, or no longer want it installed? There is no hard delete, but two options cover it. Both use `tessl plugin` whether you published a skill or a plugin.
To drop one skill from a plugin that contains others, delete the skill file and publish a new version with `tessl plugin publish`. The old version remains on the registry; the new version simply omits the skill.
* **Unpublish** removes a version as if it was never published. It has a short time limit, a couple of days after publishing:
```bash
tessl plugin unpublish --plugin engteam/api-conventions@0.1.0
```
* **Archive** hides it from search but keeps it working for anyone who already references it, so existing installs do not break:
```bash
tessl plugin archive --plugin engteam/api-conventions --reason "superseded"
```
To simply stop new people finding it, you can also make it private again: set `"private": true` in the manifest and republish, or change visibility from the registry UI.
## Next
* [Distributing via registry](/distribute/distributing-via-registry) - archive, unpublish, and monitor usage.
* [Distribute plugins across multiple repositories](/distribute/distribute-plugins-across-multiple-repositories) - push plugins across many repos.
* [Improving your skills](/improving-your-skills/overview-improving-skills-and-plugins) - raise quality before you publish widely.
# Overview
{% hint style="info" %}
**Takeaway** Know whether a skill is any good, and make it better. Use a review for fast feedback on the skill itself. Run an evaluation when you need proof it changes how an agent behaves, for example before you share it with your team.
{% endhint %}
This page is the place to start if you want to improve a skill. It walks through the two ways Tessl assesses skill quality, review and evaluation, and how you use each to make a skill better.
A review and an evaluation answer different questions.
| | |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Review** | Reads the skill itself and scores how well it is written: whether the description is clear enough for an agent to load it at the right time, and whether the content is specific, actionable, and complete. Runs in under a minute and needs nothing but the skill. |
| **Evaluation** | Runs an agent on real tasks with and without the skill, then scores the difference. Tells you whether the skill actually changes what the agent does, not just whether it reads well. Takes longer and runs against a set of scenarios. |
## Building trust in a skill
Both reviews and evaluations help you assess different aspects of skill quality and guide improvement. In practice it helps to treat them as different levels of rigour, applied according to how much trust you need to build in the skill.
For example, if you are building a skill for yourself to use day to day, and you make quick ad hoc improvements as you go, a review may be enough. You will notice when a skill misfires and fix it, using review to guide your improvements.
If you are putting the skill into a shared repository to shape how other people's agents behave, you may decide this needs an extra level of rigour. An evaluation gets ahead of that: it proves the skill does what it claims, and the scenarios you generate are saved with the skill, so anyone who edits it later can re-run them and confirm it still works. They become a regression test for the skill.
Over the following pages we walk through both review and evaluation in depth.
## Quick start: Skill Optimizer
Alternatively, Tessl's [Skill Optimizer plugin](https://tessl.io/registry/tessl/skill-optimizer) runs this whole progression for you. It includes both review and evaluation and applies them as needed. Install it, point your agent at a skill, and it reviews the skill, applies quick win improvements, and escalates into evaluation when the skill is worth testing harder, generating evaluation scenarios, diagnosing failures, and re-running until the scores improve.
```bash
tessl install tessl/skill-optimizer
```
Then ask your agent to optimise the skill. Use Skill Optimizer when you want the full cycle handled for you. Use the commands directly, covered in the next pages, when you want control over each step.
## Next
* [Check a skill's quality using review](/improving-your-skills/reviewing-skills) - run a review, read the score, and apply fixes with `tessl review`.
* [Prove a skill works using evaluation](/improving-your-skills/evaluate-skill-quality-using-scenarios) - generate scenarios and measure a skill's impact with `tessl eval`.
* To enforce a quality bar across your organisation, for example gating pull requests on a review score or scoring against your own standards, see [Codifying and enforcing your skill standards](/codifying-and-enforcing-your-skill-standards/overview).
# Check a skill's quality using review
Run a review to score how well a skill is written, read the result, and apply fixes.
{% 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).
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" %}
`tessl skill review` has been removed; `tessl review` replaces it. See [Migrate from skill review](/improving-your-skills/migrate-from-skill-review).
{% 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).
```bash
# View the most recent run
tessl review view --last
# View a specific run by ID
tessl review view
# 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. The loop runs up to `--max-iterations` times (default 3, maximum 10). It stops early once the score reaches the `--threshold` target (default 90). The highest-scoring version wins, so if no iteration improves on the original skill, no changes are applied.
```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
```
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).
## 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).
## 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.
An organization or workspace can also require a minimum review score before a plugin version is available. Every skill in the version must meet the threshold; scores are not averaged. If a version is blocked, inspect that exact version, use the review findings to improve the failing skill, then publish a higher version. See [Publication checks and blocked versions](/creating-skills-and-plugins/publish-and-update#publication-checks-and-blocked-versions) and [Codifying and enforcing your company's skill standards](/tutorials/codifying-and-enforcing-skill-standards).
## 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) - 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) - build a custom rubric, set an organisation-wide quality bar, and gate pull requests on it.
# Migrate from skill review to Tessl Review
How to switch from the removed tessl skill review to Tessl Review, and what to expect
Tessl Skill Review let you quickly evaluate the quality of a skill against best practices, providing scores on validation, content and description quality. It has been superseded by Tessl Review.
This page explains what changed, the impact on how skill quality is scored, and how to switch.
{% hint style="warning" %}
**`tessl skill review` has been removed.** Running it now fails with a message pointing here. Use `tessl review run` instead. The mapping below covers every flag, including the one flag that has no replacement yet.
{% endhint %}
## What changed, and why
Tessl Review brings skill review into Tessl's wider agentic evaluation architecture.
Tessl Skill Review evaluated individual `SKILL.md` files in a single pass against a fixed rubric. With Tessl Review, the review runs through an agent that works across the whole skill and its connected files, and reasons over multiple steps to reach its result.
This allows us to introduce several improvements:
* **Full-bundle review.** The review reads your entire skill, not just `SKILL.md`. References, scripts, and assets are all in scope, so nothing in your skill is missed.
* **Customisable rubric.** Fork the default quality scoring rubric and define what "good" means for your organisation. Set it as your workspace default and every review uses your standard.
* **Review history.** Reviews are stored and queryable with `tessl review list` and `tessl review view`, so you have a persistent record of quality over time.
* **Built for CI.** `--json` and `--threshold` gate pull requests on a review score, exactly as before.
{% hint style="info" %}
**Scores returned by Tessl Review may differ slightly from skill review.** Because the review now runs as an agent over your full skill bundle rather than a single pass, Tessl Review scores are more accurate and more reflective of real skill quality. And because the agent reasons over multiple steps, it can reach a clearer, better-founded conclusion than skill review's single pass.
{% endhint %}
The shift to Tessl Review also makes it easier for us to expand what reviews can do. You can now run a security scan directly from the CLI with `tessl review run security` — see [Protect against insecure skills](/tutorials/protecting-against-insecure-skills). Coming soon:
* Choose the model a review runs on.
## What changes on the CLI
{% hint style="info" %}
**Reviews require authentication.** `tessl review run` requires you to be signed in. Sign in with `tessl login`, or set a `TESSL_TOKEN` API key in CI.
{% endhint %}
Most workflows map across directly:
| Workflow | Removed (`tessl skill review`) | New (Tessl Review) |
| ---------------------------------- | ------------------------------------------ | ------------------------------------------------- |
| Run a review | `tessl skill review ` | `tessl review run ` |
| Review one skill from a plugin | `tessl skill review --skill ` | Point `tessl review run` at the skill's directory |
| Improve a skill automatically | `tessl skill review --optimize` | `tessl review fix` |
| Gate CI on a score | `--threshold ` | `--threshold ` (unchanged) |
| Output machine-readable results | `--json` | `--json` (unchanged) |
| Limit improvement iterations | `--max-iterations` (with `--optimize`) | `--max-iterations` (on `tessl review fix`) |
| Auto-apply fixes without prompting | `--yes` (with `--optimize`) | `--yes` (on `tessl review fix`) |
| Attribute a run to a workspace | - | `--workspace` (new) |
| Score against a custom rubric | - | `--review-plugin` (new) |
| Label a run for history | - | `--label` (new) |
| Force a fresh run | - | `--force` (new) |
| Choose the review model | `--model ` | No replacement yet, see Coming soon above |
What stays the same:
* The default rubric (Anthropic best practices) is unchanged. Reviews still score the same three components out of the box: validation, description, and content.
* Reviews still produce a 0-100 score.
* `--json` with `--threshold` still gates CI through the exit code.
* The GitHub Action still drives reviews in CI.
What's new to know:
* **Authentication.** `tessl review run` and `tessl review fix` run against your workspace, so you need to be signed in (`tessl login`, or a `TESSL_TOKEN` API key in CI) and run against a workspace (pass `--workspace`, or pick one when prompted). Any workspace member can run reviews.
* **Asynchronous by default.** A review runs server-side. `tessl review run` polls until it finishes and then prints the score, so a single command still feels the same. Press Ctrl+C to detach and pick the run back up later with `tessl review view --last`.
## Migrating your CI
Replace the `tessl skill review` step with `tessl review run`, add a workspace, and keep your threshold:
```sh
tessl review run ./my-skill --workspace --json --threshold 80
```
`--workspace` is required when `--json` is set, because a non-interactive run cannot prompt for one. In CI, authenticate with a `TESSL_TOKEN` repository secret. For a complete GitHub Actions workflow, see [Review, lint & publish with GitHub Actions](/distribute/review-and-publish-with-github-actions).
## Next steps
* [Check a skill's quality using review](/improving-your-skills/reviewing-skills) - the full guide to running reviews, customising the rubric, and gating CI
* [`tessl review run` reference](/reference/cli-commands#tessl-review-run) - all flags
* [Review, lint & publish with GitHub Actions](/distribute/review-and-publish-with-github-actions) - run reviews on pull requests
# Prove a skill works using evaluation
Generate scenarios, run an evaluation, and read the score difference to see whether a skill actually changes what an agent produces.
{% hint style="info" %}
**Takeaway** Generate scenarios from a skill, run an evaluation, and read the score difference to see whether the skill actually changes what an agent produces. Scenarios are saved with the skill, so they become a regression test you re-run after every change.
{% endhint %}
By default, an evaluation runs an agent on real tasks twice, once without the skill and once with it, then scores the difference. You can also declare your own variants to compare several configurations on the same tasks. That difference is the skill's value: proof it changes what the agent does, not just that it reads well. Where a review checks the skill itself, an evaluation measures its effect.
Evaluation is more rigorous than review and takes longer to set up and run. Reach for it when you need confidence a skill works, for example before you publish it or share it into a repository where you will not see how others' agents use it.
You can evaluate a single skill against generated scenarios, or evaluate context files against real tasks taken from your codebase's commit history. Both run through the same `tessl eval` commands.
{% hint style="info" %}
All the steps on this page are also available through your agent. Install Tessl's Skill Optimizer to generate scenarios, run evaluations, and improve skills without leaving your editor: `tessl install tessl/skill-optimizer`
{% endhint %}
## Skills are evaluated inside Tessl plugins
A Tessl plugin is a structure that bundles the skills, rules, and documentation an agent needs for an area of context, packaged so it can be versioned and shared. An evaluation generates scenarios and produces results, and a plugin is the natural place to keep them with the skill they belong to.
For this reason `tessl eval run` expects the generated scenarios to live inside the plugin, and the shorthand `tessl eval run ./my-skill` expects a directory containing a `.tessl-plugin/plugin.json`. If you have a standalone skill, import it into a plugin first:
```bash
tessl skill import ./my-skill
```
## Generate scenarios
Scenarios are the tasks an agent is assessed against. Generate them from the plugin:
```bash
tessl scenario generate ./my-skill
```
Each generated scenario is put through a feasibility check on the server. Only scenarios that pass are saved, so the generator gives you tests that actually exercise the skill rather than filler.
`--count` sets how many scenarios to target, and defaults to 3. Pass a higher number to cover more of what the skill claims to do. For a narrowly scoped skill the generator may return fewer than requested, because it will not save scenarios that fail the feasibility check.
```bash
tessl scenario generate ./my-skill --count 5
```
Generation runs server-side. Check progress with `tessl scenario list --mine`, then download the scenarios once it completes:
```bash
tessl scenario download --last
```
When run from inside a plugin directory (or any subdirectory of one), `tessl scenario download` writes scenarios directly into the plugin's `evals/` directory, so they are immediately runnable by `tessl eval run`. When run outside a plugin, it writes to an `evals/` directory relative to your current directory. Override the location with `--output`, and choose whether new scenarios merge with or replace existing ones with `--strategy merge` (the default) or `--strategy replace`. The command always prints where the files landed.
{% hint style="warning" %}
**The default destination is the plugin's `evals/`, wherever you run from inside the plugin.** Two consequences follow from this:
* `--strategy replace` clears the plugin's `evals/` directory before writing, even when you run from a subdirectory such as `src/`. It does not target `src/evals`. Pass `--output ` to replace a different directory.
* `--strategy merge` (the default) overwrites existing scenario files with the same name. Scenario names are canonical (`scenario-1/`, `scenario-2/`, …), so a re-download replaces `scenario-1/` and any hand-edits in it. Copy edited scenarios you want to keep to a directory the download will not touch, or download with `--output` to a separate directory.
{% endhint %}
The scenarios are saved with the skill, so anyone who changes it later can re-run the same scenarios and confirm it still behaves as expected.
You do not have to generate scenarios. You or your agent can write them by hand instead, as long as they sit in the plugin's `evals/` directory, one scenario per subdirectory. See [File formats](#file-formats) for the structure.
### Generate scenarios from your codebase
Instead of generating scenarios from a skill, you can build them from real changes in your repository, so the tasks reflect work your team actually does. Point `tessl scenario generate` at a repository with commit hashes or PR numbers:
```bash
# From commits
tessl scenario generate org/repo --commits abc123,def456 --workspace engteam
# From pull requests
tessl scenario generate org/repo --prs 42,107 --workspace engteam
```
Tessl analyses each diff and reconstructs the intent of the change as a task brief and a scoring rubric. The starting state has your context files stripped out, so the agent solves the task without them.
`--context` tells Tessl which files are context files. The patterns are saved in each scenario as the codebase fixture's exclude list. When omitted, Tessl excludes `*.mdc`, `*.md`, `tile.json`, `.tessl-plugin/plugin.json`, `tessl.json`, and `.tessl/` by default.
To browse recent commits and choose which to turn into scenarios, use `tessl repo select-commits org/repo`. It accepts `--keyword`, `--author`, `--since` / `--until`, and `--count`, and prints a table of commit hashes to pass to `generate`.
{% hint style="info" %}
Your GitHub or GitLab account must be connected in workspace settings.
{% endhint %}
Because these scenarios start from a state with your context files stripped out, pass `--context` again at run time with a glob matching those files. This adds a with-context variant on top of the baseline so you can measure the delta:
```bash
tessl eval run ./my-skill/evals/ --context 'src/**/*.knowledge.md'
```
Match the `--context` glob to the files each scenario excludes. With no `--context`, only the baseline runs.
## Run an evaluation
```bash
tessl eval run ./my-skill
```
By default, the agent solves each scenario twice, without the skill and with it, and a judge scores both against a per-scenario rubric. A run with explicit variants solves the same scenarios for each configuration instead. The run reports each score and any applicable difference. Runs can take a while; pressing Ctrl+C detaches and the run continues server-side.
Label a run to find it again later:
```bash
tessl eval run ./my-skill --label "baseline"
```
```bash
# List your recent runs
tessl eval list --mine
# View a run, including the per-scenario breakdown
tessl eval view --last
tessl eval view abc123
# Retry a failed run
tessl eval retry abc123
```
## Read the result
A run produces output like this:
```
Eval Results: baseline
Agent: claude:deepseek-v4.1-flash
Variants: Without this plugin, With this plugin
Status: Completed
Scenario: Commit message formatting for complex refactor
Without this plugin
Check Score
------------------------------------------
Conventional Commits format 30/30 (100%)
Valid type 0/20 (0%)
Subject line <= 72 chars 0/30 (0%)
Blank line separator 20/20 (100%)
Total 50/100 (50%)
With this plugin
Check Score
------------------------------------------
Conventional Commits format 30/30 (100%)
Valid type 20/20 (100%)
Subject line <= 72 chars 30/30 (100%)
Blank line separator 20/20 (100%)
Total 100/100 (100%)
Scenario: Type selection for a small fix
Without this plugin
Total 90/100 (90%)
With this plugin
Total 95/100 (95%)
Summary
Scenarios: 3 completed
Without this plugin avg: 71%
With this plugin avg: 92%
```
The score difference tells you what the skill is worth:
* **A large positive difference** means the skill reliably moves the agent toward the right behaviour.
* **Little or no difference** means the agent already did the task well without the skill, or the skill is not landing.
* **A small negative difference** is usually normal model variance, not evidence the skill is harmful.
* **A large or consistent negative difference** is a real sign the skill is confusing the agent or pushing it toward unhelpful behaviour, and the content needs work.
Read the per-scenario breakdown rather than just the headline average, since a strong result on one scenario can hide a weak one on another.
### Outcome and activation
A standard evaluation measures **outcome**: with the context forced on, does the agent produce better work against the rubric. It does not test whether the agent would have loaded the skill on its own.
To measure **activation**, whether the agent picks up the skill itself without being told to, add `--skip-forced-context-activation`. A skill can score well on outcome but fail to activate, which means it would not help in practice because the agent never reaches for it.
```bash
# Measure activation only: don't force the context, and skip outcome scoring
tessl eval run ./my-skill --skip-forced-context-activation --skip-scoring
```
The two flags are independent: `--skip-forced-context-activation` stops forcing the context so activation can be observed, and `--skip-scoring` skips rubric scoring. Used together they give a pure activation check.
Example activation output:
```
Activation Results
Agent: claude:deepseek-v4.1-flash
Variants: baseline, with context
Status: Completed
Injected context
Plugin: format-commit-messages@0.1.0
Scenario Activated skills
--------------------------------------------------------------------
1. Conventional Commits format and type selection format-commit-messages
2. Commit message formatting for complex refactor format-commit-messages
3. Conventional Commits with multi-line message —
```
`—` in the Activated skills column means the skill was not selected by the agent on its own. A skill that does not activate is a description problem, best fixed with a [review](/improving-your-skills/reviewing-skills). A skill that activates but does not improve the outcome is a content problem to fix in the skill body.
## Comparing test variants
A test variant is one configuration in an evaluation. Every variant solves the same scenarios and is scored against the same rubric, so you can compare models, agents, fixture combinations, or revisions of a plugin.
Declare variants with `--variant-json`. Give the flag a JSON array or the path to a JSON file:
```bash
$ tessl eval run ./my-skill --variant-json ./variants.json
```
The run solves only the variants you list. It does not add a baseline for you, so include one in the list when you want to compare against it (see [Compare a plugin with no plugin](#compare-a-plugin-with-no-plugin)). `--variant-json` cannot be combined with `--skip-baseline` or `--arms-json`. A JSON file can be up to 1 MiB.
`--arms-json` is deprecated but still works. Use `--variant-json` for new runs.
Each variant needs a unique label. A label uses lowercase letters, digits, hyphens, and underscores, starts with a letter or digit, and is at most 64 characters, so a model name such as `kimi-k2.6` needs a label without the dot. Fields you omit use the run-level agent, model, and fixture setup. The bare string `"baseline"` is the exception: it removes the run-level subject fixture. An object variant, including `{ "label": "baseline" }`, uses the ordinary object rules and includes that fixture.
```json
[
{ "label": "opus", "model": "claude-opus-5" },
{ "label": "sonnet", "model": "claude-sonnet-5" },
{ "label": "haiku", "model": "claude-haiku-4-5" }
]
```
### Variant spec reference
| Field | Type | Default | What it does |
| --------------- | ------------ | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `label` | string | required | Names the variant. Labels are unique within a run and appear with the results. |
| `agent` | string | the run's agent | Uses a different agent for this variant. |
| `model` | string | the run's model | Uses a different model for this variant. |
| `fixtures` | object | inherits | Replaces, adds, or removes named fixtures for this variant. A value replaces or adds a fixture, `null` removes it, and omitted names inherit. |
| `agentMustRead` | string array | none | Names fixtures whose installed locations the agent must read before starting the task. |
`agentMustRead` contains fixture names, not paths or file content. For a commit or directory fixture, the agent is told that fixture's `installPath`. For a plugin fixture, the agent is told the locations of the installed skills. A name must identify a fixture available to that variant after its overlay has been applied.
For example, this scenario supplies a commit fixture at the repository root and excludes draft instructions:
```json
{
"fixtures": {
"repository": {
"type": "commit",
"repoUrl": "https://github.com/org/repo.git",
"ref": "abc1234",
"installPath": ".",
"exclude": ["docs/drafts/**"]
}
}
}
```
The variant adds a directory fixture named `guidance` and names both fixtures in `agentMustRead`. The agent is told where the repository and guidance fixtures were installed.
The CLI packages the contents of a `localPath` fixture and uploads them for the evaluation. The evaluation agent can access that uploaded content, so point `localPath` only at files you intend to share.
```json
[
{
"label": "with-guidance",
"fixtures": {
"guidance": { "localPath": "./variants/guidance" }
},
"agentMustRead": ["repository", "guidance"]
}
]
```
### Fixture values in a variant
A fixture value in a variant takes one of two forms:
* `{ "localPath": "./path" }` for content on your disk. The path is relative to the directory you run the command from. A plugin directory is installed as a plugin. Any other directory is copied into the solution at its path relative to your repository root. `localPath` must be the only key in the object. The CLI uploads each distinct path once.
* A published plugin, declared by name and version. The run resolves it from the registry, so nothing is uploaded:
```json
{
"label": "published",
"fixtures": {
"context": {
"definition": { "type": "plugin", "name": "engteam/my-skill", "version": "1.2.0" }
}
}
}
```
Other fixture types need uploaded content, so declare them with `localPath` and let the CLI upload them. A `localPath` that resolves outside your Git repository (or outside the source directory, when it is not in a repository) is refused unless you pass `--allow-unsafe-fixture-paths`.
### Compare a plugin with no plugin
Passing `./my-skill` already supplies the run-level subject fixture. The bare string `"baseline"` is a special case that removes that fixture. Every object variant, including `{ "label": "baseline" }`, inherits it, so use an object with no `fixtures` to run the plugin once.
```json
[
"baseline",
{
"label": "with-plugin"
}
]
```
### Repeats and limits
Repeat each variant with `--runs` (or `-n`) when a decision depends on a small score difference. One attempt per variant cannot show how much agent behavior varies between runs. If two variants' score spreads overlap heavily, the run does not show a real difference between them. It does not show that they are equivalent either. Add repeats before you decide.
* `--runs` accepts 1 to 10.
* A run can plan at most 2,000 solves. The count is scenarios × variants × runs. Reduce one of them if the product is higher.
* A variant can set at most 100 fixtures.
* The variant list can contain at most 50 `localPath` references, which resolve to at most 20 different local directories.
## Choose how rigorous to be
Evaluation is a toolkit, not a single fixed test. Scale the rigour to how much confidence you need.
* **More scenarios.** Generate a higher `--count` to cover more of what the skill claims to do.
* **Repeated runs.** An evaluation runs a real agent, and agents are non-deterministic, so a single run can mislead. Pass `--runs` (or `-n`) to run each scenario several times and average out the variance. Worth doing before you publish.
* **Different agents.** Run the evaluation against more than one agent with `--agent` to check the skill holds up across the models your team uses.
* **Quality filter.** Pass `--quality-check` to exclude scenarios the platform judges low-feasibility, rubric-leaking, or low-signal at run time, a stricter filter than the one applied at generation.
* **Skip the baseline.** Pass `--skip-baseline` to run only the with-context variant when you do not need the comparison.
* **Override the scorer.** Pass `--scorer-agent` to score with a different agent from the one solving the tasks.
## Passing secrets to an evaluation
Some scenarios need external credentials, for example an API key or a database URL. The `--env-file` flag encrypts a local `.env` file client-side and injects the variables into the eval sandbox, where setup scripts and the agent inherit them:
```bash
tessl eval run ./my-skill --env-file ./secrets.env
```
The file uses standard `KEY=VALUE` lines; blank lines and `#` comments are ignored. The CLI rejects reserved keys at submit time, including `LITELLM_ADMIN_KEY`, `LITELLM_MASTER_KEY`, `UPLOAD_WORKSPACE`, `DOWNLOAD_WORKSPACE`, and any key prefixed `AWS_`, `S3_`, `DAYTONA_`, or `RECIPE_RUN_`. Rename conflicting keys before running.
## Choosing an agent
By default an evaluation runs against agent `claude`, and in the US region model `deepseek-v4.1-flash`. Choose a different agent and model with `--agent` and `--model`. To compare models or agents in one run, set `model` or `agent` on explicit [test variants](#comparing-test-variants).
The default model and the available models both depend on the region you are connected to: the open-weight models below (DeepSeek, GLM, Kimi, Qwen, MiniMax, GPT OSS, and Nemotron) are not offered in the EU region, which defaults to a Claude model instead. Run `tessl eval run --list-agents` to print the models and the default for your region.
```bash
$ tessl eval run ./my-skill --agent claude --model claude-opus-4-8
```
`--agent` values: `claude`, `codex`, `tessl`. Pair each with a `--model` value from its tab below.
{% tabs %}
{% tab title="Claude" %}
| Model | `--model` value |
| ----------------- | ------------------- |
| Claude Fable 5 | `claude-fable-5` |
| Claude Opus 5 | `claude-opus-5` |
| Claude Opus 4.8 | `claude-opus-4-8` |
| Claude Opus 4.7 | `claude-opus-4-7` |
| Claude Opus 4.6 | `claude-opus-4-6` |
| Claude Sonnet 5 | `claude-sonnet-5` |
| Claude Sonnet 4.6 | `claude-sonnet-4-6` |
| Claude Opus 4.5 | `claude-opus-4-5` |
| Claude Sonnet 4.5 | `claude-sonnet-4-5` |
| Claude Haiku 4.5 | `claude-haiku-4-5` |
| {% endtab %} | |
{% tab title="Other hosted models" %}
Also served through `--agent claude`.
| Model | `--model` value |
| ----------------------------- | ------------------------ |
| DeepSeek V4.1 Flash (default) | `deepseek-v4.1-flash` |
| GLM 5.3 | `glm-5.3` |
| MiniMax M3 | `minimax-m3` |
| GPT OSS 120B | `gpt-oss-120b` |
| Nemotron 3 Ultra | `nemotron-3-ultra-nvfp4` |
| {% endtab %} | |
{% tab title="Codex" %}
| Model | `--model` value |
| ------------- | --------------- |
| GPT 6 Astra | `gpt-6-astra` |
| GPT 6.1 Sol | `gpt-6.1-sol` |
| GPT 6 Sol | `gpt-6-sol` |
| GPT 6 Luna | `gpt-6-luna` |
| GPT 5.6 Sol | `gpt-5.6-sol` |
| GPT 5.6 Terra | `gpt-5.6-terra` |
| GPT 5.6 Luna | `gpt-5.6-luna` |
| GPT 5.5 | `gpt-5.5` |
| GPT 5.4 | `gpt-5.4` |
| GPT 5.4 Mini | `gpt-5.4-mini` |
| GPT 5.4 Nano | `gpt-5.4-nano` |
| GPT 5.3 Codex | `gpt-5.3-codex` |
| GPT 4.1 | `gpt-4.1` |
| GPT 4.1 Mini | `gpt-4.1-mini` |
| {% endtab %} | |
{% tab title="Tessl" %}
| Model | `--model` value |
| ------------------- | ------------------------ |
| Claude Fable 5 | `claude-fable-5` |
| Claude Opus 5 | `claude-opus-5` |
| Claude Opus 4.8 | `claude-opus-4-8` |
| Claude Opus 4.7 | `claude-opus-4-7` |
| Claude Opus 4.6 | `claude-opus-4-6` |
| Claude Sonnet 5 | `claude-sonnet-5` |
| Claude Sonnet 4.6 | `claude-sonnet-4-6` |
| Claude Opus 4.5 | `claude-opus-4-5` |
| Claude Sonnet 4.5 | `claude-sonnet-4-5` |
| Claude Haiku 4.5 | `claude-haiku-4-5` |
| DeepSeek V4.1 Flash | `deepseek-v4.1-flash` |
| GLM 5.3 | `glm-5.3` |
| MiniMax M3 | `minimax-m3` |
| GPT OSS 120B | `gpt-oss-120b` |
| Nemotron 3 Ultra | `nemotron-3-ultra-nvfp4` |
| {% endtab %} | |
| {% endtabs %} | |
## Evaluations when you publish
Publishing a plugin to the registry runs an evaluation as part of publishing, and the results appear on the registry. The evaluation is optional: pass `--skip-evals` to publish without it, or `--with-scenario-quality-check` to apply the quality filter to the publish-time run. See [Distributing via registry](/distribute/distributing-via-registry).
## Prerequisites
* Authentication, either a logged-in session, confirmed with `tessl whoami` and started with `tessl login`, or a `TESSL_TOKEN` API key in the environment.
* Workspace access at Publisher level or above.
* A Tessl project, so Tessl knows which repository an evaluation belongs to and your results stay tied to your codebase over time. Create one with `tessl project create --workspace engteam`, link an existing one with `tessl project link`, and repair a broken link with `tessl project repair`. See [Projects overview](/projects/overview).
A plugin that holds evaluations looks like this on disk:
```
my-plugin/
├── .tessl-plugin/
│ └── plugin.json workspace, name, version
├── skills//SKILL.md
├── tessl.json links the directory to a Tessl project
└── evals/
└── scenario-name/
├── task.md the task brief the agent sees
├── criteria.json the scoring rubric
└── scenario.json fixture and include declarations
```
## File formats
### task.md
Free-form markdown, and the only file the agent sees. Typically structured with problem, expected behaviour, and acceptance criteria sections. Edit it freely before running.
### criteria.json
Defines how a solution is scored, as a weighted checklist:
```json
{
"context": "Brief description of what is being evaluated.",
"type": "weighted_checklist",
"checklist": [
{
"name": "fixes_syntax_error",
"description": "The solution adds the missing closing parenthesis.",
"max_score": 1,
"category": "INTENT"
}
]
}
```
Each checklist item carries a `category`: `INTENT`, `DESIGN`, `MUST_NOT`, `MINIMALITY`, `REUSE`, `INTEGRATION`, or `EDGE_CASE`. The score is the sum of awarded scores over the sum of maximum scores, as a percentage, and the grader can award partial credit.
### scenario.json
Optional. Declares fixtures, included files, and setup scripts. A skill scenario can simply list `include` paths to copy into the working directory. A codebase scenario carries a commit fixture with the repository URL, the starting commit, and the context exclude patterns. See the [configuration reference](/reference/configuration) for the full schema.
## Next
* [Codifying and enforcing your skill standards](/codifying-and-enforcing-your-skill-standards/overview) - set an organisation-wide quality bar and enforce it.
* [Troubleshooting reviews and evaluations](/improving-your-skills/troubleshooting-reviews-and-evals) - what to do when a run fails or scores look wrong.
# Compare with test variants
Compare models, agents, skill revisions, and context using test variants, with examples of how to interpret the results.
Use test variants to try different configurations on the same tasks. You can compare models, choose between skill rewrites, or check whether an agent uses a skill without being prompted.
A **test variant** specifies the model, agent, and files available to the agent. Each variant solves the same scenarios and is scored against the same rubric. A run can include as many variants as fit in its [solve limit](#plan-the-run-size).
If you are new to evaluations, start with [Prove a skill works using evaluation](/improving-your-skills/evaluate-skill-quality-using-scenarios). The examples below build on that workflow.
## Set up a comparison
Declare your variants with `--variant-json`, as a JSON array or the path to a JSON file:
```bash
$ tessl eval run ./my-skill --variant-json ./variants.json
```
The examples below show the JSON array for each comparison. Replace placeholder models, agents, and paths with your own values. The run solves only the variants you list, so add a baseline yourself when you need one. The full field reference is in [Comparing test variants](/improving-your-skills/evaluate-skill-quality-using-scenarios#comparing-test-variants).
A fixture is a set of files supplied to the agent. The plugin you evaluate is the fixture named `context`. The `fixtures` field changes fixtures by name for one variant:
* A value replaces the fixture, or adds it when the name is new. Set `context` to another directory to test a different version of the plugin.
* `null` removes the fixture. Set `context` to `null` to measure the agent without the plugin. Other fixtures remain available.
* A name you leave out keeps the fixture the scenario and run supply.
Refer to a local directory with `{ "localPath": "./path" }`. Paths are relative to the directory where you run the command. The CLI uploads each distinct path once.
## Make the results useful
Run each scenario more than once. Agents can produce different results from the same input, so a single attempt tells you little about consistency. Start with three repeats (`-n 3`) and increase the count when results vary widely or the decision needs more confidence.
When you want to measure how much a skill helps, include a **baseline** without it:
```json
{ "label": "no-skill", "fixtures": { "context": null } }
```
This lets you distinguish improvement from a task the agent could already do well. You can omit this variant when you only need to compare versions against each other.
The results below come from example runs. Scores are percentages of the rubric's maximum; differences between scores are percentage points. **SD** means standard deviation, a measure of how much scores vary. A larger SD calls for a closer look at individual results before choosing a variant. See [Read an evaluation's results](/improving-your-skills/reading-evaluation-results) for the commands and guidance.
## 1. Compare models
Keep the skill, agent, and judge fixed, and change only the model. This helps you choose a model based on its quality, cost, and speed on your tasks.
In this example, four models used the same skill to work with an admin artifact API. The skill contained about 500 lines of procedure. Each scenario ran three times per model.
```json
[
{ "label": "frontier", "model": "" },
{ "label": "mid-tier", "model": "" },
{ "label": "small-fast", "model": "" },
{ "label": "cheaper-hosted", "model": "" }
]
```
| Model | Score | SD | Cost / solve | Duration | Turns | Input tokens |
| ---------------------- | ----- | ---- | ------------ | -------- | ----- | ------------ |
| A cheaper hosted model | 85.0 | 15.8 | $1.572 | 313.1s | 61.3 | 985,422 |
| A frontier model | 84.7 | 20.0 | $0.940 | 149.6s | 17.4 | 701,643 |
| A mid-tier model | 73.0 | 34.6 | $0.683 | 95.9s | 14.8 | 869,633 |
| A small fast model | 72.9 | 21.8 | $0.107 | 42.7s | 10.3 | 385,330 |
The small fast model averaged 72.9, compared with the frontier model's 84.7, at about 11% of the cost and under a third of the time. That may be a useful tradeoff for tasks where its quality is sufficient.
The model labeled “cheaper hosted” had a lower list price but cost 67% more per solve than the frontier model. It also took about twice as long and used 61.3 turns on average, compared with 17.4. Use the measured cost of completing a task when comparing prices.
The score differences need more care. Means ranged from 72.9 to 85.0, while standard deviations ranged from 15.8 to 34.6. The mid-tier model's individual scores covered the full range from 0 to 100. Inspect the per-scenario results and failed attempts before treating the average scores as a reliable model ranking.
## 2. Compare agents
Run the same skill with different coding agents to compare how they complete the work. Keep the model fixed where possible. If two agents do not support the same model, the comparison measures the agent and model together.
This example used a prose editing skill to change files in place. Two variants used Agent A with different models; the other two used separate agents.
```json
[
{ "label": "agent-a-larger-model", "agent": "", "model": "" },
{ "label": "agent-a-smaller-model", "agent": "", "model": "" },
{ "label": "agent-b", "agent": "", "model": "" },
{ "label": "agent-c", "agent": "", "model": "" }
]
```
| Test variant | Score | SD | Duration | Turns | Input tokens |
| ---------------------- | ----- | --- | -------- | ----- | ------------ |
| Agent A, larger model | 99.0 | 1.1 | 44.6s | 17.7 | 133,118 |
| Agent A, smaller model | 95.3 | 2.4 | 31.5s | 19.5 | 137,065 |
| Agent B | 92.3 | 3.6 | 35.5s | 5.0 | 207,486 |
| Agent C | 88.7 | 1.0 | 12.7s | 3.5 | 57,456 |
Agent A with the larger model had the highest mean score, 99.0, and a low SD of 1.1. Agent C was the fastest at 12.7 seconds and used the fewest input tokens, but had the lowest mean score at 88.7. The choice depends on the quality your editing task needs and how long you can wait for it.
## 3. Compare skill rewrites
Mutation testing compares edited versions of a skill on the same scenarios. It helps you check whether a proposed rewrite improves the agent's work.
Here, a skill for filing and updating tickets gave incorrect CLI guidance. For example, it taught `--labels`, which replaces the label set, for a task that needed `--add-labels`, which preserves existing labels. Three other flags also needed correction. Mechanics that were missing or incorrect accounted for 56 of the target scenario's 100 rubric points.
The evaluation compared nine skill versions and a no-skill baseline across three scenarios, with three repeats. Each rewrite supplied its own `context` directory. This excerpt shows five of the ten variants; the others use the same structure.
```json
[
{ "label": "no-skill", "fixtures": { "context": null } },
{ "label": "v0-shipped" },
{ "label": "v1-outcome-recipe", "fixtures": { "context": { "localPath": "./variants/v1-outcome-recipe" } } },
{ "label": "v2-unteach-labels", "fixtures": { "context": { "localPath": "./variants/v2-unteach-labels" } } },
{ "label": "v8-gutted", "fixtures": { "context": { "localPath": "./variants/v8-gutted" } } }
]
```
The target scenario produced these results:
| Test variant | Score | SD |
| ------------------------- | ----- | ---- |
| v7-combined | 97.2 | 2.5 |
| v4-label-semantics-only | 91.6 | 12.1 |
| v5-comment-mechanics-only | 89.1 | 13.5 |
| v1-outcome-recipe | 87.0 | 32.7 |
| v0-shipped | 86.4 | 21.2 |
| v3-route-to-cli | 85.2 | 20.4 |
| v2-unteach-labels | 83.0 | 32.0 |
| v6-correct-pagination | 64.7 | 40.4 |
| no-skill | 39.4 | 24.1 |
| v8-gutted | 39.3 | 29.6 |
The shipped skill scored 47 points above the no-skill baseline. The highest-scoring rewrite, `v7-combined`, added another 10.8 points and had the lowest SD, 2.5. It is a candidate to test further across the full scenario set before shipping.
Several smaller edits helped explain what to investigate:
* `v4-label-semantics-only` corrected label handling, including adding labels and removing a stale label. It scored 91.6 on a rubric with 29 points for label management.
* `v5-comment-mechanics-only` added `--body-file` and the idempotency-key format. It scored 89.1, with 19 rubric points covering comment mechanics.
* `v1-outcome-recipe` combined those changes with a discovery section and scored 87.0. Combining the same advice in a different form did not produce the same mean score as `v7-combined`.
* `v2-unteach-labels` removed incorrect guidance without adding the correct flags and scored 83.0. `v3-route-to-cli` added a scoping paragraph without flag details and scored 85.2, close to the shipped version.
Three repeats do not support ranking these rewrites against each other. Most of the standard deviations in this table are large. A variant's range often overlaps the rows above and below it. An overlapping range does not test whether two variants really differ. The score gap between v7-combined and the no-skill floor is 57.8 points, but this run does not tell you the order of the rewrites in between. Run more repeats before treating any single pair in the middle of the table as different.
The run also exposed a rubric problem. `v6-correct-pagination` documented the CLI's actual pagination behavior, but an eight-point rubric item required an `--offset` flag that the CLI did not have. Fix that item before using the results to judge pagination guidance. Its SD of 40.4 also makes the mean score a poor basis for a decision on its own.
The `v8-gutted` variant removed the skill's substantive guidance. It scored 39.3, almost the same as the no-skill baseline's 39.4. A deliberately reduced version like this helps check whether a scenario detects the loss of useful instructions. Keep the other scenarios in the evaluation too, so an improvement on the target task does not hide a regression elsewhere.
## 4. Test whether a skill activates
Change a skill's frontmatter description while keeping its body identical. This tests whether the description helps the agent recognize when to use the skill.
This example compared five descriptions: the shipped text, internal jargon, wording a user might type, the skill name alone, and a deliberately broad description. It used three scenarios with three repeats each. One task clearly needed the skill, one was ambiguous, and one used similar vocabulary but belonged to another skill. That last scenario checks for unwanted activation.
```json
[
{ "label": "d0-shipped" },
{ "label": "d1-jargon", "fixtures": { "context": { "localPath": "./variants/d1-jargon" } } },
{ "label": "d2-user-words", "fixtures": { "context": { "localPath": "./variants/d2-user-words" } } },
{ "label": "d3-name-only", "fixtures": { "context": { "localPath": "./variants/d3-name-only" } } },
{ "label": "d4-overbroad", "fixtures": { "context": { "localPath": "./variants/d4-overbroad" } } }
]
```
Run this comparison with `--skip-forced-context-activation`:
```bash
$ tessl eval run ./my-skill --variant-json ./descriptions.json --skip-forced-context-activation
```
Without that flag, the agent is told to use the context, so you cannot measure whether it would choose the skill itself. Do not set `agentMustRead` on these variants for the same reason.
Each variant had nine observations: three scenarios multiplied by three repeats.
| Test variant | Activated | Score |
| ------------- | --------- | ----- |
| d2-user-words | 6/9 | 96.0 |
| d4-overbroad | 5/9 | 98.3 |
| d1-jargon | 2/9 | 95.9 |
| d0-shipped | 0/9 | 86.9 |
| d3-name-only | 0/9 | 85.2 |
The shipped and name-only descriptions recorded no activations. The description written in user language recorded six, making it a useful candidate for further testing.
Check which scenarios activated before choosing a description. More activations are only helpful when they occur on appropriate tasks. The overbroad description scored highest despite activating less often than the user-language version; these nine observations per variant do not explain why, or establish that either description is best.
### How activation is measured
For the `claude` agent, Tessl reads the session transcript and records the skill name when the agent calls the `Skill` tool. This measures explicit invocation. The agent may read or use the content another way without producing that event, so a zero count does not prove the content had no effect.
Other agents do not report activation yet. Their activation is recorded as not measured, which does not mean the skill failed to activate.
`tessl eval view` lists activated skill names per scenario, combining names across all variants and repeats. It does not show activation counts. The table above was calculated from the underlying per-solution records.
You can add `--skip-scoring` to check activation without rubric scoring.
## 5. Compare a skill with access to the codebase
Test whether an agent needs the skill, the source code, or both. Use four variants so you can measure each combination.
This example paired a CLI skill with a portion of the CLI's source. Some guidance was available in the code. Other guidance covered a server-side route and a required preliminary check that the source did not describe. Two scenarios tested those different needs.
The `codebase-only` variant removes the plugin and adds the source as a separate fixture:
```json
[
{ "label": "neither", "fixtures": { "context": null } },
{ "label": "codebase-only", "fixtures": { "context": null, "codebase": { "localPath": "./cli-source" } } },
{ "label": "skill-only" },
{ "label": "both", "fixtures": { "codebase": { "localPath": "./cli-source" } } }
]
```
| Test variant | Score | Cost / solve |
| ---------------- | ----- | ------------ |
| skill + codebase | 100.0 | $0.654 |
| skill only | 98.0 | $0.558 |
| neither | 92.0 | $1.784 |
| codebase only | 87.8 | $2.155 |
The skill-only variant scored 98.0 and cost $0.558 per solve. Adding the source increased the score to 100.0 and the cost to $0.654. Source alone scored 87.8 and cost $2.155, nearly four times as much as the skill alone.
For these tasks, the skill-only setup offered a lower-cost option with a score close to the full setup. Check whether the two-point difference represents an important missed requirement before removing the source. These results apply to the tested tasks; they do not establish that the codebase is unnecessary for every task the skill supports.
## 6. Remove skills from a plugin
**Ablation** means removing one part at a time to measure how the result changes. For a plugin with several skills, it can help identify which skills contribute to the tasks you care about.
This example used a dbt review plugin with five skills: incremental correctness, SQL performance, dimensional modeling, test coverage, and SQL style. The scenario contained five planted defects, one for each skill, and the rubric penalized invented findings.
Seven variants ran the scenario three times each: the full plugin, five versions with one skill removed, and a no-plugin baseline. Each reduced version needs its own prepared plugin directory, supplied through the `context` fixture. Setting a fixture to `null` removes the entire fixture, so it cannot remove just one skill from a plugin.
| Test variant | Mean | SD |
| ----------------------- | ---- | --- |
| full plugin | 80.0 | 3.6 |
| `minus-modelling` | 77.3 | 6.5 |
| `minus-sql-performance` | 77.3 | 6.1 |
| `minus-testing` | 73.0 | 1.7 |
| `minus-incremental` | 72.0 | 5.2 |
| `minus-style` | 64.7 | 2.9 |
| no plugin | 39.3 | 4.2 |
The full plugin had the highest mean score, 80.0, compared with 39.3 without it. Removing the style skill produced the largest drop, 15.3 points. That makes style guidance worth investigating before any attempt to reduce the plugin.
The smaller differences, such as the 2.7-point drop after removing modeling or SQL performance, need more evidence before they justify a change. Skills can also interact, so the drops should not be added together as separate contributions to the full plugin's score. Measure cost and duration as well if the goal is to make reviews cheaper or faster.
## 7. Check for regressions after an edit
Compare a skill before and after a change to check whether the edit affects behavior.
This example used two commits that differed by a version bump and one restored sentence. The sentence explained that a CLI update command changes only three fields and cannot change instruction text.
The run compared the two versions and a no-skill baseline across two scenarios, with three repeats:
```json
[
{ "label": "no-skill", "fixtures": { "context": null } },
{ "label": "pre-edit", "fixtures": { "context": { "localPath": "./plugins/pre-edit" } } },
{ "label": "post-edit" }
]
```
One scenario assigned 45 of its 100 points to requirements affected by the restored sentence. The other tested guidance present word for word in both versions. This control helps check whether a difference is specific to the edited guidance.
The post-edit version scored 100.0, the pre-edit version 95.7, and the no-skill baseline 42.5. The observed gain from restoring the sentence was 4.3 points.
Inspect the relevant rubric items and repeat the comparison before attributing the whole difference to that sentence. Keep a regression scenario when it tests behavior you need to preserve. A tie in one run does not show that the guidance or the test is unnecessary.
## View the results
Use `view` to inspect a run and `compare` to compare separate runs:
```bash
# One run, with a summary for each test variant
$ tessl eval view
# Detailed statistics in the per-scenario tables
$ tessl eval view --full
# Compare two to ten separate runs
$ tessl eval compare --full
```
Alongside scores, check cost, duration, tokens, and turns where they are available. [Read an evaluation's results](/improving-your-skills/reading-evaluation-results) explains these fields, missing data, and the differences between the two commands.
## Plan the run size
Each combination of a variant, scenario, and repeat creates one solution:
```
solutions = test variants x scenarios x repeats
```
The rewrite comparison above uses 90 attempts, the activation comparison 45, and the ablation comparison 21. Before the run starts, the CLI prints its estimated credit cost and, where available, your remaining daily quota. See [pricing](https://tessl.io/pricing/) for current rates.
A run supports:
* At most 2,000 attempts.
* Unique variant labels matching `^[a-z0-9][a-z0-9_-]{0,63}$`. Dots are not allowed, so a model name such as `kimi-k2.6` needs a different label.
* 1 to 10 repeats, set with `--runs` or `-n`.
* Up to 50 `localPath` fixture references, resolving to at most 20 distinct local sources.
An organization can create 1,000 attempts per day, resetting at 00:00 UTC. A run with more than 50 scenarios requires `--yes` to confirm. Calculate the solution count before submitting so you have room for repeats and follow-up runs.
## Next steps
* [Read an evaluation's results](/improving-your-skills/reading-evaluation-results) explains the output and how to interpret it.
* [Prove a skill works using evaluation](/improving-your-skills/evaluate-skill-quality-using-scenarios) covers scenario generation and running an evaluation.
* [Troubleshooting reviews and evaluations](/improving-your-skills/troubleshooting-reviews-and-evals) covers failed runs and unexpected scores.
# Read evaluation results
View evaluation results, compare scores and costs, and understand variation and missing data.
An evaluation shows how well an agent completed your tasks and, where available, how much time and money it spent. Start with the summary, then check individual scenarios for failures or differences that the average may hide.
If you have not run an evaluation yet, see [Prove a skill works using evaluation](/improving-your-skills/evaluate-skill-quality-using-scenarios).
## View a run
Open your most recent run or choose one by ID:
```bash
$ tessl eval view --last
$ tessl eval view
```
The output includes a comparison of the test variants, followed by a table of results for each variant broken down by scenario.
This example is real output from a run that compared four models on the same plugin, with three repeats each:
```
Eval Results: tile-analysis — model comparison
Repo: tesslio/monorepo
Agent: claude
Model: claude-sonnet-4-6
Variants: Opus 5, Sonnet 4 6, Haiku 4 5, Deepseek V4 Flash
Status: ✔ Completed
Test variant comparison
Test variant Score Cost / solve Duration Tokens / solve Turns / solve
opus-5 100% ± 0.0pp $0.9835 ± $0.1550 183.3s ± 17.5s 730,012 26.67 ± 1.63
sonnet-4-6 98% ± 2.8pp $0.3698 ± $0.0935 126.6s ± 27.0s 533,055 24 ± 3.02
haiku-4-5 92% ± 7.9pp $0.1258 ± $0.0635 50.3s ± 42.2s 451,771 15.22 ± 13.45
deepseek-v4-flash 98% ± 2.7pp $1.3125 ± $0.3342 245.8s ± 84.0s 801,544 43 ± 9.94
```
Score, cost, duration, and turns show a **mean** (average) followed by a **standard deviation** (SD), which describes how much the measurements vary. For example, `92% ± 7.9pp` means an average score of 92% and an SD of 7.9 percentage points. It is not a guaranteed range for future scores.
The score mean is truncated to a whole number in this view: 84.7 appears as `84%`. Tokens appear as a rounded mean without an SD. When fewer repeats have results than expected, a cell includes a count such as `(n=2 of 3)`.
## View a run in the web app
`tessl eval view` prints a link to the run. The page has these sections, from top to bottom:
* **Result**: one sentence that states the outcome, for example which variant scored highest.
* **Metrics**: score, cost per solve, time per solve, and tokens per solve for each variant. Each value is a mean across repeats, drawn with its spread.
* **Did the agent actually use the skill?**: the share of repeats in which the agent loaded the skill, for each variant that has it. See [How activation is measured](/improving-your-skills/comparing-with-test-variants#how-activation-is-measured).
* **By scenario**: one row for each scenario. Select a row to open its criteria and its repeats. Each repeat shows its score, cost, time, tokens, and whether the skill activated, and members of the workspace can download the solution.
* **Setup**: what each variant did differently and what stayed the same, the total cost of the run, and how many attempts were reused from earlier runs and not billed again.
### When a difference is within noise
The page treats two means as different only when the gap between them is larger than their pooled standard deviation, the square root of the sum of the two variances. A grey band on each metric shows that threshold. In a default run, the band sits around the result without the skill, and a change inside it reads **Unchanged**. In a run with your own variants, the band sits around the best variant, and variants that trail it by more than the band are faded.
A difference inside the band is not proof that the variants are equivalent. Add repeats to narrow the spread.
### Activation states
* A percentage, such as `62%`, is the share of measured repeats in which the agent loaded the skill.
* **Not measured** means the agent does not report activation. It does not count as a zero.
* **Not loaded** on a repeat means the skill was not installed for that variant, or it was installed and the agent did not load it.
## Understand what is being counted
A run contains test variants, scenarios, and repeats:
```
Evaluation run
└── Test variant A configuration, such as a model or skill version
└── Scenario A task and its scoring rubric
└── Repeat Another attempt at the same task
```
Every variant attempts every scenario. The rubric defines what a successful response must do, and the judge scores the response against it. `-n`, or `--runs`, sets how many times each variant attempts each scenario.
Each attempt is a **solution**, whether or not scoring completes. The number of attempts is:
```
solutions = test variants x scenarios x repeats
```
For example, four models on three scenarios with three repeats create 36 attempts. This is also the number counted toward the daily quota.
A default run has two test variants: without the plugin and with it. A run declared with `--variant-json` has the variants you list. Each can change the model, agent, plugin, or other fixtures.
## What each measurement means
| Measurement | What it records |
| ---------------- | ----------------------------------------------------------------- |
| Score | Points awarded as a percentage of the rubric's maximum |
| Cost | Cost of solving the task, in dollars, where recorded |
| Duration | Wall-clock duration and the agent's own time, recorded separately |
| Tokens | Input, output, cache read, and cache creation token counts |
| Turns | Number of agent turns used to solve the task |
| Skill activation | Names of skills the agent invoked, where supported |
The judge's time, cost, and tokens are recorded separately. The cost in the variant comparison table covers solving the task; it does not include scoring it.
Numeric measurements store a count, missing count, minimum, quartiles, median, mean, maximum, and standard deviation. Activation is a separate record of skill names. See [How activation is measured](/improving-your-skills/comparing-with-test-variants#how-activation-is-measured) for its limitations.
## Inspect variation within a result
Use `--full` to see more than the average:
```bash
$ tessl eval view --last --full
```
This expands the per-scenario cells in each variant's table. The top-level comparison of variants stays compact.
An expanded score cell from the run above, for one scenario solved three times by `haiku-4-5`, looks like this:
```
min 81
q1 81.5
med 82
mean 87.7
q3 91
max 100
sd 8.73
```
`min` and `max` are the lowest and highest values. `med` is the median, or middle value. `q1` and `q3` mark the lower and upper quartiles, with the middle half of the results between them. `sd` is the standard deviation.
Use these statistics to decide which individual attempts to inspect. A low minimum may point to a failed attempt, while a wide range may reflect differences between tasks or between repeats of the same task. The summary alone does not explain the cause.
### Avoid ranking variants by the average alone
The model comparison in [What you can compare with an evaluation](/improving-your-skills/comparing-with-test-variants) had these unrounded scores:
| Test variant | Mean score | SD |
| ---------------------- | ---------- | ---- |
| A cheaper hosted model | 85.0 | 15.8 |
| A frontier model | 84.7 | 20.0 |
| A mid-tier model | 73.0 | 34.6 |
| A small fast model | 72.9 | 21.8 |
The means differ by about 12 points from highest to lowest, while the standard deviations range from about 16 to 35. With that much variation, the averages alone are a weak basis for choosing a model.
For example, the mid-tier model's individual scores ranged from 0 to 100. Its average of 73.0 hides that variation. Look at the per-scenario results to see which tasks failed and whether the failures recur across repeats.
Start with at least three repeats when you intend to share a conclusion. Add more when the result is variable or the decision needs greater confidence. Comparing standard deviations is useful for spotting uncertainty, but it does not replace a statistical test of the difference.
## Check cost and time alongside quality
That run also shows why the highest score may not be the best choice for your workload:
| Test variant | Mean score | Cost / solve | Duration | Turns |
| ---------------------- | ---------- | ------------ | -------- | ----- |
| A cheaper hosted model | 85.0 | $1.572 | 313s | 61.3 |
| A frontier model | 84.7 | $0.940 | 150s | 17.4 |
| A small fast model | 72.9 | $0.107 | 43s | 10.3 |
The small fast model scored lower, but used about 11% of the frontier model's cost and less than a third of its time. It may be suitable for tasks where that quality is enough.
The cheaper hosted model had a lower list price than the frontier model, yet cost 67% more per completed task and took about twice as long. Its higher turn count helps explain why list price alone is not enough to estimate the cost of a task.
## Measure the improvement over a baseline
To measure how much a skill helps, include a variant without it:
```json
{ "label": "no-skill", "fixtures": { "context": null } }
```
Setting the `context` fixture to `null` removes the plugin under test. Other fixtures, such as a codebase, remain available. This gives you a baseline for the same tasks without the plugin you are testing.
In one evaluation, five skill rewrites scored between 95 and 98, but the no-skill variant already scored 90.2. The measured improvements were therefore between 4.8 and 7.8 points. Those scenarios left little room to distinguish successful rewrites because the agent could already do most of the work without the skill.
On a different skill, the shipped version scored 86.4 against a baseline of 39.4. The best rewrite scored 97.2. The rewrite improved on the shipped version by 10.8 points; the baseline showed that both versions also helped substantially compared with having no skill.
A baseline provides context for a skill's contribution. You do not need it merely to calculate the difference between two versions.
## Compare separate runs
Use `compare` to put two to ten runs side by side:
```bash
$ tessl eval compare
$ tessl eval compare --full
```
The output has one column per run and shows the configuration dimensions that differ between them. Check those differences before attributing a score change to your edit.
The compact statistical cells in `compare` and `view` both show the **mean** with the standard deviation.
With `compare --full`, every statistical cell in the comparison table expands to show the full distribution. With `view --full`, only the per-scenario tables expand.
### Confirm results with another run
The seven examples in [What you can compare with an evaluation](/improving-your-skills/comparing-with-test-variants) were each run twice with the same configuration. Two conclusions changed on the second run: the order of the ablation variants reversed, and the improvement from a rewrite changed by an order of magnitude.
Repeats help reveal variation within a run. A separate run checks whether your conclusion holds again. If it does not, investigate the individual attempts and the rubric before making a change based on the first result.
## Handle missing data
A missing measurement is different from a measured zero. Missing cells display a dash, and partially missing results include a count such as `n=1 missing`. Check these counts before comparing averages.
| Missing field | What to check |
| ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Activation | Only the `claude` agent reports activation. For other agents it is recorded as not measured. This does not mean the skill failed to activate. |
| Cost | Some agents do not use the billing path that records per-solution cost. An empty cell does not mean the task was free. |
| Cost or judge statistics on a shared run | These fields are visible only to members of the workspace that owns the run, even when the run is public. Check workspace access before assuming data was not recorded. |
| Score | A solution may complete without receiving a score. Treat it as missing data, not a zero or a no-skill baseline. |
| Per-turn or tool-usage statistics | These require an agent log. Attempts without one are reported as unavailable. |
## Run limits
| Limit | Value |
| ------------------------------------------------- | ----------------------------- |
| Attempts per run (variants × scenarios × repeats) | 2,000 |
| Repeats (`-n`, `--runs`) | 1 to 10 |
| `localPath` fixture references per run | 50 |
| Distinct local sources | 20 |
| Scenarios per run | More than 50 requires `--yes` |
| Attempts per organization per day | 1,000, resetting at 00:00 UTC |
The daily cap counts attempts, not runs. Four variants on three scenarios with three repeats use 36 of the 1,000 available attempts.
## Next steps
* [What you can compare with an evaluation](/improving-your-skills/comparing-with-test-variants) gives examples of model, agent, and skill comparisons.
* [Prove a skill works using evaluation](/improving-your-skills/evaluate-skill-quality-using-scenarios) covers generating scenarios and running evaluations.
* [Troubleshooting reviews and evaluations](/improving-your-skills/troubleshooting-reviews-and-evals) helps with failed runs and unexpected scores.
* [Check a skill's quality using review](/improving-your-skills/reviewing-skills) explains how to review a skill before evaluating it.
# Troubleshooting reviews and evaluations
Most problems with reviews and evaluations come down to a few causes. Work through these when something does not behave as expected.
{% hint style="info" %}
**Takeaway** Most problems with reviews and evaluations come down to a few causes: scenarios in the wrong place, missing permissions, a skill that never activated, or normal model variance read as a real result. Work through the questions below when something does not behave as expected.
{% endhint %}
## Why does my evaluation say "no scenarios found"?
`tessl scenario download` writes scenarios into the plugin's `evals/` directory when run from the plugin root or any subdirectory of it. The plugin root is the directory that contains `.tessl-plugin/plugin.json`. If you ran it from outside the plugin tree, scenarios landed somewhere else and `tessl eval run ` cannot find them.
Re-download from inside the plugin (any subdirectory works):
```bash
cd # or any subdirectory under it
tessl scenario download --last
```
Or pass the location explicitly:
```bash
tessl scenario download --last --output /evals
```
## Why do I only see baseline results, with no "with context" column?
The evaluation completed, but every scenario shows a baseline score and nothing for the skill. This means the run could not find the skill to inject, usually because the plugin layout is wrong.
Check that `evals/`, `.tessl-plugin/`, and the skill directory all sit under the same plugin root, and that `skills[]` in `plugin.json` points at the skill directory correctly, relative to the plugin root.
## Why does my run fail on permissions?
Evaluations require at least **publisher** access to the workspace. Member access is not enough to run `tessl eval run` or `tessl scenario generate`. A review needs only member access, so a skill you can review may still fail to evaluate.
Confirm who you are logged in as with `tessl whoami`, and check your access to the workspace the plugin is attributed to in `.tessl-plugin/plugin.json`.
## Why do scores look worse with the skill than without?
A small negative difference is usually normal model variance, not evidence the skill is harmful. An evaluation runs a real agent, so results vary from run to run. Run each scenario several times with `--runs` and read the overall pattern rather than a single result. A large or consistent negative difference is a real signal that the skill is confusing the agent, and the content needs work.
## Why does the skill make no difference at all?
If the "with context" score sits at zero improvement across repeated runs, the skill most likely never activated, so the agent never used it. That is a different problem from variance. Check activation: run `tessl review run` and look at the description score, and make sure the skill's `description` states clear trigger conditions for when it should be used. See [Check a skill's quality using review](/improving-your-skills/reviewing-skills).
## A scenario keeps failing to complete
It is normal for an agent not to solve every scenario on every attempt. Retry the run, or adjust the scenario if it is consistently failing for the wrong reason.
```bash
tessl eval retry abc123
tessl eval retry --last
```
## Still using `tessl skill review`?
`tessl skill review` has been removed and replaced by `tessl review run`, which requires authentication. If a script or workflow still calls the old command, see [Migrate from skill review](/improving-your-skills/migrate-from-skill-review) for what changed and how to move across.
## Getting help
If none of the above surfaces the cause, share the output of `tessl doctor --json` when you reach out, since it reports your authentication status. See [Giving feedback](/support/giving-feedback).
# Overview
Gate skill quality automatically and define your organisation's standard for what a good skill looks like.
{% hint style="info" %}
**Takeaway** Keep poor-quality skills out of your repository. Set the bar for what "good" means, then gate it in CI so skills that fall short do not get merged.
{% endhint %}
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 section is about holding a quality line automatically, so you do not depend on everyone remembering to check.
There are two parts to it:
* **Enforce code invariants.** Use verifiers for binary, observable facts about committed files that a linter cannot express. See [Verifiers overview](/codifying-and-enforcing-your-skill-standards/verifiers-overview) and [Verify agent changes in CI](/codifying-and-enforcing-your-skill-standards/verify-agent-changes-in-ci).
* **Gate on a review score.** Run a review in CI and fail the build when a skill scores below your bar, so substandard skills never merge. See [Gate skill quality in CI](/codifying-and-enforcing-your-skill-standards/gate-skill-quality-in-ci).
* **Define your own bar.** The default rubric scores against general best practices. Fork it to encode what your organisation cares about, and apply it to every review. See [Define your own quality standards](/codifying-and-enforcing-your-skill-standards/define-your-own-quality-standards).
This section covers protecting a repository from low-quality skills. It does not cover managing your wider skill estate, surveying what is installed across your organisation, or org-level policy; those are separate capabilities.
## Next
* [Verifiers overview](/codifying-and-enforcing-your-skill-standards/verifiers-overview) - decide whether a verifier is the right way to enforce a standard.
* [Verify agent changes in CI](/codifying-and-enforcing-your-skill-standards/verify-agent-changes-in-ci) - write, calibrate, and run a verifier on pull requests.
* [Gate skill quality in CI](/codifying-and-enforcing-your-skill-standards/gate-skill-quality-in-ci) - run reviews on pull requests and block merges below your threshold.
* [Define your own quality standards](/codifying-and-enforcing-your-skill-standards/define-your-own-quality-standards) - build a custom rubric and apply it to every review.
# Verifiers overview
Use verifiers to check committed files against repository-specific invariants that a linter cannot express.
{% hint style="info" %}
**Takeaway** Use a verifier for a binary, observable fact about committed files when a deterministic check cannot express the standard.
{% endhint %}
{% hint style="info" %}
You can select and fix a specific judge with `tessl change verify --model`; use `openai/gpt-6-luna` to prioritize reasoning or **Jev** (`--model jev`) for cost and speed. Jev returns one pass/fail verdict and a confidence per rule with no written reasoning, so it is cheaper and faster to run than a reasoning judge. As with any judge, a run sends the files it checks to your configured LLM gateway. Jev's availability depends on that gateway's configuration and region, and it is not offered for bring-your-own-model organizations.
{% endhint %}
A verifier is an LLM-as-judge check that compares committed files with an invariant stored as JSON. For example, a verifier can check that every user-facing error includes a next step or that every FastAPI route uses your typed response helpers.
Verifiers belong in your repository. A verifier file describes what to judge, while the `verify` block in `tessl.json` selects the files it covers and sets the severity of its findings. This separation lets teams reuse the same verifier with different scopes and enforcement levels.
{% hint style="success" %}
Want a coding agent to set up and tune verifiers with you? Install the `tessl/tessl-verify` plugin with `tessl install tessl/tessl-verify`. Its skill walks an agent through authoring verifier JSON, scoping the `verify` block, and adding a CI gate.
{% endhint %}
## When to use a verifier
Use a verifier when all of these are true:
* The standard has a pass or fail answer.
* The evidence is visible in committed files or a diff.
* A reviewer can apply the standard consistently from the supplied context.
* A deterministic tool cannot check it reliably.
Do not use a verifier for subjective preferences such as whether code is elegant. Narrow the invariant until its checklist has observable evidence.
## Choose the right mechanism
| Mechanism | Use it for | Example |
| -------------- | --------------------------------------------------------- | ------------------------------------------------ |
| Rule | Guidance an agent must follow on every relevant task | Use the shared response helper for API routes |
| Skill | A workflow an agent should activate for a specific task | Create and register a new API route |
| Linter or test | A fact code can check deterministically | Every route file imports an approved symbol |
| Verifier | A binary invariant that needs judgment over code or prose | Every user-facing error explains the next action |
Prefer a linter or test when one can enforce the invariant. A rule or skill guides an agent before and during a change; a verifier checks the result after the change. You can pair them: a rule teaches the expected pattern, and a verifier catches changes that do not follow it.
Verifiers are separate from Tessl Code Review. Code Review looks for general problems across a pull request. Verifiers enforce the specific invariants your repository names and configures.
## How verification works
Each verifier JSON file contains the instruction, applicability criteria, evaluation scope, and a checklist of binary rules. The repository's `tessl.json` groups verifier files, targets source files with include and exclude globs, and assigns an `info`, `warn`, or `error` level.
`tessl change verify` resolves the configured scope and judges applicable targets. In CI, `warn` findings remain advisory and `error` findings exit non-zero, so they can block a pull request.
By default, `tessl change verify` is change-aware: it checks the files a change touches against every applicable verifier, and re-checks a changed verifier or `tessl.json` rule against its full configured scope. Run `tessl change verify --all` to audit every file in the current project's configured scopes (include and exclude filters still apply); add `--recursive` to include linked child manifests in a monorepo.
For the complete configuration fields, see the [`verify` block reference](/reference/configuration#verify-block).
## Next
* [Verify agent changes in CI](/codifying-and-enforcing-your-skill-standards/verify-agent-changes-in-ci) - create a verifier, inspect its scope, and add a pull request gate.
* [Improving agent code quality](/tutorials/improving-agent-code-quality) - find recurring review feedback worth turning into a rule, skill, test, or verifier.
# Verify agent changes in CI
Write and calibrate a verifier, then run it as an advisory or blocking check on pull requests.
{% hint style="info" %}
**Takeaway** Start a verifier as a warning, inspect the files it covers, and promote it to an error only after it produces reliable findings on real changes.
{% endhint %}
This guide creates a verifier for a repository invariant, connects it to `tessl.json`, and runs it against pull request changes. If you are deciding whether a verifier fits your standard, start with [Verifiers overview](/codifying-and-enforcing-your-skill-standards/verifiers-overview).
## 1. Write the verifier
Create `verifiers/actionable-errors.json`:
```json
{
"name": "User-facing errors include a next step",
"instruction": "When code returns a user-facing error, it should tell the user what to do next.",
"relevant_when": "TypeScript code that constructs a UserFacingError or prints an error for a CLI command.",
"context": "CLI errors should be actionable for users running commands in a terminal.",
"scope": "file",
"scope_reason": "Each command file contains the error and its recovery guidance.",
"checklist": [
{
"name": "actionable-error",
"rule": "Each user-facing error includes the command to run next, the flag to change, or the file to inspect."
}
]
}
```
Keep `relevant_when` specific. It should name the observable trait that makes a target applicable, rather than a broad category such as "TypeScript file."
Validate the file before running it:
```bash
$ tessl change verify lint verifiers/actionable-errors.json
```
## 2. Configure its scope as a warning
Add a group to the `verify` block in `tessl.json`:
```json
{
"name": "engteam/my-project",
"verify": {
"groups": {
"error-ux": {
"path": "verifiers/actionable-errors.json",
"level": "warn",
"include": ["src/**/*.ts"],
"exclude": ["**/*.test.ts"]
}
}
}
}
```
Severity belongs in `tessl.json`, not in the verifier file. Starting at `warn` reports findings without blocking the pull request.
## 3. Inspect the matched files
Preview a full-repository run before spending judge calls:
```bash
$ tessl change verify --dry-run --all --show-files
```
Check that the output contains the files you intend to cover and excludes unrelated files. Adjust the group's `include` and `exclude` globs or the verifier's `relevant_when` if the scope is too broad or narrow.
Then judge a small sample:
```bash
$ tessl change verify --all --sample 5
```
This sends the selected source content to Tessl's LLM judge. Limit the verifier's scope to content your organization is authorized to send, and exclude credentials, personal data, and other sensitive material.
Review each result against the invariant. Refine the verifier until the same evidence produces consistent pass or fail decisions.
## 4. Run it on pull requests
CI needs a Tessl API key in the `TESSL_TOKEN` environment variable. For key creation and storage guidance, see [Authenticating in CI](/codifying-and-enforcing-your-skill-standards/gate-skill-quality-in-ci#authenticating-in-ci). A pull request can change its workflow, verifier, and manifest configuration, so its branch location does not establish trust. Use a `pull_request` workflow, not `pull_request_target`, and protect the credentialed job with a GitHub environment that requires approval from reviewers who are authorized to approve the configuration and source changes.
The following job and steps assume the workflow runs on `pull_request`, has checked out the repository, and installed Tessl with `tesslio/setup-tessl@v2`. The job skips an external head repository by comparing repository identities, so it still runs for same-repository pull requests when the repository itself is a fork. Create the `tessl-verify` environment in GitHub with required reviewers, store `TESSL_TOKEN` as an environment secret, and do not approve it until the pull request's workflow, verifier, and manifest changes have been reviewed:
```yaml
verify:
runs-on: ubuntu-latest
if: github.event.pull_request.head.repo.full_name == github.repository
environment: tessl-verify
env:
TESSL_TOKEN: ${{ secrets.TESSL_TOKEN }}
steps:
- name: Fetch base branch
env:
BASE_REF: ${{ github.event.pull_request.base.ref }}
run: git fetch --no-tags origin "$BASE_REF:refs/remotes/origin/$BASE_REF"
- name: Inspect verifier scope
env:
BASE_REF: ${{ github.event.pull_request.base.ref }}
run: tessl change verify --base "origin/$BASE_REF" --dry-run --show-files --max-calls 200
- name: Verify changed files
env:
BASE_REF: ${{ github.event.pull_request.base.ref }}
run: tessl change verify --base "origin/$BASE_REF" --github --max-calls 200
```
`--base "origin/$BASE_REF"` compares against the pull request's actual target branch, which the fetch step records as a remote-tracking ref. For source-only changes, the command verifies the pull request's changed files. When the pull request changes a verifier JSON file or the `verify` configuration, the affected verifier runs across its full configured scope. `--github` emits annotations for findings. A `warn` finding is advisory, while an `error` finding makes the command exit non-zero.
`--max-calls 200` is the gate's call budget. The command stops before judging if its planned scope exceeds that limit; narrow the group's scope or choose and document a larger limit before changing the workflow.
If you run the command from a monorepo root with linked child manifests, add `--recursive` to each invocation.
## 5. Promote the verifier to a blocking check
Leave the verifier at `warn` while it runs on real pull requests. Track false positives, missed applicable files, and unclear findings. When the verifier is reliable, change the group level:
```json
{
"verify": {
"groups": {
"error-ux": {
"path": "verifiers/actionable-errors.json",
"level": "error",
"include": ["src/**/*.ts"],
"exclude": ["**/*.test.ts"]
}
}
}
}
```
The existing CI command now blocks pull requests with failing findings. You do not need to change the workflow or add `--fail-on-warn`.
## Next
* Read the [`verify` block reference](/reference/configuration#verify-block) for group filters and per-verifier overrides.
* Add [Tessl Code Review](/tutorials/setting-up-agentic-code-review) when you also want general pull request review beyond named repository invariants.
# Gate skill quality in CI
Run a review on every pull request and fail the build when a skill scores below your threshold.
{% hint style="info" %}
**Takeaway** Run a review on every pull request and fail the build when a skill scores below your threshold. Skills that fall short of the bar never merge.
{% endhint %}
A review tells one person whether a skill is good. Gating in CI applies that check to everyone, automatically, so a substandard skill cannot reach your shared repository in the first place.
## Fail a build below a threshold
Pass `--threshold` to exit non-zero when a review score falls below your bar:
```bash
tessl review run ./my-skill --workspace engteam --threshold 80
```
`--threshold` takes a 0-100 integer. The default is 0, which never fails. Any value above 0 causes the command to exit non-zero - and fail the CI step - when the score falls below it.
Add `--json` when you need machine-readable output, for example in a script that reads the score programmatically:
```bash
tessl review run ./my-skill --workspace engteam --json --threshold 80
```
`--workspace` is required when `--json` is set, because a non-interactive run cannot prompt for one. In practice, always pass `--workspace` in CI regardless.
You can also re-check an existing run against a threshold without starting a new review:
```bash
tessl review view --json --threshold 80
```
## Authenticating in CI
A review runs against your workspace, so CI needs to authenticate without an interactive login. Create an API key for your workspace:
```bash
tessl api-key create --workspace engteam
```
Set the key as a repository secret named `TESSL_TOKEN`. The CLI and the Tessl GitHub Action both read it from that variable.
### Keys expire after 30 days
Every API key expires. Unless you pass `--expiry-date` or `--ttl`, the key you just created is valid for **30 days from creation**, and the CLI prints the exact date when it issues the key.
This matters most in CI, because nothing fails at the moment the key expires. Your pipeline stays green for a month and then starts failing authentication on a run that changed nothing. Put a reminder in your calendar, or pass a longer `--expiry-date` when you create the key:
```bash
tessl api-key create --workspace engteam --name ci --role member --expiry-date 2027-12-31T00:00:00Z
```
You can also set a duration using the local clock just before the creation request, such as `--ttl 4w` for four weeks, `--ttl 2mo` for 60 days, or `--ttl 1y` for 365 days. Use one expiry flag at a time.
### Rotating a CI key
Rotation is always something you run from your own machine, never from inside the pipeline. An API key cannot create another API key, which means a leaked CI credential cannot renew itself. That is deliberate.
Two paths, depending on whether the key has already expired.
**The key has already expired.** Your pipeline is broken, so there is no window to protect. Replace it under the same name:
```bash
tessl api-key delete --workspace engteam ci
tessl api-key create --workspace engteam --name ci --role member
```
**The key is still valid.** Create the replacement under a new name first, confirm a run passes with it, and only then remove the old key. Your pipeline is never without a working credential:
```bash
tessl api-key create --workspace engteam --name ci-2 --role member
# update the secret, confirm a run passes, then:
tessl api-key delete --workspace engteam ci
```
Key names are unique per workspace, which is why the second path needs a different name rather than reusing `ci`.
Both paths involve reading your pipeline to find which secret feeds `TESSL_TOKEN`, and that secret can be named anything. `tessl agent` can do that part for you: ask it to rotate your Tessl CI key and it finds the secret, shows you a plan naming where each fact came from, and waits for a go-ahead before it changes anything.
```bash
tessl agent "rotate my Tessl CI key"
```
Nothing to install. The skill behind this ships with the CLI.
Use `tessl api-key list --workspace engteam --json` when you want key ids, roles, or expiry dates in a script.
### Where the key lives on each CI platform
Whatever your platform, the CLI reads the key from the `TESSL_TOKEN` environment variable. What changes is where the secret behind that variable is stored. The secret itself can be named anything, so check your pipeline definition to see which one it maps to `TESSL_TOKEN`.
| Platform | Where the secret lives | CLI |
| ------------------- | ------------------------------------------------------ | ------------------------------ |
| GitHub Actions | Settings > Secrets and variables > Actions | `gh secret set ` |
| GitLab CI | Settings > CI/CD > Variables | `glab variable set ` |
| CircleCI | Project Settings > Environment Variables | |
| Buildkite | Pipeline Settings > Secrets | `bk secret set ` |
| Azure Pipelines | Pipelines > Library | `az pipelines variable update` |
| Jenkins | Manage Jenkins > Credentials | |
| Bitbucket Pipelines | Repository settings > Pipelines > Repository variables | |
| TeamCity | Build Configuration > Parameters | |
When a key expires, the CLI names your platform and its secret location in the error, so you do not have to come back to this table.
## Run it on pull requests
Tessl publishes a GitHub Action that installs the CLI and runs this gate on pull requests, so you do not have to wire up the CLI by hand. For the complete workflow, see [Review, lint & publish with GitHub Actions](/distribute/review-and-publish-with-github-actions).
## Next
* [Define your own quality standards](/codifying-and-enforcing-your-skill-standards/define-your-own-quality-standards) - gate against your organisation's own rubric, not just the default.
* [Check a skill's quality using review](/improving-your-skills/reviewing-skills) - full reference for `tessl review run`, score interpretation, and applying fixes.
# Define your own quality standards
Fork the default review rubric to encode your organisation's quality bar, then apply it to every review.
{% hint style="info" %}
**Takeaway** The default review rubric scores against general best practices. Fork it to encode what your organisation cares about, then apply it everywhere: local reviews, automated fixes, and your CI gate.
{% endhint %}
The default rubric is a good baseline, but it does not know your conventions. If your team has its own bar for what a skill must do, a custom reviewer plugin lets you define it once and apply it consistently.
## Build a reviewer
The `create-review-plugin` skill from [`tessl/review-plugin-creator`](https://tessl.io/registry/tessl/review-plugin-creator) scaffolds a reviewer plugin for you. Install it, then ask your agent to create a reviewer:
```bash
tessl install tessl/review-plugin-creator
```
A reviewer plugin is a standard Tessl plugin with this layout:
```
/
├── .tessl-plugin/
│ └── plugin.json
└── skills/skill-reviewer/
├── SKILL.md
├── references/
│ ├── config.json
│ └── rubrics/
│ └── .json (one per judge)
```
`config.json` sets the weight each judge contributes to the final score, plus a `validation_weight` for the deterministic validation pass. All weights must sum to 1.0:
```
validation_weight + sum of judge weights = 1.0
```
Set `validation_weight` to `0.0` to exclude validation from scoring. Validation still runs as a gate but does not affect the numeric score.
Each rubric file defines one judge: what it evaluates (`evaluation_target`), a scoring scale, and a set of dimensions. Dimension weights within a single rubric also sum to 1.0. The `create-review-plugin` skill validates the finished plugin by running `tessl review run` against a test skill, so you catch misconfigured weights before you use it.
The [default rubric](https://github.com/tesslio/product-plugins/tree/main/default-skill-review) 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 keeps those dimensions and lets you adjust weights, remove ones that do not apply, or add judges of your own.
## Use a reviewer
Point a review at your reviewer with `--review-plugin`, passing either a local directory or a `workspace/plugin` registry reference:
```bash
tessl review run ./my-skill --workspace engteam --review-plugin
```
The same flag works with `tessl review fix` and in your CI gate:
```bash
tessl review run ./my-skill --workspace engteam --review-plugin --threshold 80
```
Pass `--review-plugin` explicitly on each run, or configure a workspace default, so the flag is not required at all.
## Setting workspace policy
Rather than passing `--review-plugin` on every run, you can set your reviewer plugin as the default for an entire workspace. Once set, any review run that does not name its own reviewer uses your plugin automatically, so contributors do not need to remember the flag. A run that passes an explicit `--review-plugin` (or an upload override) still takes precedence, so the workspace default is the automatic choice rather than a non-bypassable rule.
To configure this, open the workspace settings in the Tessl web app and navigate to the **Reviews** section. Select **Manage**, enter your reviewer plugin reference (for example `myorg/my-reviewer` or a pinned version such as `myorg/my-reviewer@1.2.3`), and save. The reviewer plugin you choose becomes the workspace default, applied to every review run that does not override it.
{% hint style="info" %}
You still need the `customReviewPlugins` entitlement to use this feature. Contact your workspace owner if the Reviews section is not visible in your settings.
{% endhint %}
## Next
* [Gate skill quality in CI](/codifying-and-enforcing-your-skill-standards/gate-skill-quality-in-ci) - enforce your rubric automatically on pull requests.
# Distributing via registry
Distribute, share, and maintain plugins through the Tessl Registry
Once you've created and published a plugin, you'll need to share it with your team, keep it updated, and manage its lifecycle. This guide covers the common tasks for managing published plugins.
## Sharing with your team
Add members to your workspace so they can access your private plugins:
```bash
tessl workspace add-member --username --role member --workspace myworkspace
```
The `member` role gives read-only access to plugins. See [Roles](/administrators/roles) for more information about workspace roles and permissions.
To verify members have been added:
```bash
tessl workspace list-members myworkspace
```
## Installing plugins in projects
Team members can install your plugin in their projects:
```bash
tessl install myworkspace/your-plugin
```
Or search for it:
```bash
tessl search your-plugin
```
Private plugins appear in search results for workspace members just like public plugins.
To install a specific version:
```bash
tessl install myworkspace/your-plugin@1.0.0
```
## Updating documentation
When your library or service changes, update the plugin to keep documentation current.
### For automated plugins
If you used automated generation from a repository:
1. Merge code changes to your repository
2. Navigate to the Tessl interface and regenerate the plugin
3. Review new evaluation results
4. Publish the updated version
### For manual plugins
If you created the plugin manually:
1. Edit your documentation files
2. Increment the version in `.tessl-plugin/plugin.json` (following [semantic versioning](https://semver.org/))
3. Validate with `tessl plugin lint`
4. Publish with `tessl plugin publish`
**Version guidelines:**
* **Patch** (1.0.0 → 1.0.1): Bug fixes, typo corrections
* **Minor** (1.0.0 → 1.1.0): New content, backward-compatible changes
* **Major** (1.0.0 → 2.0.0): Restructuring, breaking changes
Users can update to the latest version:
```bash
tessl install myworkspace/your-plugin
```
## Archiving plugins
To remove a plugin from search results without deleting it:
```bash
tessl plugin archive --plugin myworkspace/your-plugin@1.0.0 --reason "replaced by new library"
```
Archived plugins:
* No longer appear in search results
* Cannot be installed by new users
* Remain accessible to projects that already have them installed
* Can be restored by contacting support
Use archiving when:
* A library is deprecated but still used by some projects
* You're migrating to a new plugin and want to phase out the old one
* The plugin is outdated but may still be needed for reference
## Unpublishing plugins
To completely remove a plugin within ***2 days*** of upload:
```bash
tessl plugin unpublish --plugin myworkspace/your-plugin@1.0.0
```
**Important:** Unpublishing is only available within 2 days of the original publish. After that, use archiving instead.
Unpublished plugins are completely removed and cannot be recovered.
## Monitoring plugin usage
Track how your plugins are being used:
1. Navigate to the [Tessl Registry](https://tessl.io/registry)
2. Log in and select your workspace
3. View your plugins to see usage statistics and install counts
This helps you understand which plugins are most valuable to your team.
## Best practices
* **Update regularly** - Keep documentation in sync with code changes
* **Use semantic versioning** - Help users understand the impact of updates
* **Archive deprecated plugins** - Guide users to replacement plugins
* **Monitor usage** - Focus maintenance effort on widely-used plugins
* **Document breaking changes** - Communicate major version updates to your team
## Related
* [Workspaces](/reference/workspaces) - Understanding workspaces and permissions
* [Configuration files](/reference/configuration) - Complete `.tessl-plugin/plugin.json` reference
# Sharing with your team and publicly
Making your plugins publicly discoverable in the Tessl Registry
Plugins can be shared with your team or with the entire internet. This is controlled by the `private` field in your plugin's [`.tessl-plugin/plugin.json`](https://docs.tessl.io/distribute/pages/wpdogFLQtCeEnXfbelvK#plugin.json) file.
## Understanding public vs private plugins
### Private plugins (`"private": true`) - Default
**Shared only with your team:**
* Only accessible to workspace members
* Not discoverable in public searches
* Useful for proprietary code, internal standards, company-specific content
* **Team sharing:** [Add members to your workspace](/reference/workspaces#add-member) to give them access
If you don't specify the `private` field in your `.tessl-plugin/plugin.json`, it defaults to `true` (private).
### Public plugins (`"private": false`)
**Shared with the entire internet:**
* Anyone can discover and install them via the Tessl Registry
* Appear in search results and on your workspace's public profile
* Useful for open source libraries, shared standards, community resources
* **Cannot be made private again once published**
## Making a plugin public
**Warning:** Once you make a plugin public, you cannot make it private again. Use this with caution.
To make a plugin publicly discoverable, set `"private": false` in your [`.tessl-plugin/plugin.json`](https://docs.tessl.io/distribute/pages/wpdogFLQtCeEnXfbelvK#plugin.json):
```json
{
"name": "myworkspace/my-plugin",
"version": "1.0.0",
"description": "My public plugin",
"private": false,
"skills": "skills"
}
```
Then publish (or republish) your plugin:
```sh
tessl plugin publish
```
Your plugin is now publicly discoverable in the [Tessl Registry](https://tessl.io/registry) and accessible to anyone on the internet.
## Best practices
* **Start private** - Develop and test plugins privately before making them public
* **Use semantic versioning** - Especially important for public plugins that others depend on
* **Document thoroughly** - Include clear README files and usage examples
* **Validate before publishing** - Run `tessl plugin lint` to check for issues
## Related documentation
* [Distributing via registry](/distribute/distributing-via-registry) - How to publish plugins
* [Configuration files](/reference/configuration) - plugin.json field reference
* [Creating plugins](/creating-skills-and-plugins/create-a-plugin) - How to create your own plugins
# Permissions
The following permissions are required to configure and use Tessl with your repositories.
## **GitHub permissions**
You must have **`write` access**, so Tessl can create branches and open PRs.
## GitLab permissions
* A token with the scope of **`api`** is required.\* Project or Group tokens is required, webhooks will be set.
* For Group tokens, the **`Owner`** permission is required.
* Project tokens require **`Maintainer`** or above.
## **Tessl permissions**
* To enable GitHub or GitLab integration: **`Manager` or `Owner`.**
* To generate a plugin: **`Member`**.
* To distribute guidance across repositories: **`Publisher` or above** for the workspace.
If these permissions are missing, specific actions won’t appear in the interface.
# Connect Tessl to GitHub
Connect a GitHub account or organization so Tessl can scan its repositories and report Context and Findings in your Organization.
## Enable the SCM connection
You need the Organization admin role to manage SCM connections.
* Select your Organization from the dropdown at the top of the sidebar.
* Open **Settings**, then **Integrations**.
* Under **Source control**, select **Add** next to GitHub.
* Select the GitHub organization or account to add the Tessl App to. Accounts that already have Tessl will not have the option.
* Decide if you want to authorize Tessl on specific repositories or provide access to everything. Once selected, click *Install & Authorize*
* If the required permissions are available, the Tessl integrations screen shows **Connected**.
After the connection is created, Tessl may start a first scan of the repositories in scope. The connection can show **Connected** before a scan starts or finishes, or when scan provisioning is unavailable. Open the connection to check its scan status, retry a failed scan, or set its **Scan scope**.
## Review Context and Findings
When scan analysis succeeds and your Organization has an active workspace, Tessl starts indexing the repository skills it found. Without an active workspace, the scan still completes and its Context remains available, but indexing does not start. There is no private-indexing opt-in or manual first-party approval step.
Indexing, review, and security scoring run as separate background work. A skill can appear in **Context** before its scores are available, and scoring can fail without removing the Context item. Some advanced Finding details depend on your Organization's plan.
Select your Organization and open **Context** to browse the skills and configuration Tessl observed. Open **Findings** to inspect issues from the latest account scans. Organization members can view both pages. Organization admins can ignore or restore Findings and manage scan settings. See [Roles](/administrators/roles).
## Add or remove Repositories when *Only Select Repositories* are in use.
If you wish to later add repositories, you will navigate to the Tessl app in GitHub:
* Click *Configure* next to the Tessl App.
* Select or remove repositories as needed.
* Click *Save*.
## Troubleshooting
What if the option to **Add** the connection is not available? Confirm that you are an Organization admin, or ask an Organization admin to set up the connection. See [Roles](/administrators/roles).
# Connect Tessl to GitLab
To enable Tessl on your repositories, you will first navigate to the [Tessl Registry](https://tessl.io/registry) and login, if required.
## Enabling the Integration
* Select your workspace from the workspace switcher in the sidebar, below the organization dropdown.\
.png?alt=media)
* Open **Settings** in the sidebar, then select the **Integrations** section\
.png?alt=media)
.
If the integration belongs to your organization rather than this workspace, the workspace Integrations section only summarizes it. Manage the connection from the organization dropdown at the top of the sidebar → **Settings** → **Integrations** → **Manage**. This route needs the organization integration-management permission.
* Select *Add* next to the GitLab integration.
* Provide an access token with the correct [permissions](/distribute/permissions#gitlab-permissions) for a gitlab.com instance. \* If you are using a self hosted or customer-url for your instance, check the Use a custom instance URL box, and provide the necessary URL.
```
```
## Troubleshooting
What if the option to *Add Integration* isn't available? In the following example Tessl is not enabled and the user does not have the correct [Role](/administrators/roles) within Tessl (manager or owner) so the interface does not provide the option to integrate GitLab. To address this, ensure you have the correct [Role](/administrators/roles) within Tessl or request a user with these permissions to setup the integration.
# Initialize a repository
Using *Setup* on the Repositories view in [Tessl Registry](https://tessl.io/registry) creates a `tessl.json` file and adds any plugins Tessl has for the dependencies your repository uses. It also creates a `.mcp.json` file so people working in the repository can use Tessl as an MCP server for their coding agent.
## Setup Tessl
* Select your workspace from the workspace switcher in the sidebar, below the organization dropdown.\
.png?alt=media)
* Click on Repositories from the menu.\
.png?alt=media)
* Select *Setup Tessl*.
* Select the agents you wish to use and click *Setup*.
* Once clicked, a pull request will be created and a popup will be displayed to bring you to the pull request.
### The Pull request created
Pull requests may contain updates to `tessl.json` and `.mcp.json` based on your selections and the dependencies the repository contains.
* You or your pipeline automation would merge the request(s).\
%20\(1\).png?alt=media)
## Troubleshooting
If you do not see your repositories listed, see [Connect Tessl to GitHub](/distribute/connect-tessl-to-github) or [Connect Tessl to GitLab](/distribute/connect-tessl-to-gitlab).
* It's possible you are only allowing specific repositories, in which case you may need to select the additional repositories you wish to display in the GitHub settings or provide a group token with access in GitLab.
# Distribute plugins across multiple repositories
The Tessl web interface allows users, with the correct permissions, to create pull requests adding plugins to selected repositories. The following workflow demonstrates distributing a plugin that has guidelines that must be followed by the agents that company is using. This could include style guides, architecture and other guidelines that you now want to push across your organization.
Before you start, make sure your repositories are connected to Tessl and you have the required [permissions](/distribute/permissions):
* [Connect Tessl to GitHub](/distribute/connect-tessl-to-github) or [Connect Tessl to GitLab](/distribute/connect-tessl-to-gitlab)
* [Initialize a repository](/distribute/initialize-a-repository) if it has not been set up with Tessl yet
To distribute a plugin, follow these steps:
* Navigate to the workspace your plugin resides in.
* Click *Rollout* next to the plugin you wish to push.
* Indicate the Tessl workspace to roll the plugin out to.\
* Select which repositories the pull request will be created in.
* To complete the action, click *Create a rollout PR*.\
%20\(1\).png?alt=media)
* By doing this it will create a pull request adding the plugin to the tessl.json. A `.tessl-plugin/plugin.json` will be created if Tessl has not been initialized for that repository. An option to view the PR will be displayed:
* The PR will then be merged by you or your pipeline automations.
# Removing the integration
## GitHub Integration
To remove the GitHub integration, two steps are required:
\
1\) GitHub: Remove the Tessl App from within your GitHub Organization settings.
2\) Tessl: Click the delete icon next to the integration and confirm.
### GitHub removal
* Navigate to *Applications* and click on *Configure*
* Scroll and click the option to Uninstall, completing the steps to Uninstall when requested.
### Tessl Removal
* Select your workspace from the workspace switcher in the sidebar, below the organization dropdown.\
.png?alt=media)
* Open **Settings** in the sidebar, then select the **Integrations** section.
.\
.png?alt=media)
If the integration belongs to your organization rather than this workspace, the workspace Integrations section only summarizes it. Remove the connection from the organization dropdown at the top of the sidebar → **Settings** → **Integrations** → **Manage**. This route needs the organization integration-management permission.
* Click the delete icon next to the GitHub integration, then click *Uninstall* in the confirmation dialog.
***
## Gitlab integration
To remove the GitLab integration, two steps are required:
1\) Tessl: Click the delete icon next to the integration and confirm.
2\) GitLab, delete the integration token if it is no longer in use.
### Tessl & GitLab removal
* Select your workspace from the workspace switcher in the sidebar, below the organization dropdown.\
.png?alt=media)
* Open **Settings** in the sidebar, then select the **Integrations** section.\
.png?alt=media)
.
If the integration belongs to your organization rather than this workspace, the workspace Integrations section only summarizes it. Remove the connection from the organization dropdown at the top of the sidebar → **Settings** → **Integrations** → **Manage**. This route needs the organization integration-management permission.
* Click the delete icon next to the GitLab integration.
* Enter in the requested value\
%20\(1\).png?alt=media)
### Gitlab removal
For security purposes, it is generally good practice to delete old tokens that are no longer used. Navigate to the correct token area in Gitlab and delete the token used for the integration
# Using plugins directly from your repo
Use plugins directly from your repository for codebase-specific context
Instead of publishing plugins to the Tessl Registry, you can also check them directly into your repository. This is a simpler way to distribute plugins together with your code.
## When to check plugins into your repo vs using the registry
**Check plugins into your repo when:**
* You want a simple distribution method - plugins travel automatically with your code
* Context is tightly coupled to this specific codebase
* You don't need version management across multiple projects
**Use the Tessl Registry when:**
* You need centralized management and updates
* You want evaluation and review workflows
* You need automated distribution across multiple repositories
* You want to keep plugins up to date independently from code changes
## How it works
Repository-specific plugins are committed to your codebase and referenced in `tessl.json` with a `file:` source. Team members automatically get the plugin when they clone the repo and run `tessl install`.
## Setup
### 1. Create the plugin in your repository
cd my-repo
tessl plugin new --name myworkspace/my-plugin --path ./plugins/my-plugin
This creates the plugin structure for skills or rules:
```
my-repo/
├── plugins/my-plugin/
│ ├── .tessl-plugin/plugin.json
│ └── skills
│ └── my-plugin/
│ └── SKILL.md
│ └── rules/ # This repo's conventions
│ └── standards.md
└── tessl.json
```
### 2. Install it locally
Add the plugin to your project by referencing it in `tessl.json` with a `file:` source:
```bash
tessl install file:./plugins/my-plugin
```
This updates your `tessl.json`:
```json
{
"name": "my-project",
"dependencies": {
"myworkspace/my-plugin": {
"version": "1.0.0",
"source": "file:./plugins/my-plugin"
}
}
}
```
### 3. Commit both to version control
```bash
git add plugins/my-plugin/ tessl.json
git commit -m "Add repository-specific context plugin"
```
## Team workflow
When team members clone the repository:
```bash
git clone
cd
tessl install
```
The plugin installs automatically from the `file:` source in `tessl.json`. Everyone gets the same codebase-specific context.
## Updating the plugin
Changes to the plugin go through your normal code review process:
1. Edit plugin content (rules, skills)
2. Commit changes: `git commit -m "Update architecture docs"`
3. Create pull request
4. Team reviews context changes like code changes
5. Merge to main
Team members get updates when they pull and run `tessl install`.
## Benefits
* **Versioned with code** - plugin evolves alongside the codebase
* **Automatic distribution** - Team gets context when they clone
* **Code review** - Changes to patterns/architecture reviewed via PR
* **Private** - Context stays internal, no publishing needed
* **Self-documenting** - Codebase carries its own context
## Example: Monorepo workspaces
In monorepos, create workspace-specific plugins:
```
my-monorepo/
├── frontend/
│ ├── plugins/my-plugin/ # Frontend patterns
│ │ ├── .tessl-plugin/plugin.json
│ │ ├── skills/ # Frontend Testing methodology
│ │ └── rules/ # UI standards
│ └── tessl.json # References frontend plugin
├── backend/
│ ├── plugins/my-plugin/ # Backend patterns
│ │ ├── .tessl-plugin/plugin.json
│ │ ├── skills/ # Database migration process
│ │ └── rules/ # Backend standards
│ └── tessl.json # References backend plugin
└── shared/
└── plugins/my-plugin/ # Cross-cutting concerns
└── skills/ # Unified Code Review
```
Each workspace's `tessl.json` references its local plugin and any shared plugins:
```json
{
"dependencies": {
"myworkspace/frontend-context": {
"source": "file:./plugins/my-plugin"
},
"myworkspace/shared-context": {
"source": "file:../shared/plugins/my-plugin"
}
}
}
```
## Related
* [Developing plugins locally](/creating-skills-and-plugins/develop-and-test-locally) - Create and test plugins with local development workflow before checking them into your repo
* [Configuration files](/reference/configuration#plugin-configuration) - Complete plugin.json reference
# Promote or claim a skill you have created
Have you authored a skill in GitHub and want to promote it using Tessl? Tessl allows you to take a skill from a local repository or GitHub repository, and generate the plugin.json, which is essential for Tessl plugins and Skills. Once imported, you will publish the plugin to make it available, publicly or privately, to your teams. The following section discusses organization of your skills and how to publish them. Additionally if you have authored a plugin on GitHub that appears in Tessl, there is a section on [claiming that skill in Tessl](#claim-a-tessl-skill).
## Prerequisites
* Tessl [installed](/introduction-to-tessl/set-up-tessl/installation)
* Tessl logged in
* Skill code available locally
* Access to a [workspace](/reference/workspaces)
## Mapping and importing your skills into Tessl plugins
If you've authored a number of skills and documents to help your agents, you can logically group the related files together and create individual skill plugins in Tessl. For example:
* If you're developing a "data migration" skill, place all the files related to that skill and documentation in a single folder or repository. This would be a single plugin.
* Similarly if you've built a skill for "building a front end", that might contain best practices and design skills you would group them together into its own plugin, create the plugin.json, by running the import command, then lint, review, eval and publish the skill to your workplace.
### Anti-patterns
To avoid performance issues and confusion of your agents, avoid throwing in the kitchen sink! Make your skill purpose built, providing the information for specific tasks.
## Clone the Repository
Clone your repository locally.
## Create a .tessl-plugin/plugin.json
* Create a [.tessl-plugin/plugin.json](/reference/configuration#plugin-configuration) (metadata describing it) by running the following command, with your workspace and folder location values:
```
tessl skill import ./ --workspace
```
* You can create an eval file in `/eval` or request one through the web interface. More on this coming soon!
## Improve your skill with Lint, Review, and Evaluate your Skill
### Review your Skill against best practices
Before publishing, validate your skill structure and contents:
```sh
tessl skill lint ./my-skill
```
This command checks:
* `SKILL.md` format and structure
* Required frontmatter fields (name, description)
* Conformance to the Agent Skills specification
* Markdown validity
To optimize your skill, run the following:
```sh
tessl review fix ./my-skill
```
Fix any errors before proceeding.
### Evaluate quality using Scenarios
Once you've built your skill the final step before publishing is to create scenarios your skill can be evaluated against. The following document illustrates how you would accomplish this:
* [Evaluate skill quality using scenarios](/improving-your-skills/evaluate-skill-quality-using-scenarios)
## Set up GitHub Action to publish to Tessl's Registry
The following steps introduce the [GitHub action](https://github.com/tesslio/setup-tessl) to your repository to publish your plugin automatically.
Using the GitHub action will automatically link your plugin to the repository, and all skills we previously indexed in the repository will be hidden and redirected to the plugins.\
\
See Tessl's [setup-tessl GitHub action](https://github.com/tesslio/setup-tessl) for additional options and information.
{% stepper %}
{% step %}
**Create your workflow**
Create your workflow file `.github/workflows/tessl-publish.yml`. [Here's an example action for auto-publishing](https://github.com/tesslio/setup-tessl?tab=readme-ov-file#publish-a-plugin-on-push).
{% endstep %}
{% step %}
**Create an API Key**
Log into [Tessl](https://tessl.io) on web UI. Open your workspace, navigate to **Settings**, then **API keys**. Create a new API key. Copy the value as it will only be shown once.
{% endstep %}
{% step %}
**Add your API Key as a Repository Secret**
In GitHub, navigate to your repo **Settings**, select **Secrets and variables**, under actions find **New Repository Secret**. Provide the name: `TESSL_TOKEN` and the value is the Tessl API key you procured in the earlier step.
{% endstep %}
{% step %}
**Run your workflow**
Kick off your workflow by running the relevant trigger, or manually triggering from the UI if you enabled that in your workflow definition.
{% endstep %}
{% endstepper %}
## Claim a Tessl Skill
Found a skill in Tessl that is created/indexed from your Skill/GitHub repository of skills? You'll want to claim ownership and disable indexing by Tessl. To do this, you will:
* Recreate the skill in your workspace by importing it locally, update the workspace in `.tessl-plugin/plugin.json`.
* Use the [GitHub action to publish](https://github.com/tesslio/setup-tessl?tab=readme-ov-file#publish-a-plugin-on-push) , which will manage the Skill and ensure changes to the repo are reflected in your Tessl workspace and not reindexed by Tessl.
{% hint style="info" %}
If you accidentally use the CLI to publish a skill to your workspace, and the skill was already indexed by Tessl in the Tessl workspace, you would find two versions, in two different workspaces, when searching for that skill. You can [contact Tessl support](/support/giving-feedback) to claim your plugin and address the duplicate. Be sure to set up the GitHub action as part of this.
{% endhint %}
# Review, lint & publish with GitHub Actions
The following steps introduce the [GitHub action](https://github.com/tesslio/setup-tessl) to your repository. This action sets up `tessl` so it can be used for any CI/CD use case, such as auto-publishing plugins, linting or running skill reviews on PRs, etc.
If you're migrating your skill into Tessl's registry, using the GitHub action will automatically link your plugin to the repository, and all skills we previously indexed in the repository will be hidden and redirected to the plugins.\
\
See Tessl's [setup-tessl GitHub action](https://github.com/tesslio/setup-tessl) for additional options and information.
{% stepper %}
{% step %}
**Create your workflow**
Create your workflow file in `.github/workflows` for your desired action. For example, [here's how you'd set up an auto-publish action](https://github.com/tesslio/setup-tessl?tab=readme-ov-file#publish-a-plugin-on-push).
{% endstep %}
{% step %}
**Create an API Key**
Log into [Tessl](https://tessl.io) on web UI. Open your workspace, navigate to **Settings**, then **API keys**. Create a new API key. Copy the value as it will only be shown once.
{% endstep %}
{% step %}
**Add your API Key as a Repository Secret**
In GitHub, navigate to your repo **Settings**, select **Secrets and variables**, under actions find **New Repository Secret**. Provide the name: `TESSL_TOKEN` and the value is the Tessl API key you procured in the earlier step.
{% endstep %}
{% step %}
**Run your workflow**
Kick off your workflow by running the relevant trigger, or manually triggering from the UI if you enabled that in your workflow definition.
{% endstep %}
{% endstepper %}
## Gating pull requests with Tessl Review
Once `TESSL_TOKEN` is set as a repository secret, you can gate a pull request on a skill's review score using `tessl review run`. This is the authenticated, asynchronous review path: it requires auth and a workspace, kicks off a review pipeline server-side, and polls until the review completes. With `--json --threshold`, the command exits non-zero when the score falls below the threshold, failing the check.
The job below reviews a skill and fails if its score is under 80%:
```yaml
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 engteam --json --threshold 80
```
`--workspace` is required whenever `--json` is set, since CI runs non-interactively and cannot prompt for a workspace. Point the path at the skill file or skill directory you want to review.
For the full flag reference, see [`tessl review run`](/reference/cli-commands#tessl-review-run). For more on running reviews and the companion commands, see [Check a skill's quality using review](/improving-your-skills/reviewing-skills).
# Overview
Understand what Tessl projects are and why we need them.
A Tessl project gives Tessl a stable place to attach eval runs and other repository-connected data, so your results stay tied to your codebase over time.
### Why projects exist
Tessl needs a project so it knows where an eval belongs. That way your results aren’t just a one-off run — they stay linked to the repository, so you can find them later, compare runs, and keep improving the same codebase.
### Common workflows
#### Create a new project
Use `tessl project create` when this repository is not linked yet and you want to create a new Tessl project. The command creates the project, then records the project link in `tessl.json`, creating the file if it does not exist yet. `tessl init` sets up local agent configuration and bootstraps `tessl.json` if it does not exist, but it does not create or link a remote project on its own; run `tessl project create` or `tessl project link` for that.
#### Link to an existing project
Use `tessl project link` when the Tessl project already exists for that repository.
#### Repair a project link
Use `tessl project repair` when the project link is missing, broken, outdated, or linked to the wrong project.
### Current limitations
Projects currently have limited fallback when a directory is not a Git repository.
### See also
* [Manage projects from the CLI](/projects/manage-projects-from-the-cli)
* [Projects in the app](/projects/projects-in-the-app)
# Manage projects from the CLI
Set up and repair project links from the Tessl CLI.
Start with `tessl init` or `tessl project create`. Both commands recognize a Tessl project that already matches the current repository and link it automatically when there is one clear match.
If you're blocked when starting an eval, this is usually the page you need.
Creating a Tessl project does not create a new Git repository. It creates the Tessl project for the repository you are already working in.
### When you are asked to create a project
Tessl asks for a project when it needs to identify the repository behind the current directory.
This happens most often when you run an eval from a repository that is not linked yet.
### Automatic setup
Run `tessl init` to set up Tessl and your coding agents. If the repository already has a project that Tessl discovered from GitHub, `tessl init` records that link in a new `tessl.json`. It does not create a duplicate project.
Run `tessl project create` when you only need to set up the project link. The command creates `tessl.json` if it is missing, then:
* Links the project automatically when exactly one project matches the repository and package path
* Creates a project when none match
* Shows the matching projects and the resolving command when more than one match is available
Both commands show the repository, matched project, manifest link, and next action after an automatic match.
### Which explicit command should I use?
| Command | Use it when | What it does |
| ---------------------- | ------------------------------------------------ | ------------------------------------------------------------------------------- |
| `tessl project create` | This directory is not linked yet | Links one matching project automatically, or creates a project when none match |
| `tessl project link` | Several projects match and you need to choose | Links this directory to the selected existing project |
| `tessl project repair` | An existing local link is missing, wrong, or old | Inspects the link and applies an explicit relink, source update, or name update |
### `tessl project create`
Sets up the Tessl project link for the current repository checkout.
Use this when the current repository is not linked yet. The command checks the projects across your organization before it creates anything.
If no `tessl.json` is found in this directory or any parent directory, the command creates one before proceeding. You do not need to run `tessl init` first.
If a `tessl.json` already exists in a parent directory (but not in the current directory), the command stops and asks you to pass `--nested`. Run it again with `--nested` to create a new `tessl.json` in the current directory and a separate project for it, rather than reusing the parent project.
When one existing project matches, the command records its full `workspace/project` link in `tessl.json`. When no project matches, it creates one and records the new link. Use `--new` with an explicit workspace and project name only when you intentionally need another project for the same repository.
### `tessl project link`
Links the current repository to an existing Tessl project.
Use this when several projects match and you need to choose one explicitly.
This command only links to an existing project. It does not create a new one.
If you want to create a brand new project for this repository, use `tessl project create` instead.
### `tessl project repair`
Inspects or repairs the Tessl project link for the current repository.
Use this when the repository should already be linked to a project, but the link is missing, broken, outdated, or no longer matches the expected repository.
Use `--relink` to connect the repository to a different existing project, `--update-source` to keep the linked project but approve this repository as its source, and `--update-name` to rename the linked project to match `tessl.json`.
### What happens after linking
Once a repository is linked:
* Evals attach to that Tessl project
* The CLI and app can show one shared evaluation history
# Repairing projects
Understand how to diagnose and fix issues with projects.
Use `tessl project repair` when Tessl detects that the project identity for your current repository no longer matches the project it is linked to.
A Tessl project has two parts of identity:
* its **locator** — the project name in `tessl.json`
* its **source** — the repository Tessl sees for the current directory
If those drift apart, Tessl can stop evals from running until you repair the association.
### What `tessl project repair` does
`tessl project repair` helps you diagnose and fix **project identity drift** for the current repository.
Depending on the problem, you can use it to:
* inspect the current mismatch
* **relink** this repository to a different existing Tessl project
* **update the source** recorded for the currently matched Tessl project
* **update the project name** to match a local rename
### Start by diagnosing
Run this first:
```bash
tessl project repair
```
This checks the current repository and shows whether the problem is:
* a **locator drift**
* a **source drift**
* a **rename drift**
* a more complete mismatch that needs relinking or project creation
If you just want machine-readable output, use:
```bash
tessl project repair --json
```
### When to use each repair action
### Relink to a different project
Use this when your current repository is linked to the **wrong Tessl project**.
```bash
tessl project repair --relink --workspace --project --yes
```
Use `--relink` when:
* Tessl matched the wrong project
* your repository should belong to a different existing project
* you are in a monorepo and the current package or subpath was associated with the wrong project
* the locator in `tessl.json` is missing, stale, or points at the wrong project
#### Example: locator drift
Your current repository source matches an existing Tessl project, but the project named in `tessl.json` does not.
For example:
* local `tessl.json` does **not** point to the right project
* Tessl can see that the current repo actually matches `team-two/real-project`
In that case, relink the current repository to the correct project:
```bash
tessl project repair --relink --workspace team-two --project real-project --yes
```
### Update the source for the current project
Use this when the **project is correct**, but Tessl has the wrong **repository source** recorded for it.
```bash
tessl project repair --update-source --yes
```
Use `--update-source` when:
* the repo remote changed
* the repo was renamed or transferred
* the repo subpath changed in a way Tessl should now treat as the project’s canonical source
* Tessl found the right project by name, but the current repository source no longer matches the stored source
#### Example: repoistory name change
Your `tessl.json` still points to the correct project, but the underlying repository source has changed.
For example:
* locator: `team-one/old-name`
* recorded source: `https://github.com/acme/old-name`
* current local source: `https://github.com/acme/new-name`
In that case, keep the same project and update its recorded source:
```bash
tessl project repair --update-source --yes
```
Use this when the project identity is still right and only the source has drifted.
### Update the project name
Use this when the **repository is still linked correctly**, but the **project name has changed** locally.
```bash
tessl project repair --update-name --yes
```
Use `--update-name` when:
* you renamed the project in `tessl.json`
* the repo still matches the existing project source
* you want the Tessl project name to match the new local name
#### Example: rename drift
Your repository still matches the same project source, but the name in `tessl.json` changed.
For example:
* old name: `team-one/old-project`
* new local name: `team-one/renamed-project`
In that case, repair the name without relinking or recreating the project:
```bash
tessl project repair --update-name --yes
```
### How to decide which one to use
Use:
* `--relink` when the repository should point to a **different existing project**
* `--update-source` when the **project is right** but its **recorded source is outdated**
* `--update-name` when the **project is right** but its **name changed**
A simple rule:
* wrong project → **relink**
* wrong repo source → **update source**
* wrong project name → **update name**
### When repair is not the right command
You usually do **not** need repair when:
* you are creating a Tessl project for the first time
* there is no existing project association yet
* Tessl is asking you to create a project before your first eval
In those cases, use the normal create or link flow instead.
## Project visible in the web app but missing after cloning
**Symptom.** The project appears in the Tessl web app. A fresh clone has no `tessl.json`, and `tessl install` or `tessl init` behaves as if no project exists.
**Cause.** A teammate created the project but did not commit `tessl.json` to the repository. Without it the CLI has no stored project link and cannot connect automatically. Running `tessl install` blocks when the backend confirms a match, and `tessl init` offers to link inline when the session is interactive and exactly one project matches.
### The `tessl install` block
When the CLI confirms the backend already has a project for this repository, `tessl install ` exits with an error rather than creating a second, disconnected project:
```
A Tessl project already exists for this repository but no tessl.json was found.
To link this directory to the existing project, run:
tessl init
tessl project repair --relink --workspace engteam --project my-project --yes
Ask the teammate who created the project to commit tessl.json, so the next clone links to it.
```
When more than one project matches, the relink command uses placeholders and a `Matching projects:` list follows, one `workspace/project` per line, so you can choose the right one and fill in the values.
If the backend check cannot run (authentication failure, network error, or timeout), `tessl install` falls through to normal initialization instead of blocking.
### The `tessl init` prompt
#### Interactive session with one matching project
When the CLI confirms a single matching project and the session is interactive, `tessl init` asks:
```
Link this directory to engteam/my-project? (Y/n)
```
* **Yes**: writes `tessl.json` already linked to the existing project. No relink step is needed.
* **No**: writes an unlinked `tessl.json` and prints the relink command after `Init complete!`.
#### Non-interactive session, declined prompt, or multiple matching projects
When init cannot link inline, it writes an unlinked `tessl.json` and prints the relink command after `Init complete!`.
**Single matching project**: the printed command includes the project's workspace and name:
```bash
$ tessl project repair --relink --workspace engteam --project my-project --yes
```
**Multiple matching projects**: the printed command uses placeholders, followed by a list of candidates:
```
tessl project repair --relink --workspace --project --yes
Matching projects:
engteam/project-a
engteam/project-b
```
Choose the correct project from the list and substitute its workspace and name into the command.
### Running from a subdirectory
When the CLI confirms the project is registered at the repository root but the command runs from a subdirectory:
* `tessl install` exits with an error that names the repository root and the recovery commands to run from there.
* `tessl init` stops without writing anything and tells you to run `tessl init` from the repository root.
Move to the repository root and run the recovery from there. If the backend check cannot run, both commands fall through to normal initialization instead.
### The commit nudge
When `tessl init` creates a new `tessl.json` that is not yet tracked by git, the CLI prints:
```
Commit tessl.json so teammates connect to the same project. Leaving it uncommitted is the most common cause of project mismatch errors.
```
This nudge fires when the manifest is linked, either for a fresh project or after the user accepts the link prompt. When init writes an unlinked manifest (user declined or non-interactive path), the nudge is suppressed; run the relink command first, then commit.
### Prevention
Commit `tessl.json` immediately after running `tessl init` or `tessl project create`. Every teammate who clones the repository will then connect to the same project without needing to relink.
# Projects in the app
Browse organization-level projects and review project-level activity in the Tessl app.
Projects are visible at the organization level and in project-specific views.
Each Tessl project represents a repository, so the app can show repository-level eval history in one place.
Projects are stored in a workspace for permissions and compatibility, but appear in the organization that owns that workspace.
### Organization Projects list
Use the Projects list to:
* Browse projects across your organization
* Filter projects by their backing workspace
* Open a project's detail view
### Project eval views
Each project has app views that show project-level evaluation history.
Use these views to:
* Inspect evaluation history over time
* Review results connected to the same repository
* Understand the state of evaluations for a codebase
# CLI commands
The Tessl CLI provides commands for managing plugins, workspaces, authentication, repository configuration, and Tessl projects. This page provides a comprehensive reference for all available commands.
{% hint style="info" %}
On this page, **repository** means your Git repository. **Tessl project** means the stable home for Tessl in that repository.
{% endhint %}
## Getting started
### tessl help command
To see all available commands, run:
```sh
tessl --help
```
To get detailed information about a specific command or command group, use the `--help` flag:
```sh
tessl --help
tessl --help
```
***
## Authentication
### tessl login
Authenticate with Tessl.
**Usage**
```shell-session
$ tessl login [--device | --loopback]
```
Use `--device` to sign in with a device code instead of a local browser redirect. Use `--loopback` to sign in with a local browser redirect. Use only one of these flags.
Organizations using the EU region must have `TESSL_ENV=app-eu` set in the CLI's environment and use device login:
```shell-session
$ TESSL_ENV=app-eu tessl login --device
```
See [Using the EU region](/administrators/eu-region) for the full setup, including shell profiles, CI, and MCP servers.
**Alternative**
```sh
tessl auth login
```
### tessl logout
Sign out and clear credentials.
**Usage**
```sh
tessl logout
```
**Alternative**
```sh
tessl auth logout
```
### tessl whoami
Show current authenticated user.
**Usage**
```sh
tessl whoami
```
**Alternative**
```sh
tessl auth whoami
```
***
## Setup and initialization
### tessl init
Set up your repository and configure your coding agent.
**Usage**
```sh
tessl init [--agent ]... [--name ]
```
**Flags**
* `--agent` (string, optional, repeatable): Configure MCP for coding agent. Supported values: `claude-code`, `cursor`, `gemini`, `antigravity`, `codex`, `openhands`, `openclaw`, `copilot`, `copilot-vscode`, `agents`, `tessl-agent`. Can specify multiple agents. See [Custom Agents](/reference/custom-agent-setup) for information on configuring additional agents.
* `--name` (string, optional): Project name for new `tessl.json` (default: current directory name)
**Notes**
* Configures MCP server settings for AI coding agents
* Creates a `tessl.json` manifest at the repository root
**Examples**
```sh
# Basic initialization with default settings
tessl init
# Initialize and configure Cursor integration
tessl init --agent cursor
# Initialize with multiple agents
tessl init --agent cursor --agent claude-code
```
### tessl project
Create, link, or repair the Tessl project for this repository.
A Tessl project gives Tessl a stable place to attach eval runs and other repository-connected data, so your results stay tied to your codebase over time.
Use these commands to create a new project, link this checkout to an existing project, or repair a missing or broken reference in `tessl.json`. For a workflow guide, see [Manage projects from the CLI](/projects/manage-projects-from-the-cli).
**Usage**
```sh
tessl project
```
### tessl project create
Create a new Tessl project for the current repository.
**Usage**
```sh
tessl project create [--nested] [--new] [--workspace ] []
```
**Flags**
* `--nested` (boolean, optional): Required when a parent directory has a `tessl.json` but the current directory has none. Creates a separate `tessl.json` and project for the current directory instead of reusing the parent project.
* `--new` (boolean, optional): Create a new project for a different workspace. Use with `--workspace` and provide a project name when you intentionally want a separate new project for the same repository.
* `--workspace` (string, optional): Name or ID of workspace
**Arguments**
* `project-name` (string, optional): Name for the new project. If omitted, you'll be prompted.
**Notes**
* Use this when this repository is not linked to a project yet and you want to create one in Tessl
* This command always creates a new project
* If this repository should use a project that already exists, use `tessl project link` instead
### tessl project link
Link the current repository to an existing Tessl project.
**Usage**
```sh
tessl project link [--workspace ]
```
**Flags**
* `--workspace` (string, optional): Name or ID of workspace to search
**Notes**
* Use this when the project already exists in Tessl and you want this repository to use it
* This command only links to an existing project
* If you want to create a brand new project for this repository, use `tessl project create` instead
### tessl project repair
Inspect or repair the Tessl project link for the current repository.
**Usage**
```sh
tessl project repair [--json] [--relink] [--workspace ] [--project ] [--update-source] [--update-name] [--yes]
```
**Flags**
* `--json` (boolean, optional): Output as JSON, for automation or agent workflows
* `--relink` (boolean, optional): Relink this repository to a different existing project
* `--workspace` (string, optional): Workspace name or ID for `--relink`
* `--project` (string, optional): Project name for `--relink` target
* `--update-source` (boolean, optional): Approve this repository as the linked project source
* `--update-name` (boolean, optional): Rename the linked project to match `tessl.json`
* `--yes` / `-y` (boolean, optional): Confirm and apply requested repair
**Notes**
* Use this when this repository should already be linked to a project, but the link is missing, broken, outdated, or no longer matches the expected repository or project details
### tessl project list
List all projects in a workspace.
**Usage**
```sh
tessl project list [--workspace ] [--json]
```
**Flags**
* `--workspace` (string, optional): Name or ID of workspace.
* `--json` (boolean, optional): Output as JSON.
**Notes**
* Shows every project you can access in the selected workspace, with its name, ID, and source.
* The workspace is resolved in this order: `--workspace`, the `TESSL_WORKSPACE` environment variable, the project linked in `tessl.json`, then the workspace prefix in a `.tessl-plugin/plugin.json` when no `tessl.json` exists. If none of those apply and you belong to more than one workspace, you are prompted to pick one, or must pass `--workspace` in a non-interactive shell.
**Examples**
```sh
# List projects in the resolved workspace
tessl project list
# List projects in a specific workspace
tessl project list --workspace engteam
# Output as JSON
tessl project list --json
```
***
## Project dependencies
### tessl install
Install plugins into your repository. plugins are versioned bundles of reusable, agent-agnostic context that make coding agents more effective. They can contain skills, documentation, and rules.
**Alias**: `tessl i`
**Usage**
```sh
tessl install [--global] [--skill ]... [--yes] [--verbose] [--watch-local] [--accept-warnings] [--strict] [--agent ]... ...
```
**Arguments**
* `source` (string, required): plugin or GitHub URL to install. Can be:
* Registry plugin: `workspace/plugin[@version]` (version optional, defaults to latest)
* GitHub repository:
* Full URL: `https://github.com/owner/repo`
* Shorthand: `github:owner/repo` (e.g., `github:softaworks/agent-toolkit`)
* File path: `file:` to install from local directory
**Flags**
* `--global` / `-g` (boolean, optional): Install plugins globally to `~/.tessl/` instead of the current repository. Global plugins are available across all your repositories.
* `--skill` (string, repeatable, optional): Select specific skills to install from GitHub repositories. Used when a repository contains multiple skills. If omitted, you'll be prompted interactively to select from available skills. Can be specified multiple times to install multiple skills from the same repository.
* `--yes` (boolean, optional): Skip confirmation prompts and auto-select all skills
* `--verbose` / `-v` (boolean, optional): Show detailed warning messages during installation
* `--watch-local` (boolean, optional): Watch local file-source plugins and reinstall on changes
* `--accept-warnings` (boolean, optional): Pre-accept install policy warnings (no interactive prompt)
* `--strict` (boolean, optional): Fail if a version is too new rather than installing an older fallback
* `--agent` (string, optional, repeatable): Override agents to install for. Supported values: `claude-code`, `cursor`, `gemini`, `antigravity`, `codex`, `openhands`, `openclaw`, `copilot`, `copilot-vscode`, `agents`, `tessl-agent`.
**Notes**
* Plugins are installed to `.tessl/plugins//` in your repository (or `~/.tessl/plugins/` when using `--global`)
* Your repository's `tessl.json` is automatically updated with the plugin reference
* If a plugin is already installed and up-to-date, it will be skipped
* **GitHub URL formats**: `https://github.com/owner/repo`, `github:owner/repo`, or with branch/path: `https://github.com/owner/repo/tree/main/skills/pdf`
* **File system installation**: Use `file:` to install from a local directory (`.tessl-plugin/plugin.json` expected in the path)
* **Install policy warnings**: If a plugin triggers install policy warnings (such as critical or high Snyk security findings), you will be asked for permission before installation continues. You can always choose to proceed — installation is never blocked. Use `--accept-warnings` to pre-accept these warnings and skip the prompt.
**Examples**
```sh
# Install a specific plugin from registry
tessl install tessl/svelte@5.38.0
# Install multiple plugins from registry
tessl install tessl/svelte tessl/react
# Install from file system (.tessl-plugin/plugin.json is expected in the specified path)
tessl install file:
# Install from GitHub repository with interactive skill selection
tessl install https://github.com/anthropics/skills
# Install using GitHub shorthand syntax
tessl install github:softaworks/agent-toolkit
# Install specific skill by name from GitHub repository (when repo has multiple skills)
tessl install https://github.com/anthropics/skills --skill pdf
# Install multiple skills by name from GitHub repository using shorthand
tessl install github:anthropics/skills --skill pdf --skill pptx
# Install from specific branch and path in GitHub repository
tessl install https://github.com/anthropics/skills/tree/main/skills/pdf
# Install from a specific commit (useful when the registry shows security results for that commit)
tessl install engteam/my-skill@abc1234
# Install a plugin globally (available across all repositories)
tessl install --global tessl/svelte
```
### tessl search
Search for plugins and skills in the Tessl registry by name, PURL, or HTTP URL.
**Usage**
```sh
$ tessl search [--global] [--type skills|docs|rules] [--org | --workspace ] [--json] []
```
**Flags**
* `--global` / `-g` (boolean, optional): Install selected plugins and skills globally to `~/.tessl/` instead of the current project
* `--type` (string, optional): Filter by content type. Supported values: `skills`, `docs`, `rules`
* `--org` (string, optional): Limit results to an organization you can access, identified by its slug or ID
* `--workspace` (string, optional): Limit results to a workspace you can access, identified by `org/workspace` or its ID
* `--json` (boolean, optional): Output search results as JSON
`--org` and `--workspace` require authentication and cannot be used together.
**Arguments**
* `query` (string, optional): Search query (name, PURL, or HTTP URL). If omitted, you'll be prompted interactively.
**Examples**
```sh
# Search for plugins matching "svelte"
$ tessl search svelte
# Search and install selected results globally
$ tessl search --global svelte
# Search for skills in an organization
$ tessl search --type skills --org acme code-review
# Search for skills in a workspace
$ tessl search --type skills --workspace acme/engteam code-review
# Interactive search
$ tessl search
```
### tessl uninstall
Uninstall plugins from your repository.
**Usage**
```sh
tessl uninstall [--global] [--skill ]...
```
**Arguments**
* `workspace/plugin` (string, required): Full plugin name in the format `workspace/plugin`
**Flags**
* `--global` / `-g` (boolean, optional): Uninstall plugins from the global `~/.tessl/` directory instead of the current repository
* `--skill` (string, repeatable, optional): Remove specific skills instead of the entire plugin (repeatable)
**Notes**
* Removes the plugin from `tessl.json` and deletes files from `.tessl/plugins/`
* Does not require authentication (local operation only)
**Examples**
```sh
# Uninstall a plugin from the current repository
tessl uninstall tessl/svelte
# Uninstall a globally installed plugin
tessl uninstall --global tessl/svelte
```
### tessl list
List all installed plugins in your repository.
**Usage**
```sh
tessl list [--global] [--json]
```
**Flags**
* `--global` / `-g` (boolean, optional): List plugins installed in global `~/.tessl/` instead of the current repository
* `--json` (boolean, optional): Output plugins as JSON instead of human-readable format
**Notes**
* Lists all plugins installed in your repository based on `tessl.json`
* Shows plugin names in the format `workspace/plugin` with their versions
* Does not require authentication (local operation only)
**Examples**
```sh
# List all installed plugins
tessl list
# List plugins in JSON format
tessl list --json
```
### tessl outdated
Check for available plugin updates.
**Usage**
```sh
tessl outdated [--json]
```
**Flags**
* `--json` (boolean, optional): Output as JSON
**Examples**
```sh
# Check for outdated plugins
tessl outdated
# Output as JSON
tessl outdated --json
```
### tessl update
Update plugins to newer versions.
**Usage**
```sh
tessl update [--yes] [--force] [--global] [--accept-warnings] [--agent ]... []
```
**Flags**
* `--yes` / `-y` (boolean, optional): Skip prompts and update all compatible plugins
* `--force` / `-f` (boolean, optional): Include breaking updates
* `--global` / `-g` (boolean, optional): Update plugins installed globally in `~/.tessl/` instead of the current repository
* `--accept-warnings` (boolean, optional): Pre-accept install policy warnings (no interactive prompt)
* `--agent` (string, optional, repeatable): Override agents to sync for. Supported values: `claude-code`, `cursor`, `gemini`, `antigravity`, `codex`, `openhands`, `openclaw`, `copilot`, `copilot-vscode`, `agents`, `tessl-agent`.
**Arguments**
* `plugin` (string, optional): plugin to update in the format `workspace/plugin`. If omitted, updates all plugins.
**Notes**
* If a plugin triggers install policy warnings in the new version (such as critical or high Snyk security findings), you will be asked for permission before the update is applied. Use `--accept-warnings` to pre-accept these warnings and skip the prompt.
**Examples**
```sh
# Update all plugins interactively
tessl update
# Update all plugins without prompts
tessl update --yes
# Update a specific plugin
tessl update engteam/my-plugin
# Include breaking updates
tessl update --force
```
***
## Skill management
### tessl skill new
Create a new skill with an interactive wizard or using flags.
**Usage**
```sh
tessl skill new [--name NAME] [--description DESCRIPTION] [--workspace WORKSPACE] [--path PATH] [--install] [--public]
```
**Flags**
* `--name` (string, optional): Skill name
* `--description` (string, optional): When the skill should be triggered
* `--workspace` (string, optional): Workspace for the skill (default: local)
* `--path` (string, optional): Directory path where the skill will be created
* `--install` (boolean, optional): Automatically install in the current repository after creation
* `--public` (boolean, optional): Make the skill public (default: private)
**Notes**
* If flags are omitted, an interactive wizard will guide you through skill creation
* The skill will be created as a directory with the proper Agent Skills specification structure
* Use `--install` to immediately add the skill to your local agent configuration
**Examples**
```sh
# Create a skill interactively
tessl skill new
# Create a skill with all details specified
tessl skill new --name "commit-conventions" --description "Enforce commit message standards" --workspace myteam --install
```
### tessl skill import
Create `.tessl-plugin/plugin.json` from a local `SKILL.md` file.
**Usage**
```sh
tessl skill import [--workspace WORKSPACE] [--public] [--force] []
```
**Flags**
* `--workspace` (string, optional): Workspace for the skill (default: local)
* `--public` (boolean, optional): Make skill public (default: private)
* `--force` (boolean, optional): Overwrite existing `.tessl-plugin/plugin.json` without prompting
**Arguments**
* `path` (string, optional): Local path to directory containing SKILL.md or to SKILL.md file. Defaults to current directory if omitted.
**Examples**
```sh
# Import from current directory
tessl skill import
# Import from a specific path
tessl skill import ./my-skill
# Import and make public
tessl skill import --public --workspace myteam ./my-skill
```
### tessl skill lint
Validate skill structure and contents.
**Usage**
```sh
tessl skill lint []
```
**Arguments**
* `source` (string, optional): Path to skill folder or plugin.json. Defaults to current directory if omitted.
**Notes**
* Checks for required files and proper structure
* Validates frontmatter fields (name, description, etc.)
* Verifies conformance to the Agent Skills specification at [agentskills.io/specification](https://agentskills.io/specification)
* Returns validation errors and warnings
**Examples**
```sh
# Lint skill in current directory
tessl skill lint
# Lint skill at specific directory path
tessl skill lint ./my-skill
```
### tessl skill publish
Import (if needed) and publish skill to the registry. This command bundles skills, rules, documentation into a plugin.
**Usage**
```sh
tessl skill publish [--workspace WORKSPACE] [--public] [--force] [--bump patch|minor|major] [--dry-run] [--skip-evals] [--with-scenario-quality-check] [--eval-scenarios ] [--resolve-symlinks] []
```
**Flags**
* `--workspace` (string, optional): Workspace for the skill (used if importing)
* `--public` (boolean, optional): Make skill public (used if importing)
* `--force` (boolean, optional): Overwrite existing `.tessl-plugin/plugin.json` without prompting
* `--bump` (string, optional): Auto-bump version if it already exists in the registry. Supported values: `patch`, `minor`, `major`
* `--dry-run` (boolean, optional): Run all pre-publish checks without publishing
* `--skip-evals` (boolean, optional): Skip publishing eval scenarios from evals/ directory
* `--with-scenario-quality-check` (boolean, optional): Exclude misleading scenarios from the publish-time eval run
* `--eval-scenarios` (string, optional): Path to eval scenarios directory (default: `/evals`)
* `--resolve-symlinks` (boolean, optional): Resolve symlinked files to their target contents when packing
**Arguments**
* `path` (string, optional): Path to the skill directory to publish. Defaults to current directory if omitted.
**Notes**
* Skills are automatically linted before publishing
* Published skills are versioned based on the version in the skill manifest
* Eval scenarios from the `evals/` directory are published by default; use `--skip-evals` to exclude them
* **Automatic evaluation**: When published, skills are automatically evaluated and review scores are calculated (see [Check a skill's quality using review](/improving-your-skills/reviewing-skills))
**Examples**
```sh
# Publish skill from current directory
tessl skill publish
# Publish to a specific workspace
tessl skill publish --workspace myteam ./my-skill
# Publish publicly
tessl skill publish --public
```
### tessl skill unpublish
Prints guidance explaining that skills cannot be unpublished on their own. Performs no registry action. `tessl skill archive` and `tessl skill delete` print the same guidance.
Skills are published inside a plugin. To remove a published skill, delete the skill and republish the plugin, unpublish the plugin, or archive the plugin. See [tessl plugin unpublish](#tessl-plugin-unpublish) and [tessl plugin archive](#tessl-plugin-archive).
***
## Tessl Review
The `tessl review` family runs an asynchronous review pipeline server-side. These commands require authentication; `run` and `fix` also require a workspace. The pipeline is bundle-aware, and `tessl review run` polls until it completes. This is the primary path for authenticated users and CI gating.
### tessl review run
Run an asynchronous **quality** review of a skill — it scores the skill against a reviewer rubric. `tessl review run` is shorthand for `tessl review run quality`; to run a security scan instead, use `tessl review run security` (documented below). Requires authentication and a workspace.
**Usage**
```sh
tessl review run [--json] [--workspace WORKSPACE] [--threshold ] [--label ] [--force] [--review-plugin ] [--no-wait] []
```
**Flags**
* `--json` (boolean, optional): Output as JSON
* `--workspace` / `-w` (string, optional): Workspace name or ID. Required when `--json` is set
* `--threshold` (number, optional): Exit non-zero if the review score is below this percentage. `0` never fails (skips validation and score gating)
* `--label` / `-l` (string, optional): Label to describe this review run
* `--force` / `-f` (boolean, optional): Run a fresh review even when cached results exist
* `--review-plugin` (string, optional): Reviewer plugin — a path to a local plugin directory, or a registry ref `workspace/plugin[@version]`. Requires a paid plan; on a Free organisation, passing this flag returns an upgrade error
* `--wait` / `--no-wait` (boolean, optional): Wait for the review to finish before returning (default: wait; use `--no-wait` to submit and return the run id immediately, then reconnect with `tessl review view`). Cannot be combined with `--threshold`, which needs the completed score
**Arguments**
* `path` (string, optional): Path to a skill file or skill directory. Defaults to current directory if omitted.
**Notes**
* Requires authentication; sign in with `tessl login` or set the `TESSL_TOKEN` API key in the environment
* `--workspace` is required when `--json` is set, since non-interactive runs cannot prompt for a workspace
* The command polls until the review completes, then prints the results
* `--threshold` causes a non-zero exit when the score falls below the percentage, making it a CI gate
* Press Ctrl+C to detach — the review continues server-side and can be viewed later with `tessl review view`
* `run` has two subcommands: `quality` (the default, documented here) and `security` (below). `tessl review run quality` is the explicit form of the default
**Examples**
```sh
# Review the skill in the current directory
tessl review run --workspace engteam
# Review a skill at a specific path
tessl review run ./my-skill --workspace engteam
# CI gate: fail if the score is below 80%
tessl review run ./my-skill --workspace engteam --json --threshold 80
# Review with a specific reviewer plugin
tessl review run ./my-skill --workspace engteam --review-plugin engteam/my-reviewer
```
### tessl review run security
Run an asynchronous security scan of a skill, powered by Snyk. Reports findings and the highest severity. Requires authentication and a workspace.
**Usage**
```sh
tessl review run security [--json] [--workspace WORKSPACE] [--label ] [--force] [--fail-on ] [--no-wait] []
```
**Flags**
* `--json` (boolean, optional): Output as JSON
* `--workspace` / `-w` (string, optional): Workspace name or ID. Required when `--json` is set
* `--label` / `-l` (string, optional): Label to describe this security review run
* `--force` / `-f` (boolean, optional): Run a fresh scan even when cached results exist
* `--fail-on` (string, optional): Exit non-zero if the highest severity is at or above this level: `low`, `medium`, `high`, `critical`
* `--wait` / `--no-wait` (boolean, optional): Wait for the scan to finish before returning (default: wait; use `--no-wait` to submit and return the run id immediately, then reconnect with `tessl review view`). Cannot be combined with `--fail-on`, which needs the completed findings
**Arguments**
* `path` (string, optional): Path to a skill file or skill directory. Defaults to current directory if omitted.
**Notes**
* Requires authentication; sign in with `tessl login` or set the `TESSL_TOKEN` API key in the environment
* The scan runs server-side; the command polls until it completes, then prints the findings and the highest severity
* `--fail-on` gates the exit code on severity, making it a CI gate — the security equivalent of `--threshold` on a quality review
**Examples**
```sh
# Security-scan the skill in the current directory
tessl review run security --workspace engteam
# Scan a skill at a specific path
tessl review run security ./my-skill --workspace engteam
# CI gate: fail if any finding is high or critical
tessl review run security ./my-skill --workspace engteam --json --fail-on high
```
### tessl review view
View results for a review run of either kind. The run ID resolves whether it is a quality or a security review, and the results are rendered accordingly.
**Usage**
```sh
tessl review view [--json] [--last] [--threshold ] [--fail-on ] [--workspace ] []
```
**Flags**
* `--json` (boolean, optional): Output as JSON, in the same shape as `tessl review run --json`
* `--last` (boolean, optional): View results for the most recent review run
* `--threshold` (number, optional): Quality reviews only. Exit non-zero if the review score is below this percentage (0-100)
* `--fail-on` (string, optional): Security reviews only. Exit non-zero if the highest severity is at or above this level: `low`, `medium`, `high`, `critical`
* `--workspace` / `-w` (string, optional): Workspace name or ID. Only applies with `--last`; an explicit review run ID already identifies its workspace.
**Arguments**
* `id` (string, optional): Review run ID. Provide an ID or use `--last`.
**Notes**
* Provide a review run ID or use `--last`; one is required
* The gate flag follows the run's kind: `--threshold` gates a quality run, `--fail-on` gates a security run. Passing the flag for the other kind is a usage error
* `--workspace` is only accepted with `--last`; passing it alongside an explicit review run ID fails with a validation error
**Examples**
```sh
# View a specific review run
tessl review view abc123
# View the most recent review run
tessl review view --last
# Re-check a stored run against a threshold
tessl review view abc123 --json --threshold 80
```
### tessl review list
List recent review runs.
**Usage**
```sh
tessl review list [--json] [--limit ] [--workspace WORKSPACE]
```
**Flags**
* `--json` (boolean, optional): Output as JSON
* `--limit` (number, optional): Maximum number of review runs to display (default: 20)
* `--workspace` / `-w` (string, optional): Workspace name or ID
**Examples**
```sh
# List recent review runs
tessl review list
# List the 50 most recent runs
tessl review list --limit 50
# List runs for a specific workspace
tessl review list --workspace engteam
```
### tessl review retry
Re-run a failed review run.
**Usage**
```sh
tessl review retry [--json] [--workspace ] [--last] []
```
**Flags**
* `--json` (boolean, optional): Output as JSON
* `--workspace` / `-w` (string, optional): Workspace name or ID. Only applies with `--last`; an explicit review run ID already identifies its workspace.
* `--last` (boolean, optional): Retry the most recent review run
**Arguments**
* `id` (string, optional): Review run ID to retry. Provide an ID or use `--last`.
**Notes**
* `--workspace` is only accepted with `--last`; passing it alongside an explicit review run ID fails with a validation error
**Examples**
```sh
# Retry a specific review run
tessl review retry abc123
# Retry the most recent review run
tessl review retry --last
# Retry the most recent review run in a specific workspace
tessl review retry --last --workspace engteam
```
### tessl review fix
Improve a skill by running an automated review-and-fix loop server-side. Requires authentication and a workspace.
**Usage**
```sh
tessl review fix [--json] [--workspace WORKSPACE] [--threshold ] [--max-iterations ] [--yes] [--review-plugin ] []
```
**Flags**
* `--json` (boolean, optional): Output as JSON
* `--workspace` / `-w` (string, optional): Workspace name or ID
* `--threshold` (number, optional): Stop once a review scores at or above this percentage (0-100, default 90)
* `--max-iterations` (number, optional): Maximum improve→review iterations to attempt (1-10, default 3)
* `--yes` / `-y` (boolean, optional): Apply the improved skill without confirmation
* `--review-plugin` (string, optional): Reviewer plugin — a path to a local plugin directory, or a registry ref `workspace/plugin[@version]`. Requires a paid plan; on a Free organisation, passing this flag returns an upgrade error
**Arguments**
* `path` (string, optional): Path to a local skill file or skill directory. Defaults to current directory if omitted.
**Notes**
* Requires authentication; sign in with `tessl login` or set the `TESSL_TOKEN` API key in the environment
* `--workspace` is required when `--json` is set, since non-interactive runs cannot prompt for a workspace
* Runs an asynchronous improve→review loop, stopping early once `--threshold` is met
**Examples**
```sh
# Improve the skill in the current directory
tessl review fix --workspace engteam
# Improve until the score reaches 90%, up to 5 iterations
tessl review fix ./my-skill --workspace engteam --threshold 90 --max-iterations 5
# Apply improvements without a confirmation prompt
tessl review fix ./my-skill --workspace engteam --yes
```
***
## Plugin management
### tessl plugin new
Create a new plugin with an interactive wizard.
**Usage**
```sh
tessl plugin new [--name ] [--summary ] [--path ] [--rules ] [--rule-description ] [--workspace ] [--skill] [--skill-name ] [--skill-description ] [--install] [--public]
```
**Flags**
* `--name` (string, optional): plugin name in format `workspace/plugin-name`
* `--summary` (string, optional): Brief description of the plugin
* `--path` (string, optional): Directory path where plugin will be created
* `--rules` (string, optional): Include rule by name
* `--rule-description` (string, optional): Initial rule instructions to include in generated rule file
* `--workspace` (string, optional): Workspace for the plugin
* `--skill` (boolean, optional): Include a skill in the plugin
* `--skill-name` (string, optional): Skill name (implies `--skill`)
* `--skill-description` (string, optional): Skill description (required with `--skill` or `--skill-name`)
* `--install` (boolean, optional): Automatically install in the current repository
* `--public` (boolean, optional): Make plugin public (default: private)
**Notes**
* Creates a new plugin directory with a basic `.tessl-plugin/plugin.json` template
* If run without flags, launches an interactive wizard to guide you through plugin creation
* For non-interactive use, include at least one component with `--skill`, `--skill-name`, or `--rules`
* Use `--skill` or `--skill-name` to create a plugin with a skill component
**Examples**
```sh
# Interactive wizard mode
tessl plugin new
# Create a plugin with specific options
tessl plugin new --name myworkspace/my-skill --summary "My skill description" --path ./my-skill-plugin
# Create a plugin with a skill
tessl plugin new --name myworkspace/my-skill --skill --skill-name "my-skill" --skill-description "Description of my skill"
# Create and automatically install
tessl plugin new --name myworkspace/my-skill --install
```
### tessl plugin lint
Validate plugin structure and contents
**Usage**
```sh
tessl plugin lint []
```
**Arguments**
* `source` (string, optional): Path to the plugin directory to lint. Defaults to current directory if omitted.
### tessl plugin migrate
Migrate `tile.json` to `.tessl-plugin/plugin.json`.
**Usage**
```sh
tessl plugin migrate [--force] []
```
**Flags**
* `--force` (boolean, optional): Overwrite existing `.tessl-plugin/plugin.json`
**Arguments**
* `path` (string, optional): Path to plugin directory. Defaults to current directory if omitted.
### tessl plugin pack
Package a plugin into a .tgz file.
**Usage**
```sh
tessl plugin pack [--output path] []
```
**Flags**
* `--output` (string, optional): Output path for .tgz file. If omitted, uses the plugin name and version to create a file in your current directory.
**Arguments**
* `source` (string, optional): Path to plugin folder. Defaults to current directory if omitted.
### tessl plugin info
Show plugin details from the registry.
**Usage**
```sh
tessl plugin info []
```
**Arguments**
* `name-or-path` (string, optional): plugin name (`workspace/plugin[@version]`) or path to plugin directory. Defaults to current directory if omitted.
**Examples**
```sh
# Show info for plugin in current directory
tessl plugin info
# Show info for a specific plugin
tessl plugin info engteam/my-plugin
# Show info for a specific version
tessl plugin info engteam/my-plugin@1.0.0
```
### tessl plugin publish
Publish plugins to the Tessl registry. This command bundles skills, rules, documentation into a plugin.
**Usage**
```sh
tessl plugin publish [--dry-run] [--bump patch|minor|major] [--skip-evals] [--with-scenario-quality-check] [--workspace ] [--version ] [--verbose] []
```
**Flags**
* `--dry-run` (boolean, optional): Run all pre-publish checks without publishing
* `--bump` (string, optional): Auto-bump version if it already exists in the registry. Supported values: `patch`, `minor`, `major`
* `--skip-evals` (boolean, optional): Skip publishing eval scenarios from evals/ directory
* `--with-scenario-quality-check` (boolean, optional): Have the backend's LLM judge filter out misleading scenarios (low feasibility, rubric leakage, low value) from the publish-time eval run. Equivalent to `tessl eval run --quality-check` for the eval that runs as part of publishing.
* `--workspace` (string, optional): Workspace to publish under when the plugin manifest name is flat (no `workspace/` prefix)
* `--version` (string, optional): Version to publish when the plugin manifest omits one
* `--verbose` / `-v` (boolean, optional): Print every archived file with the reason it was included
**Arguments**
* `path` (string, optional): Path to the plugin directory to publish. Defaults to current directory if omitted.
**Examples**
```sh
# Publish a plugin from current directory
tessl plugin publish
# Publish a plugin from a specific directory
tessl plugin publish path/to/my/plugin
```
{% hint style="info" %}
Not sure what your published plugin's URL will look like? See [Workspaces](/reference/workspaces#how-workspaces-appear-in-the-registry) to learn how workspace and plugin names map to Registry URLs.
{% endhint %}
### tessl plugin unpublish
Unpublish plugins from the registry (within 2 days of publishing).
**Usage**
```sh
tessl plugin unpublish [--plugin ]
```
**Flags**
* `--plugin` (string, optional): plugin to unpublish in the format `workspace/plugin@version`. If omitted, you'll be prompted.
**Notes**
* Only available within 2 days of publishing
**Examples**
```sh
# Unpublish a specific plugin version
tessl plugin unpublish --plugin myworkspace/myplugin@1.0.0
# Interactive mode
tessl plugin unpublish
```
### tessl plugin archive
Archive plugins in the registry.
**Usage**
```sh
tessl plugin archive [--plugin ] --reason
```
**Flags**
* `--plugin` (string, optional): plugin to archive in the format `workspace/plugin` (archives all versions) or `workspace/plugin@version` (archives a single version)
* `--reason` (string, required): Reason for archiving the plugin
**Notes**
* Prevents new installations while preserving existing installations
**Examples**
```sh
# Archive a specific plugin version
tessl plugin archive --plugin engteam/myplugin@1.0.0 --reason "Deprecated in favor of v2"
# Archive all versions of a plugin
tessl plugin archive --plugin engteam/myplugin --reason "No longer maintained"
```
***
## Organization management
### tessl org list
List all organizations that you are a member of.
**Usage**
```sh
tessl org list
```
### tessl org usage
Show your Tessl credit usage.
**Usage**
```sh
tessl org usage [--org ] [--json]
```
**Flags**
* `--org` (string, optional): Organization name or ID. You are prompted when you belong to several.
* `--json` (boolean, optional): Output as JSON. The payload contains `plan` and `credits` fields.
**Examples**
```sh
# Show credit usage
tessl org usage
# Show usage for a specific organization
tessl org usage --org my-org
# Output as JSON
tessl org usage --json
```
***
## Workspace management
Workspaces enable you to create private collections of plugins that are restricted to yourself or your organization. You can control member access and permissions. To learn more, see [Distributing via registry](/distribute/distributing-via-registry).
### tessl workspace create
Create a new workspace.
**Usage**
```sh
tessl workspace create [--org ] []
```
**Flags**
* `--org` (string, optional): Organization name or ID to own the workspace. When omitted and you belong to several organizations, interactive terminals prompt you to pick one; noninteractive callers must pass `--org `.
**Arguments**
* `name` (string, optional): Name for the workspace. The name must be lowercase. If omitted, you'll be prompted.
**Examples**
```sh
# Create a workspace
tessl workspace create myworkspace
# Interactive creation
tessl workspace create
# Create a workspace in a specific organization
tessl workspace create --org 01935e2c-1234-5678-abcd-ef0123456789 engteam
```
### tessl workspace list
List all workspaces that you are a member of.
**Usage**
```sh
tessl workspace list [--has-publish-access]
```
**Flags**
* `--has-publish-access` (boolean, optional): Only show workspaces where you have permission to publish.
**Examples**
```sh
# List all workspaces you belong to
tessl workspace list
# List only workspaces you can publish to
tessl workspace list --has-publish-access
```
### tessl workspace delete
Delete an existing workspace.
**Usage**
```sh
tessl workspace delete []
```
**Arguments**
* `name` (string, optional): The name or ID of the workspace. If omitted, you'll be prompted.
**Examples**
```sh
# Delete a workspace
tessl workspace delete myworkspace
# Interactive deletion
tessl workspace delete
```
If a workspace has published a public plugin, deleting it permanently reserves its name: the name cannot be used again, in this organization or any other. To move a workspace between organizations, do not delete it. Email and we can move it for you after a review.
### tessl workspace add-member
Add a user to a workspace with specified permissions.
**Usage**
```sh
tessl workspace add-member [--workspace ] [--username ] [--role ]
```
**Flags**
* `--workspace` (string, optional): Name or ID of workspace
* `--username` (string, optional): Username or ID of user to add
* `--role` (string, optional): Role to assign. Supported values: `member`, `publisher`, `manager`, `owner`
See [Roles](/administrators/roles) for more information
**Examples**
```sh
# Add a user to the workspace with a member role
tessl workspace add-member --workspace myworkspace --username johnsmith --role member
# Add a user to the workspace with an owner role
tessl workspace add-member --workspace myworkspace --username janesmith --role owner
# Interactive mode (prompts for all fields)
tessl workspace add-member
```
### tessl workspace remove-member
Remove a user from a workspace.
**Usage**
```sh
tessl workspace remove-member [--workspace ] [--username ]
```
**Flags**
* `--workspace` (string, optional): Name or ID of workspace
* `--username` (string, optional): Username or ID of user to remove
**Examples**
```sh
# Remove a member
tessl workspace remove-member --workspace myworkspace --username johnsmith
# Interactive mode
tessl workspace remove-member
```
### tessl workspace list-members
List all members of a workspace.
**Usage**
```sh
tessl workspace list-members []
```
**Arguments**
* `name` (string, optional): The name or ID of the workspace. If omitted, you'll be prompted.
**Examples**
```sh
# List members of a workspace
tessl workspace list-members myworkspace
# Interactive mode
tessl workspace list-members
```
### tessl workspace archive
Archive a workspace. An archived workspace won't be available to publish to or read from, but can be unarchived later.
**Usage**
```sh
tessl workspace archive --reason []
```
**Flags**
* `--reason` (string, required): Reason for archiving the workspace
**Arguments**
* `name` (string, optional): The name or ID of the workspace. If omitted, you'll be prompted.
**Notes**
* Archiving is a safer alternative to deleting, as archived workspaces can be restored
* Use `tessl workspace unarchive` to restore an archived workspace
**Examples**
```sh
# Archive a workspace with a reason
tessl workspace archive --reason "deprecated" myworkspace
# Interactive mode
tessl workspace archive --reason "no longer in use"
```
### tessl workspace unarchive
Unarchive an archived workspace, making it active again.
**Usage**
```sh
tessl workspace unarchive
```
**Arguments**
* `name` (string, required): The name or ID of the workspace.
**Examples**
```sh
# Unarchive a workspace
tessl workspace unarchive myworkspace
```
***
## Configuration management
### tessl config get
Get a configuration value or show all configuration.
**Usage**
```sh
tessl config get []
```
**Arguments**
* `key` (string, optional): Configuration key to get. If omitted, shows all configuration.
**Examples**
```sh
# Show all configuration
tessl config get
# Get a specific configuration value
tessl config get shareUsageData
```
### tessl config set
Set a configuration value.
**Usage**
```sh
tessl config set
```
**Arguments**
* `key` (string, required): Configuration key to set. Supported values: `shareUsageData`, `termsAcceptedAt`, `evalDefaultModelNoticeShownAt`, `evalDefaultModelNoticeModel`, `agents`
* `value` (string, required): Configuration value to set
**Examples**
```sh
# Set a configuration value
tessl config set shareUsageData false
```
### tessl config list
List all configuration values.
**Usage**
```sh
tessl config list []
```
**Arguments**
* `key` (string, optional): Configuration key to list. If omitted, lists all configuration.
**Notes**
* Similar to `tessl config get` but specifically for listing configuration values
**Examples**
```sh
# List all configuration
tessl config list
# List a specific configuration key
tessl config list shareUsageData
```
### tessl config add
Add one or more values to a configuration array.
**Usage**
```sh
tessl config add ...
```
**Arguments**
* `key` (string, required): Configuration key for the array
* `value` (string, required, repeatable): One or more values to add to the array
**Notes**
* Use this command to add values to array-type configuration settings
* Can specify multiple values in a single command
**Examples**
```sh
# Add a single value to an array configuration
tessl config add agents cursor
# Add multiple values to an array configuration
tessl config add agents cursor claude-code
```
### tessl config remove
Remove a value from a configuration array.
**Usage**
```sh
tessl config remove
```
**Arguments**
* `key` (string, required): Configuration key for the array
* `value` (string, required): Value to remove from the array
**Notes**
* Use this command to remove values from array-type configuration settings
* Only removes the specified value, not the entire configuration key
**Examples**
```sh
# Remove a value from an array configuration
tessl config remove agents cursor
```
***
## Diagnostics and utilities
### tessl doctor
Run authentication and manifest diagnostics to troubleshoot issues.
**Usage**
```sh
tessl doctor [--json]
```
**Flags**
* `--json` (boolean, optional): Output diagnostics as JSON for programmatic processing
**Examples**
```sh
# Run diagnostics with human-readable output
tessl doctor
# Output diagnostics as JSON
tessl doctor --json
```
### tessl feedback
Send feedback to the Tessl team.
**Usage**
```sh
tessl feedback []
```
**Arguments**
* `message` (string, optional): Feedback message to send. If omitted, you'll be prompted interactively.
**Examples**
```sh
# Send feedback directly
tessl feedback "Great tool! Would love to see Python support."
# Interactive feedback
tessl feedback
```
***
## CLI self-management
### tessl cli update
Update the CLI to the latest or specified version.
**Usage**
```sh
tessl cli update [--target ] [--channel ] [--dry-run]
```
**Flags**
* `--target` / `-t` (string, optional): Target version to update to (example: v1.0.0)
* `--channel` / `-c` (string, optional): Release channel to switch to. Supported values: `latest`, `beta`
* `--dry-run` (boolean, optional): Show what would be run without executing the update
**Examples**
```sh
# Update to the latest version
tessl cli update
# Update to a specific version
tessl cli update --target v1.0.0
# Switch to the beta release channel
tessl cli update --channel beta
# Preview update without executing
tessl cli update --dry-run
```
***
## API key management
### tessl api-key create
Create an API key for a workspace.
**Usage**
```sh
tessl api-key create [--workspace ] [--name ] [--role ] [--expiry-date | --ttl ]
```
**Flags**
* `--workspace` (string, optional): Name or ID of workspace
* `--name` (string, optional): Name for the API key
* `--role` (string, optional): Role to assign. Supported values: `member`, `publisher`, `manager`, `owner`
* `--expiry-date` (string, optional): Expiry date in ISO 8601 format (example: 2027-12-31T00:00:00Z). Defaults to 30 days from creation
* `--ttl` (string, optional): Time until expiry as a positive whole number followed by `h` (hours), `d` (days), `w` (weeks), `mo` (30-day months), or `y` (365-day years), such as `3h`, `4w`, or `1y`. Minutes are not supported. Calculated using the local clock after interactive prompts, just before the creation request. Use either `--ttl` or `--expiry-date`. Without either flag, keys expire 30 days from creation
**Examples**
```sh
# Create an API key interactively
tessl api-key create
# Create an API key with all details specified
tessl api-key create --workspace engteam --name "ci-key" --role publisher --expiry-date 2027-12-31T00:00:00Z
# Create an API key that expires in four weeks
tessl api-key create --workspace engteam --name "ci-key" --role publisher --ttl 4w
```
### tessl api-key list
List API keys for a workspace.
**Usage**
```sh
tessl api-key list [--workspace ]
```
**Flags**
* `--workspace` (string, optional): Name or ID of workspace
**Examples**
```sh
# List API keys interactively
tessl api-key list
# List API keys for a specific workspace
tessl api-key list --workspace engteam
```
### tessl api-key delete
Delete an API key from a workspace.
**Usage**
```sh
tessl api-key delete [--workspace ] [--yes] []
```
**Flags**
* `--workspace` (string, optional): Name or ID of workspace
* `--yes` / `-y` (boolean, optional): Skip confirmation prompt and delete immediately
**Arguments**
* `api-key-id` (string, optional): ID of the API key to delete. If omitted, you'll be prompted.
**Examples**
```sh
# Delete an API key interactively
tessl api-key delete
# Delete a specific API key
tessl api-key delete --workspace engteam
```
***
## Environment management
An environment is a named, workspace-scoped set of variables that a scheduled run, a launch, or a cloud run executes inside. Its values are sealed and write-only: you can set and replace them, but never read them back. Use an environment to supply the GitHub token, API keys, and any other credentials a run needs.
For what belongs in an environment and how runs consume it, see [Environments](/automations/environments).
{% hint style="info" %}
`tessl env` is a short alias for `tessl environment`. A scheduled run cannot mint its own GitHub token, so include a `GITHUB_TOKEN` (or `GH_TOKEN`) in the environment for any schedule that checks out a repository or opens pull requests.
{% endhint %}
### tessl environment create
Create an environment for a workspace.
**Usage**
```sh
tessl environment create [--workspace ] [--env-file ] [--mcp-server ] [--github-access ] [--linear-access ]
```
**Arguments**
* `name` (string, required): Name for the environment.
**Flags**
* `--workspace` (string, optional): Name or ID of workspace.
* `--env-file` (string, optional): Path to a `.env` file with environment variables.
* `--mcp-server` (string, optional, repeatable): Name of a workspace MCP server to configure.
* `--github-access` (`none`, `read`, or `write`, optional): GitHub access granted to runs that use this environment. The default is `read`.
* `--linear-access` (`none`, `read`, or `write`, optional): Linear access granted to cloud launch runs that use this environment. The default is `none`.
`none` mints no GitHub credential, so the run must bring its own token. `read` can clone the repository but cannot push. `write` can push branches and open pull requests; a person remains responsible for reviewing the changes and deciding whether to merge them.
For Linear access, `none` injects no platform credential. `read` permits Linear queries, while `write` also permits mutations. An environment cannot grant `read` or `write` while defining a non-empty `LINEAR_TOKEN` or `LINEAR_API_URL`. Tools must use `LINEAR_TOKEN` for authorization and `LINEAR_API_URL` as the API base URL; a tool that ignores `LINEAR_API_URL` sends the run key to Linear, which rejects it.
**Examples**
```sh
# Create an environment and load its values from a .env file
tessl environment create production --env-file production.env
# Create an environment in a specific workspace
tessl environment create production --workspace engteam --env-file production.env
# Wire workspace MCP servers into the environment
tessl environment create production --env-file production.env --mcp-server linear --mcp-server slack
# Create an environment whose runs can push branches and open pull requests
tessl environment create production --env-file production.env --github-access write
# Create an environment whose cloud launch runs can read and write Linear
tessl environment create production --linear-access write
```
### tessl environment list
List environments for a workspace.
**Usage**
```sh
tessl environment list [--workspace ] [--json]
```
**Flags**
* `--workspace` (string, optional): Name or ID of workspace.
* `--json` (boolean, optional): Output as JSON.
**Examples**
```sh
# List environments in the resolved workspace
tessl environment list
# List environments in a specific workspace
tessl environment list --workspace engteam
# Output as JSON
tessl environment list --json
```
### tessl environment view
View metadata for an environment.
**Usage**
```sh
tessl environment view [--workspace ] [--json]
```
**Arguments**
* `name` (string, required): Name or ID of the environment to view.
**Flags**
* `--workspace` (string, optional): Name or ID of workspace.
* `--json` (boolean, optional): Output as JSON.
**Notes**
* This shows metadata only, such as the variable names, GitHub access, Linear access, and MCP servers wired in. Sealed values are write-only and are never returned.
**Examples**
```sh
# View an environment
tessl environment view production
# View an environment as JSON
tessl environment view production --json
```
### tessl environment update
Update an environment for a workspace.
**Usage**
```sh
tessl environment update [--workspace ] [--env-file ] [--mcp-server ] [--github-access ] [--linear-access ] [--clear-mcp-servers]
```
**Arguments**
* `name` (string, required): Name or ID of the environment to update.
**Flags**
* `--workspace` (string, optional): Name or ID of workspace.
* `--env-file` (string, optional): Path to a `.env` file with environment variables.
* `--mcp-server` (string, optional, repeatable): Name of a workspace MCP server to configure.
* `--github-access` (`none`, `read`, or `write`, optional): GitHub access granted to runs that use this environment.
* `--linear-access` (`none`, `read`, or `write`, optional): Linear access granted to cloud launch runs that use this environment.
* `--clear-mcp-servers` (boolean, optional): Remove all MCP servers wired into this environment.
`none` mints no GitHub credential, so the run must bring its own token. `read` can clone the repository but cannot push. `write` can push branches and open pull requests.
For Linear access, `none` injects no platform credential. `read` permits Linear queries, while `write` also permits mutations. An environment cannot grant `read` or `write` while defining a non-empty `LINEAR_TOKEN` or `LINEAR_API_URL`. Tools must use both injected variables: `LINEAR_TOKEN` for authorization and `LINEAR_API_URL` as the API base URL.
**Notes**
* `--env-file` is required unless at least one `--mcp-server`, `--github-access`, or `--linear-access` is provided. A metadata-only update with no `--env-file` changes just the metadata and leaves every stored value untouched. Passing `--env-file` replaces the sealed values instead: the env file becomes the complete set, so it must include every credential you want to keep.
* `--clear-mcp-servers` always requires `--env-file`, including when it is combined with `--github-access`, `--linear-access`, or `--mcp-server`, because clearing is treated as an update with no new MCP servers.
**Examples**
```sh
# Replace an environment's values from a .env file
tessl environment update production --env-file production.env
# Rewire which MCP servers the environment configures (stored values are kept)
tessl environment update production --mcp-server linear
# Allow runs to push branches and open pull requests (stored values are kept)
tessl environment update production --github-access write
# Allow cloud launch runs to read Linear (stored values are kept)
tessl environment update production --linear-access read
# Remove every MCP server from the environment (credentials are replaced by the env file — include every value to keep)
tessl environment update production --clear-mcp-servers --env-file production.env
```
### tessl environment delete
Delete an environment from a workspace.
**Usage**
```sh
tessl environment delete [--workspace ] [name]
```
**Arguments**
* `name` (string, optional): Name or ID of the environment to delete. You are prompted when it is omitted.
**Flags**
* `--workspace` (string, optional): Name or ID of workspace.
**Examples**
```sh
# Delete an environment
tessl environment delete staging
# Delete an environment from a specific workspace
tessl environment delete staging --workspace engteam
```
***
## Model Context Protocol (MCP)
### tessl mcp start
Start the Tessl MCP (Model Context Protocol) server for integration with AI coding agents.
**Usage**
```sh
tessl mcp start
```
### tessl mcp proxy
Bridge a coding agent to a workspace MCP server through the Tessl MCP gateway. Starts a stdio MCP proxy that forwards JSON-RPC messages to a workspace-registered upstream MCP server, authenticating to the gateway with your Tessl credentials (`tessl login`) or `TESSL_TOKEN`. See [MCP gateway](/reference/mcp-gateway) for how to register the upstream server and wire the proxy into an agent or plugin `.mcp.json`.
**Usage**
```sh
tessl mcp proxy /
```
**Arguments**
* `workspace/mcp` (string, required): Slug of the workspace and the MCP server registered in that workspace's gateway (for example `engteam/linear`).
**Authentication**
* **Interactive use** — sign in once with `tessl login`; the proxy reuses the same credentials.
* **CI or other non-interactive contexts** — set `TESSL_TOKEN` to a Tessl API key for the workspace. See [`tessl api-key create`](#tessl-api-key-create).
**Examples**
```sh
# Proxy to an MCP server named `linear` in the `engteam` workspace
tessl mcp proxy engteam/linear
```
***
## Repository
### tessl repo select-commits
Browse recent commits in a repository and select which ones to evaluate. Used as the first step in [generating codebase scenarios](/improving-your-skills/evaluate-skill-quality-using-scenarios#generate-scenarios-from-your-codebase).
{% hint style="info" %}
This command is not listed in `tessl --help` but works when invoked directly.
{% endhint %}
**Usage**
```sh
tessl repo select-commits [flags]
```
**Arguments**
* `org/repo` (string, required): Repository in `org/repo` format
**Flags**
* `--keyword` (string, optional): Filter by commit message keyword
* `--author` (string, optional): Filter by author name
* `--since` / `--until` (string, optional): Date range in YYYY-MM-DD format
* `--count` / `-n` (number, optional): Number of commits to show (1–100)
* `--workspace` / `-w` (string, optional): Required outside interactive mode
* `--json` (boolean, optional): Output as JSON
**Prerequisite:** your GitHub or GitLab account must be connected in workspace settings. If it isn't, the error message includes a direct link to the settings page.
**Examples**
```sh
# Browse recent commits
$ tessl repo select-commits org/repo
# Filter by keyword and date range
$ tessl repo select-commits org/repo --keyword=feat --since=2026-01-01
# Show last 50 commits by a specific author
$ tessl repo select-commits org/repo --author="Alice" --count=50
```
***
## GitHub integration
Tessl Helper is a GitHub App your workspace installs. These commands mint short-lived installation tokens so CI steps and coding agents can act as the Tessl Helper bot without holding the App's private key.
A workspace can reach the Tessl Helper App on more than one GitHub account. Pass `--repo owner/name` to say which: the owner selects the installation to mint from, and the repository names limit what the token can reach. Without it, the most recently updated installation is used, which may not be the one that owns the repositories you want.
### tessl github token
Mint a short-lived GitHub installation token for the Tessl Helper bot and print it to stdout.
**Usage**
```sh
$ tessl github token [--workspace ] [--repo ]...
```
**Flags**
* `--workspace` (string, optional): Name or ID of workspace
* `--repo` (string, optional, repeatable): Scope the token to a repository and select its installation by owner, in `owner/name` form. All values must share one owner, since a token is minted against a single installation.
**Notes**
* The token is written to stdout so it can be captured directly, for example `GH_TOKEN=$(tessl github token ...)`. The expiry is written to stderr, so it does not pollute that capture.
* The minted token is a GitHub App installation token, not a user token. Installation-scoped endpoints such as `/installation/repositories` work; user-scoped endpoints such as `gh org list` fail.
* Without `--repo`, the token covers everything the selected installation can reach.
**Examples**
```sh
# Mint a token scoped to one repository
$ tessl github token --workspace engteam --repo my-org/my-repo
# Scope to several repositories owned by the same account
$ tessl github token --workspace engteam --repo my-org/api --repo my-org/web
# Capture the token for a single command
$ GH_TOKEN=$(tessl github token --workspace engteam --repo my-org/my-repo) gh api /installation/repositories
```
### tessl github setup-auth
Configure `gh` and `git` on this machine to act as the Tessl Helper bot, so subsequent commands authenticate without a token in the environment.
**Usage**
```sh
$ tessl github setup-auth [--workspace ] [--repo ]... [--force] [--auto-refresh] [--refresh-interval-seconds ]
```
**Flags**
* `--workspace` (string, optional): Name or ID of workspace
* `--repo` (string, optional, repeatable): Scope the token to a repository and select its installation by owner, in `owner/name` form. All values must share one owner.
* `--force` (boolean, optional): Overwrite an existing `gh`/`git` auth configuration. Without it, the command stops rather than replacing one already in place.
* `--auto-refresh` (boolean, optional): Spawn a background process that re-mints the token periodically, for steps that outlive a single token.
* `--refresh-interval-seconds` (number, optional): How often that background process re-mints, in seconds. Defaults to 2700, which is 45 minutes.
**Notes**
* Signs in `gh` and sets a global git identity for the bot. This persists after the command exits, so prefer an ephemeral runner or container.
* Refuses to run when `gh` is already signed in or a global git identity is already set. Use `--force` to replace them.
* Clear `GH_TOKEN` and `GITHUB_TOKEN` first. `gh` prefers a token in the environment over the credential this writes.
* Without `--auto-refresh` the credential lasts until the expiry the command prints.
* With `--repo`, refreshes re-mint against the same owner and repositories. Without it, each refresh picks the most recently updated installation.
**Examples**
```sh
# Authenticate for one repository
$ tessl github setup-auth --workspace engteam --repo my-org/my-repo
# Long-running CI step, refreshing in the background
$ tessl github setup-auth --workspace engteam --repo my-org/my-repo --auto-refresh
# Replace an existing gh/git configuration
$ tessl github setup-auth --workspace engteam --repo my-org/my-repo --force
```
***
## Inventory
### tessl inventory import
Scan a GitHub account or org for installed skills and upload an inventory. Forked repos are skipped.
**Usage**
```sh
tessl inventory import [--org ] [--workspace ] [--repo ]... [--ignore-repo ]... [--dry-run ]
```
**Flags**
* `--org` (string, optional): GitHub account or org to scan. Prompted if omitted.
* `--workspace` (string, optional): Name or ID of workspace to upload to. Prompted if omitted.
* `--repo` (string, repeatable, optional): Limit scan to this repo (repeatable)
* `--ignore-repo` (string, repeatable, optional): Exclude this repo from the scan (repeatable)
* `--dry-run` (string, optional): Write inventory JSON to the given path instead of uploading
**Notes**
* `--org` and `--workspace` are prompted when omitted in interactive sessions, but required as flags in non-interactive environments (including with `--dry-run`)
**Examples**
```sh
# Scan an org and upload to a workspace
tessl inventory import --org my-github-org --workspace engteam
# Limit the scan to specific repositories
tessl inventory import --org my-github-org --workspace engteam --repo repo-a --repo repo-b
# Preview the inventory without uploading
tessl inventory import --org my-github-org --workspace engteam --dry-run ./inventory.json
```
***
## Scenario management
{% hint style="warning" %}
Scenario management and evals are in public beta. Workflows and output formats may change in upcoming releases.
{% endhint %}
Scenario commands generate and manage eval scenarios from real repository commits. For a full walkthrough, see [Prove a skill works using evaluation](/improving-your-skills/evaluate-skill-quality-using-scenarios).
### tessl scenario generate
Generate eval scenarios from a plugin or repository commits. Runs server-side — the CLI polls until complete. Ctrl-C detaches without cancelling; check progress with `tessl scenario list`.
**Alias:** `tessl scenarios generate`
**Usage**
```sh
tessl scenario generate [--commits ] [--prs ] [--count ] [--workspace ] [--context ] [--json] [--no-wait]
```
**Arguments**
* `source` (string, required): plugin path or `org/repo` to generate scenarios from
**Flags**
* `--commits` (string, optional): Comma-separated commit hashes to generate scenarios from (repo only)
* `--prs` (string, optional): Comma-separated PR numbers to resolve as commit ranges (repo only)
* `--count` / `-n` (number, optional): Number of new scenarios to add (plugin only)
* `--context` (string, optional): Glob patterns for context files to exclude from baseline, comma-separated (repo only). These patterns are stored in each generated `scenario.json` as `fixture.exclude` — they are stripped for the baseline eval variant and injected back for the with-context variant. Defaults to `*.mdc`, `*.md`, `tile.json`, `.tessl-plugin/plugin.json`, `tessl.json`, `.tessl/` when omitted.
* `--workspace` / `-w` (string, optional): Workspace name or ID (repo only). Required outside interactive mode.
* `--json` (boolean, optional): Output as JSON
* `--wait` / `--no-wait` (boolean, optional): Wait for the generation to finish before returning (default: wait when interactive; a non-interactive run, such as CI, submits and returns without waiting; use `--no-wait` to force that anywhere, then reconnect with `tessl scenario view`). `--json` on its own also detaches; pass `--wait --json` to poll to completion and still get JSON.
**Examples**
```sh
# Generate scenarios for two commits
$ tessl scenario generate org/repo --commits=abc123,def456
# Generate scenarios from PRs
$ tessl scenario generate org/repo --prs=42,43
# Generate scenarios from a plugin
$ tessl scenario generate ./my-plugin --count=5
# Specify context file patterns
$ tessl scenario generate org/repo --commits=abc123 --context="*.mdc,*.md"
# Non-interactive with workspace
$ tessl scenario generate org/repo --commits=abc123 --workspace=engteam
```
### tessl scenario list
List recent scenario generation runs in reverse chronological order.
**Alias:** `tessl scenarios list`
**Usage**
```sh
tessl scenario list [--mine] [--workspace ] [--limit ] [--status ] [--json]
```
**Flags**
* `--mine` (boolean, optional): Only show generation runs created by you
* `--workspace` / `-w` (string, optional): Filter by workspace name
* `--limit` (number, optional): Maximum number of runs to display (default: 20)
* `--status` (string, optional): Filter by status. Supported values: `pending`, `in_progress`, `completed`, `failed`
* `--json` (boolean, optional): Output as JSON
### tessl scenario view
Inspect a scenario generation run. Shows run metadata and a table of generated scenarios with titles and checklist item counts.
**Alias:** `tessl scenarios view`
**Usage**
```sh
tessl scenario view [--last] [--json] []
```
**Flags**
* `--last` (boolean, optional): View the most recent generation run
* `--json` (boolean, optional): Output as JSON
**Arguments**
* `id` (string, optional): Generation run ID. Either `id` or `--last` is required.
**Examples**
```sh
# View the most recent generation run
$ tessl scenario view --last
# View a specific run
$ tessl scenario view 019c4791-9eec-7458-b28a-6c94405a3d38
```
### tessl scenario download
Download generated scenarios to your local `evals/` folder.
**Alias:** `tessl scenarios download`
**Usage**
```sh
tessl scenario download [--output ] [--strategy ] [--json] [--last] ...
```
**Flags**
* `--output` / `-o` (string, optional): Output directory (default: `evals`)
* `--strategy` / `-s` (string, optional): Write strategy: `merge` (default) adds new scenarios alongside existing ones; `replace` clears the directory first
* `--json` (boolean, optional): Output as JSON
* `--last` (boolean, optional): Download from the most recent generation run
**Arguments**
* `id` (string, required, repeatable): Generation IDs to download. Can specify multiple IDs. Either `id` or `--last` is required.
If the generation run is still in progress or pending, the command reports the status and exits.
**Downloaded structure:**
```
evals/
<7-char-hash>-/
task.md ← task brief shown to the agent
criteria.json ← weighted checklist rubric
scenario.json ← fixture with repo URL, commit ref, and context exclude patterns
```
**Examples**
```sh
# Download from the most recent generation run
$ tessl scenario download --last
# Download to a custom directory, replacing existing scenarios
$ tessl scenario download --last --output=my-evals --strategy=replace
# Download a specific run
$ tessl scenario download 019c4791-9eec-7458-b28a-6c94405a3d38
```
***
## Evaluations
For more information on workflows and usage, see [Prove a skill works using evaluation](/improving-your-skills/evaluate-skill-quality-using-scenarios).
### tessl eval run
Run evals from a scenarios directory. The context under test, if any, comes from `--context`; with no context, the run is the baseline variant alone (see Notes).
* **Codebase eval**: source directory contains `scenario.json` fixtures → runs with smart defaults (agent `claude`, model `deepseek-v4.1-flash`, context pattern from `fixture.exclude`, context ref `infer`)
* **Plugin eval** — source contains `.tessl-plugin/plugin.json` → runs the plugin's own evals. Pass the plugin root directory (the directory that contains `.tessl-plugin/`, not `.tessl-plugin/` itself).
Pointing at a plugin directory is shorthand: `tessl eval run ./my-plugin` expands to `tessl eval run ./my-plugin/evals --context ./my-plugin` — the plugin's `evals/` as the scenarios, the plugin itself as the context. An explicit `--context` opts out of the shorthand.
**Usage**
```sh
tessl eval run [--agent ] [--model ] [--scorer-agent ] [--scorer-model ] [--context ] [--context-commit ] [--skill ]... [--skip-baseline] [--variant-json ] [--allow-unsafe-fixture-paths] [--runs ] [--label
%20(1)%20(1).png?alt=media)
%20(1)%20(1).png?alt=media)
.png?alt=media)
.png?alt=media)
.png?alt=media)
.png?alt=media)
.png?alt=media)
.png?alt=media)
%20(1).png?alt=media)
%20(1).png?alt=media)
%20(1).png?alt=media)
%20(1).png?alt=media)
.png)
.png?alt=media)
%20(1).png?alt=media)
%20(1).png?alt=media)
%20(1).png?alt=media)
.png?alt=media)
%20(1).png?alt=media)
* Select which repositories the pull request will be created in.
%20(1).png?alt=media)
%20(1).png?alt=media)
%20(1).png?alt=media)
.png?alt=media)
.png?alt=media)
.png?alt=media)
.png?alt=media)
