> 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/tutorials/improving-agent-code-quality.md). # Improving agent code quality {% 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"). **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 PR time before they accumulate into patterns by [Setting up agentic code review](/tutorials/setting-up-agentic-code-review.md) with `tessl change review` and `tessl change verify`. * Discover other manual workflows in your repository that can be automated with the [Automating repetitive tasks](/tutorials/automating-repetitive-tasks.md) tutorial and the `find-automations` skill. --- # 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/tutorials/improving-agent-code-quality.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.