> 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 organization's own quality bar. * How to apply a custom reviewer consistently across local reviews and CI. * How to scale your standard from per-run flags to organization and workspace policy. {% 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 organization 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 6. Set organization and workspace policy so your standard applies by default ## Prerequisites * Tessl installed and initialized (`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 organization'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, or set your reviewer as the workspace default so every review in that workspace uses your standard without the flag. The next step covers how that default fits into wider policy. ## Step 6: Set policy across your organization The steps so far enforce your standard one run at a time: a threshold on a command, a reviewer flag you pass, a CI job you maintain. Policy is how that standard scales beyond a single run, so it applies by default across an organization or a workspace without anyone having to remember a flag. Policy is set in the app under `Settings → Policy`. Setting organization-level policy is an organization admin action, so if you do not see it, ask your admin. ### Organization-level policy An **organization** is the top-level entity, and policy set there applies to every workspace and project inside it. This is where you set a single standard for the whole company, so a workspace inherits it by default rather than starting from nothing. For a security admin, this is the broadest and most impactful control. ### Workspace-level scoping Each **workspace** inherits the organization policy and can tighten it for its own skills. A workspace can raise the bar above the organization default, but it cannot loosen what the organization sets: lower levels only tighten, never relax, and when levels disagree the strictest one wins. Projects can tighten a workspace policy further in the same way. This lets a stricter team hold a higher bar without weakening the company-wide floor. The workspace default reviewer is a separate workspace setting, configured under `Settings → Reviews` rather than in the policy editor. As covered in Step 5, setting it means every review in that workspace applies your rubric without passing `--review-plugin`. For more on reviewer defaults, see [Define your own quality standards](/codifying-and-enforcing-your-skill-standards/define-your-own-quality-standards.md). ### Public-skill controls Publishing skills publicly is controlled at both levels. An organization can block public publishing across all its workspaces, and an individual workspace can block it for itself. A workspace can only add restriction, so when the organization blocks public publishing, a workspace cannot re-enable it. To let only some workspaces publish public skills, leave public publishing allowed at the organization level and block it in each workspace that must stay private. ### Install gating An install policy stops a skill that fails your security bar from being installed at all. It gates on the Snyk-powered security score, not the review quality score: choose the severity at which an install is warned and the severity at which it is blocked, so a skill that meets the block threshold is refused with the offending finding shown and no override. You can also restrict installs by source and require a minimum release age for git sources. For the full walkthrough of install policy, see [Protecting yourself from insecure skills](/tutorials/protecting-against-insecure-skills.md). {% hint style="info" %} Install and publish gating act on the security score, not the review quality score. To hold a quality line, gate on the review score in CI with `--threshold` as shown in Steps 1 to 3. The two work together: security policy controls what can enter and leave your registry, and the CI threshold holds the quality bar on every pull request. {% endhint %} ## Next steps * [Gate skill quality in CI](/codifying-and-enforcing-your-skill-standards/gate-skill-quality-in-ci.md) - full reference for `--threshold`, `--json`, and `tessl api-key create`. * [Define your own quality standards](/codifying-and-enforcing-your-skill-standards/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.