> For the complete documentation index, see [llms.txt](https://docs.tessl.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.tessl.io/use/using-the-tessl-agent.md).
# Using the Tessl agent
## 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 build a skill inventory."
**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**
A snapshot of your whole skill estate: what exists, where it lives, who last touched it, and which skills are near-duplicates of each other. Run it again any time. Each scan is diffed against the last, so you get a living view of what's new, unchanged, and removed.
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
Skills are the unit of review knowledge. Any skill can act as a review lens, and one call can run several in parallel and interlace their findings into a single review.
Try a code review locally
USE WHEN Start on a diff you already understand, so you can judge the output before automating it.
**Ask your agent**
"Do a code review on my current diff using the code-legibility lens."
**You provide**
One `--skill` per lens you want, repeatable. The diff is read from your working tree, so add `--base` only to compare against something other than `main`.
**Under the hood**
```
tessl change review \
--skill tessl/code-review#review-code-legibility
```
Repeat `--skill` to run several lenses at once. Add `--json --output review.json` to capture the data.
**What to expect**
High-confidence findings anchored to specific files and lines, from every lens you passed, interlaced into one structured review. Lenses run in parallel, so two lenses cost roughly the wall-clock time of one.
The `--skill` flag takes a registry ref `workspace/plugin[@version]#skill-name`, a local path to a `SKILL.md` or skill directory, or the bare name of an installed skill.
{% hint style="warning" %}
**Heads up:** this command emits review data and never posts to GitHub. Wiring it into PRs needs a workflow plus a separate publisher step. Pass `--base` explicitly too: a detached PR checkout usually has no `origin/main` tracking ref, and without it the default base can't be resolved and the run fails.
{% endhint %}
The six lenses that ship with the agent
| Lens in `tessl/code-review` | Reach for it when the signal that matters most is |
| ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `review-functional-correctness` | Runtime bugs, regressions, data integrity, accessibility, or workflow breakage. The broadest lens. |
| `review-contract-boundaries` | API schemas, generated clients, CLI flags, event payloads, or database migrations that can break an existing consumer. |
| `review-security-risks` | Auth, untrusted input, injection, secrets, crypto, or sensitive logging. Complements CodeQL, Snyk, and Dependabot rather than repeating them. |
| `review-test-risk` | Changed behavior with no meaningful test, a fix with no regression test, or brittle tests asserting implementation trivia. |
| `review-code-legibility` | Whether names, types, return shapes, and abstractions are clear to a reader with no prior context. |
| `review-local-precedent` | Whether new code should have reused an existing helper, component, or convention instead of reimplementing it. |
Review every new PR automatically
USE WHEN You spend too much time on PR review and want a first pass before a human looks.
**Ask your agent**
"Set up automated PR review for this repo."
**Under the hood**
Built-in `change-review` skill
Creates a GitHub Actions workflow that runs `tessl change review` on every PR and posts findings as inline comments.
**What to expect**
A workflow file committed to the repo. The review runs on every new PR and posts structured findings as inline GitHub comments anchored to the relevant lines.
Gate the PRs that need a human
USE WHEN You want merges blocked only when a change is genuinely risky, from a policy you own.
**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**
```
tessl change risk init
tessl change risk --base origin/main \
--fail-if-review-required --json
```
Combines deterministic git measurements with an advisory agent judgment, then a deterministic gate decision.
**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**
```
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 --git`
`--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` → `--dry-run --all --show-files` → `--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-tesslov2` 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="warning" %}
**Heads up:** scenarios must sit in an `evals/` directory inside the plugin root, but `scenario download` writes relative to your current directory. Either run it from the plugin root or pass `--output /evals`. Evals also need at least `publisher` access; `member` is enough to run a review but not an eval.
{% endhint %}
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.tessl.io/use/using-the-tessl-agent.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.