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.
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.
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 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:
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 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 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 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; to write one from scratch, use the create-code-review-lens skill in the same 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
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.
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.
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
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.
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.
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 <name>, 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
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. Usehooksfor the portable path that works across agents, andnativeHooksto pass agent-specific config straight through when you need the escape hatch.Five generic events.
PreToolUse,PostToolUse,UserPromptSubmit,SessionStart, andStop. Amatchernarrows 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.
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.
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
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 <percent> 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
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/<hash>-<slug>/ with a task.md, a criteria.json, and a scenario.json.
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.
Last updated