> 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 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 gate for every merge candidate. **Ask your agent** Install the setup plugin, then ask for the setup you want: ```sh tessl install tessl/code-review-setup ``` "Set up Tessl Code Review for this repository. Start in advisory mode and review a pull request when it becomes ready." **You provide** Two policy choices: * when reviews run: manually, when a pull request becomes ready, or on every commit; * whether findings are advisory or gate merging. The recommended starting point is one review when the pull request becomes ready, plus requested rounds after fixes or replies, in advisory mode. **Under the hood** The setup writes a thin GitHub Actions workflow that invokes `tesslio/code-review-action` at its major tag, `@v1`, or at a release's full commit SHA if you ask for the revision frozen. The workflow owns triggers, permissions, concurrency, the repository secret, and who may request a review by mention. The Action owns safe checkout, Tessl CLI setup, deciding whether a comment requested a review, the check run it reports on the reviewed head, and artifacts. The CLI it installs runs the review and publishes it. Either Action reference fixes the Action rather than the CLI, which tracks its current release unless the workflow sets the `cli-version` input. **What to expect** A `.github/workflows/tessl-code-review.yml` file, a request to add the `TESSL_TOKEN` repository secret, and a summary of the chosen cadence and mode. The Action publishes **Changes approved** or **Changes requested (N)**, with findings anchored to files and lines where possible. Read [Set up Tessl Code Review](/tutorials/setting-up-agentic-code-review.md) for the complete workflow, gate configuration, security boundaries, and troubleshooting.
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.1.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 [`tessl/code-review-lens-creator`](https://tessl.io/registry/tessl/code-review-lens-creator) 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** ``` 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-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="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.