> 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/codifying-and-enforcing-skill-standards.md). # Codifying and enforcing your company's skill standards {% hint style="info" %} **Takeaways** * How to gate pull requests on a review score using `--threshold`. * How to authenticate CI with an API key so reviews run without manual login. * How to fork the default rubric to encode your organisation's own quality bar. * How to apply a custom reviewer consistently across local reviews and CI. {% endhint %} When a team shares skills, quality stops being a personal matter. A weak skill that one person tolerates becomes everyone's problem once it is in the shared repository, shaping how every agent on the team behaves. This tutorial shows you how to hold a quality line automatically, first by setting a score threshold that blocks substandard skills from merging, and then by forking the default rubric to encode what your organisation actually cares about. ## The core workflow 1. Run `tessl review run --threshold` locally to confirm the score gate works 2. Create an API key and add it as a CI secret so reviews can run non-interactively 3. Add a review step to your pull request workflow 4. Install `tessl/review-plugin-creator` and build a custom reviewer plugin 5. Apply the custom reviewer via `--review-plugin` in local reviews and CI ## Prerequisites * Tessl installed and initialised (`tessl init`) * Authenticated (`tessl login`) * A workspace to attribute reviews to * A GitHub repository with Actions enabled (for the CI steps) ## Step 1: Test the threshold locally Before wiring anything into CI, confirm the score gate behaves as expected: ```bash tessl review run ./my-skill --workspace --threshold 80 ``` `--threshold` takes a 0-100 integer. The command exits non-zero when the score falls below it, which is what fails a CI step. The default is 0, which never fails. Any value above 0 enforces the gate. Add `--json` when you need machine-readable output in a script that parses the result: ```bash tessl review run ./my-skill --workspace --json --threshold 80 ``` `--workspace` is required when `--json` is set, because a non-interactive run cannot prompt for one. ## Step 2: Authenticate CI A review runs against your workspace, so CI needs to authenticate without an interactive login. Create an API key for the workspace: ```bash tessl api-key create --workspace ``` Copy the key and add it as a repository secret named `TESSL_TOKEN` in your GitHub repository settings (**Settings → Secrets and variables → Actions → New repository secret**). ## Step 3: Add the review step to CI Tessl publishes a GitHub Action that installs the CLI. Add a job to your pull request workflow: ```yaml name: Skill review on: pull_request: jobs: review: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: tesslio/setup-tessl@v2 with: token: ${{ secrets.TESSL_TOKEN }} - name: Review skill run: tessl review run ./my-skill --workspace --json --threshold 80 ``` The step fails when the score falls below 80. Adjust the path, workspace, and threshold to match your repository. For a full reference of flags and options, see [Review, lint & publish with GitHub Actions](/distribute/review-and-publish-with-github-actions.md). ## Step 4: Build a custom reviewer The default rubric scores against general best practices. To score against your organisation's own standards, build a custom reviewer plugin with the `create-review-plugin` skill: ```bash tessl install tessl/review-plugin-creator ``` Ask your agent to create a reviewer. It scaffolds the plugin structure, helps you define judges and their weights, writes the rubric files, and validates the finished plugin by running a test review. A reviewer plugin is a standard Tessl plugin. Its key components are a `config.json` that sets the weight each judge contributes to the score, and one rubric file per judge that defines the scoring dimensions. The weights across validation and all judges must sum to 1.0. The default rubric is worth forking rather than building from scratch. It scores a skill's description on specificity, completeness, trigger term quality, and distinctiveness, and the content on conciseness, actionability, workflow clarity, and progressive disclosure. Forking lets you adjust those weights or add judges for concerns specific to your team. ## Step 5: Apply the custom reviewer Point any review at your reviewer with `--review-plugin`, passing a local path or a `workspace/plugin` registry reference: ```bash tessl review run ./my-skill --workspace --review-plugin ``` The same flag works in `tessl review fix` and in your CI gate, so the standard you define in the rubric is the standard you enforce everywhere: ```bash tessl review run ./my-skill --workspace --review-plugin --json --threshold 80 ``` Pass `--review-plugin` explicitly on each run. There is no workspace-level default; passing the flag consistently is how you apply your standard. ## Next steps * [Gate skill quality in CI](https://github.com/tesslio/monorepo/blob/main/apps/docs/codifying-and-enforcing/gate-skill-quality-in-ci.md) - full reference for `--threshold`, `--json`, and `tessl api-key create`. * [Define your own quality standards](https://github.com/tesslio/monorepo/blob/main/apps/docs/codifying-and-enforcing/define-your-own-quality-standards.md) - deeper coverage of reviewer plugin structure and the weight invariant. * [Review, lint & publish with GitHub Actions](/distribute/review-and-publish-with-github-actions.md) - complete GitHub Actions workflow for skill CI. --- # 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/codifying-and-enforcing-skill-standards.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.