Tessl Skill Review

Enforce agent skill quality in your CI. The bot reviews every SKILL.md changed in a PR, scores it, and posts inline suggestions the author can accept with one click.

What you'll see when a PR changes a SKILL.md

• A summary comment with a quality score and a per-dimension review of the skill
• Inline suggestion blocks on the Files Changed tab — click Commit suggestion to accept changes one at a time, or use Add suggestion to batch to combine several into one commit
• /apply-optimize (per skill or for the whole PR) as a one-shot way to take all changes via the bot

Setup

1. Get a Tessl API token and add it as a repository secret named TESSL_API_TOKEN.

2. Add .github/workflows/skill-review.yml:

   name: Tessl Skill Review
   on:
     pull_request:
       paths: ['**/SKILL.md']
     issue_comment:
       types: [created]
   
   jobs:
     review:
       if: github.event_name == 'pull_request'
       runs-on: ubuntu-latest
       permissions:
         pull-requests: write
         contents: read
       steps:
         - uses: actions/checkout@v4
         - uses: tesslio/skill-review-and-optimize@7b2383f98ce4d2ba281a9a1d573a9f82390ad7db
           with:
             optimize: true
             inline-suggestions: true
             tessl-token: ${{ secrets.TESSL_API_TOKEN }}
   
     apply:
       if: >
         github.event_name == 'issue_comment' &&
         github.event.issue.pull_request &&
         contains(github.event.comment.body, '/apply-optimize') &&
         contains(fromJSON('["OWNER","MEMBER","COLLABORATOR"]'), github.event.comment.author_association)
       runs-on: ubuntu-latest
       permissions:
         pull-requests: write
         contents: write
       steps:
         - uses: actions/checkout@v4
           with:
             fetch-depth: 0
         - uses: tesslio/skill-review-and-optimize@7b2383f98ce4d2ba281a9a1d573a9f82390ad7db
           with:
             mode: apply

That's it. Open a PR that changes a SKILL.md and the bot will comment.

To pin the Tessl CLI version used for review runs, add cli-version to the review step:

- uses: tesslio/skill-review-and-optimize@7b2383f98ce4d2ba281a9a1d573a9f82390ad7db
  with:
    cli-version: 0.73.0

Omit cli-version to keep using the latest Tessl CLI. Set it to a specific version when you need reproducible runs or a short rollout delay for new CLI releases.

The CLI is only installed for mode: review; /apply-optimize does not need the Tessl CLI.

⚠️ First-time setup gotcha — /apply-optimize won't work on the PR that introduces this workflow. GitHub reads issue_comment workflows from your default branch only, never from a PR branch. So the very first time you add this file, you need to land it on main (typically by merging the PR that added it) before /apply-optimize fires on any PR. After that, it works on every future PR. The review side (the summary comment + inline suggestions) is unaffected — it works from the PR branch on the very first run.

The pinned SHA (@e7b9c0…) keeps your workflow reproducible. Bump it from the tags page when you intentionally upgrade.

Already wired this up as two separate workflows (skill-review.yml + apply-optimize.yml) from an earlier setup? No migration needed — both patterns work identically. The single-file workflow above is just simpler to copy from scratch.

Optional: block PRs below a quality threshold

Add fail-threshold to the review job to fail the check when a skill scores below your minimum:

- uses: tesslio/skill-review-and-optimize@7b2383f98ce4d2ba281a9a1d573a9f82390ad7db
  with:
    optimize: true
    inline-suggestions: true
    fail-threshold: 70
    tessl-token: ${{ secrets.TESSL_API_TOKEN }}

When optimize: true, the threshold is checked against the post-optimize achievable score. So skills the optimizer can lift above the threshold pass the check — the user has a one-click /apply-optimize path to merge. Skills even the optimizer can't lift fail (genuine quality issue).

Inputs reference

Input	Description	Default
tessl-token	Tessl API token. Required for optimize: true. Get one here.	(required for optimize)
optimize	Run AI-powered optimization after review	false
inline-suggestions	Post inline suggestion blocks on the PR file diff	false
fail-threshold	Minimum score (0-100) to pass the check. 0 = never fail.	0
optimize-iterations	Max optimization iterations (1-10)	3
cli-version	Tessl CLI version to install, for example 0.73.0 or latest	latest
mode	review (default) or apply (used by the /apply-optimize job)	review
path	Root path to search for SKILL.md files (for monorepos)	.
comment	Whether to post the summary comment	true
re-review-on-suggestion-acceptance	Re-run review after a Commit suggestion accept. Set false to skip those runs and keep the original review comment.	true

Optional: skip re-review when a suggestion is accepted

With inline-suggestions: true, every Commit suggestion click pushes a new commit and re-fires the workflow — by default the action re-reviews and posts a fresh summary. Set re-review-on-suggestion-acceptance: false to detect those commits (GitHub-signed web-flow committer + either Apply suggestions from code review for batch accepts or Update <path> with a Co-authored-by: trailer for single accepts) and exit early, leaving the original review in place. Plain web edits (the pencil "Edit this file" button), /apply-optimize, and ordinary human pushes still trigger a review.

- uses: tesslio/skill-review-and-optimize@7b2383f98ce4d2ba281a9a1d573a9f82390ad7db
  with:
    optimize: true
    inline-suggestions: true
    re-review-on-suggestion-acceptance: false
    tessl-token: ${{ secrets.TESSL_API_TOKEN }}

How it works

1. Detects which SKILL.md files changed in the PR
2. Runs tessl skill review on each one for a quality score
3. If optimize: true, runs the optimizer to suggest improvements (requires tessl-token)
4. Posts (or updates) a single summary comment per PR with the score and per-dimension review
5. If inline-suggestions: true, also posts a single batched PR review with one inline suggestion block per diff hunk; prior bot suggestions are cleaned up before each new run
6. If fail-threshold is set, fails the check when the post-optimize achievable score is below threshold
7. When a repo collaborator comments /apply-optimize, the apply job extracts the optimized content from the summary comment and commits it to the PR branch

Local development

bun install
bun run lint
bun test

License

MIT