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 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.
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
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
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.
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.
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
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.
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 --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 <name>, 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
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.
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 <plugin-root>/evals. Evals also need at least publisher access; member is enough to run a review but not an eval.
Last updated