# Tessl Docs > Documentation for the Tessl platform. ## Overview - [What is Tessl?](/index.md) ## Introduction to Tessl - [Set up Tessl](/introduction-to-tessl/set-up-tessl.md): Takeaway: By the end of this page you will have a Tessl account, the CLI installed and authenticated, and Tessl initialized in a project. That is everything you need before running your first workflow. To set up a factory that turns GitHub issues into pull requests, you don't need the CLI. See Build your first factory. Tessl helps you manage the skills and context your coding agents rely on. You work with it through the tessl command line tool, so setup comes down to three things: install the CLI, create an account, and initialize a project. It takes a few minutes. - [Installation](/introduction-to-tessl/installation.md): A step-by-step guide on how to install, update or remove the Tessl CLI. - [Build your first factory](/introduction-to-tessl/build-your-first-factory.md): Set up a Tessl factory on a GitHub repository in the web app, hand it one issue, and review and merge the pull request it opens. - [Improve your first skill](/introduction-to-tessl/improve-your-first-skill.md): Takeaway: You will connect an SCM account, explore your Organization's Context and Findings, improve a local skill, run an eval that measures the skill's effect, and publish a new version your team can install. This is the end-to-end loop you will repeat with Tessl: see what context your Organization has, find what needs attention, make it better, measure the effect with an eval, and ship it. A few terms show up along the way, namely skills, plugins, Organizations, workspaces, reviews, and evals. You can follow every step without reading ahead; each term links to a fuller explanation in Core concepts. As a quick orientation: an Organization owns SCM connections and reporting, a workspace controls private publishing, and a project ties Tessl to a single repository. - [Core concepts](/introduction-to-tessl/core-concepts.md): Takeaway: Understand the building blocks of Tessl, namely the kinds of context, how they are packaged, where they live, and how Tessl measures quality, so the rest of the docs make sense. If you have worked through the getting started flow, you have already used most of these ideas. This page names them and explains how they fit together. ## Tutorials - [Overview](/tutorials.md): End-to-end walkthroughs for the most common agentic-development workflows on Tessl. - [Using Tessl as a package manager](/tutorials/using-tessl-as-a-package-manager.md): Use Tessl as a package manager for agent context: find and install skills, keep them up to date, and publish your own to a workspace. - [Protecting yourself from insecure skills](/tutorials/protecting-against-insecure-skills.md): Inspect skills across your Organization, read their Snyk-powered security scores, and use install policies to block risky skills before they reach a developer. - [Codifying and enforcing your company's skill standards](/tutorials/codifying-and-enforcing-skill-standards.md): Capture your team's quality bar as a custom review rubric and enforce it on every skill in CI. - [Improving a skill](/tutorials/improving-a-skill.md): Use reviews and evals to measure a skill's impact, find what's holding it back, and ship an improvement with evidence. - [Cutting agent cost with a skill](/tutorials/cutting-agent-cost-with-a-skill.md): Use evals to find where an agent spends tokens working things out, write a skill that answers those questions up front, and measure the cost per task before and after. - [Set up Tessl Code Review](/tutorials/setting-up-agentic-code-review.md): Install the Tessl Review GitHub App, enable a repository, choose when reviews run, ask for a review by comment, and configure lenses with .tessl-code-review.yml. - [Run Code Review with GitLab](/tutorials/code-review-in-gitlab.md): Review GitLab merge requests locally or integrate the Tessl CLI into your own GitLab CI pipeline. - [Running Code Review in your own GitHub CI](/reference/code-review-action.md): Unsupported. Inputs and outputs of the tesslio/code-review-action GitHub Action, kept for people who cannot install the Tessl Review GitHub App. - [Set up Vulnerability Remediation](/tutorials/vulnerability-remediation.md): Turn on Vulnerability Remediation in Tessl Reviewer, connect a scanner, ask for a run by comment, and read what it fixed, suggested, or left for you. - [Improving agent code quality](/tutorials/improving-agent-code-quality.md): Turn recurring agent mistakes into fixes. Mine PRs and session logs with the Tessl Agent, then prove the fix with evals. - [Automating repetitive tasks](/tutorials/automating-repetitive-tasks.md): Identify repetitive work in your development loop and turn it into repeatable, automated workflows with the Tessl Agent. ## Automations - [Automations overview](/automations/overview.md): How a Tessl factory is built: loops that run an action when an event, a schedule, or a person starts them. Declare them in tessl.json or set them up in Tessl. - [Learn from past work](/automations/learn-from-past-work.md): Turn on Learn from past work so Tessl records the problems your agents keep hitting as findings, then triage those findings into tickets your factory builds. - [Stop, remove, and move loops](/automations/stop-and-change-loops.md): Pause, resume, remove, and move each kind of loop, cancel a run already in progress, and turn off Code Review, with a read-back for every step. - [Troubleshoot factory runs](/automations/troubleshooting-factory-runs.md): Find out why a factory run never started, failed, or stopped to wait for you, with one check and one next step for each stage from the event to the pull request. - [Schedules](/schedules/overview.md): No CI setup, no GitHub Actions config. Declare a schedule in your tessl.json, push to your default branch, and Tessl runs it for you. - [Validate schedules in CI](/schedules/validate-in-ci.md): Add tessl schedule validation to your continuous integration workflow. - [Example Schedules](/automations/overview/example-schedules.md): The following are examples of schedules you can get started with easily. use-case-docs-audit.md use-case-changelog.md use-case-review-miner.md use-case-test-health.md use-case-release-check.md - [Keep docs in sync](/automations/overview/example-schedules/use-case-docs-audit.md): Keep your docs in sync with your code, automatically. A scheduled docs audit checks whether the docs still match the code and opens a PR when they have drifted. - [Weekly changelog](/automations/overview/example-schedules/use-case-changelog.md): Get a changelog draft every week without anyone remembering to write it. A scheduled changelog writer scans the week's merged PRs and opens a PR with the draft. - [Review pattern mining](/automations/overview/example-schedules/use-case-review-miner.md): Stop repeating the same code-review comment. A scheduled review miner reads recent reviews, finds the feedback that keeps coming up, and proposes a lint rule for it. - [Test health monitor](/automations/overview/example-schedules/use-case-test-health.md): Catch flaky tests before everyone learns to ignore them. A scheduled test health monitor finds flaky or repeatedly failing tests and files a ticket for each one. - [Release readiness check](/automations/overview/example-schedules/use-case-release-check.md): Find release problems while there is still time to fix them. A scheduled release check verifies migrations, feature flags, the changelog, and the docs before each release window. - [Best practices for Tessl Factory on public repositories](/automations/factory-on-public-repositories.md): Use this guide before allowing Factory to work on a public GitHub repository, or before making an existing Factory repository public. You'll choose who can hand work to Factory, limit the access its agents receive, and require a person to approve code before merging. Factory turns issues into pull requests and follows up on them using agents that read discussion, execute commands, and push code. Public issues, comments, and files can contain malicious instructions. The steps below reduce that risk, including when a trusted maintainer starts the work. - [Environments](/schedules/environments.md): A named set of secrets and configuration a loop can use. Store API keys and credentials here. - [Cloud setup hook](/automations/cloud-setup-hook.md): Install your repository's dependencies before each loop run and cloud launch with .tessl/cloud-launch-setup.sh, and check the hook on a branch before you merge it. ## Administrators - [Administrating Organizations, Workspaces, and Roles](/administrators/administrating-organizations-workspaces-and-roles.md) - [Roles](/administrators/roles.md): Organization and workspace roles and their permissions - [Least privilege for environments](/administrators/least-privilege-environments.md): Configure organization environments, secrets, MCP servers, and the Linear connection so each run gets the least access it needs. - [Using the EU region](/administrators/eu-region.md): Set up the Tessl CLI for an organization using the EU region. - [SSO](/administrators/sso.md) ## Use - [Using the Tessl agent](/guides/use/using-the-tessl-agent.md): Six things teams use the agent for, the way you'd actually ask for each one, the command it runs underneath, and what you should see back. - [Enhance your workflow with skills](/guides/use/enhance-your-workflow-with-skills.md): Learn how to discover and install skills that enhance your agent's capabilities with procedural workflows - [Migrating from tiles to plugins](/guides/use/tile-to-plugin-migration.md): Guide for migrating from the legacy tile.json format to the new plugin format - [Understand your organization's context](/use/understand-your-skill-estate.md): How to connect an SCM account so Tessl scans your repositories and shows your Organization's Context and Findings. ## Creating skills and plugins - [Overview](/creating-skills-and-plugins/overview.md): Create a skill or a plugin - the packaged, versioned context you share with your team and your agents. - [Create a skill](/creating-skills-and-plugins/create-a-skill.md): Scaffold a skill, write its SKILL.md, and validate it before you share it. - [Create a plugin](/creating-skills-and-plugins/create-a-plugin.md): Bundle skills, rules, and commands into one versioned plugin, and choose what each piece should be. - [Add an MCP server](/creating-skills-and-plugins/add-an-mcp-server.md): Ship an MCP server inside a plugin to give the agent live tools or data, not just instructions. - [Develop and test locally](/creating-skills-and-plugins/develop-and-test-locally.md): Install a plugin straight from your filesystem so you can test and iterate before publishing. - [Publish and update](/creating-skills-and-plugins/publish-and-update.md): Publish a skill or plugin to the registry, control who can install it, and ship new versions. ## Improving your skills - [Overview](/improving-your-skills/overview-improving-skills-and-plugins.md): This page is the place to start if you want to improve a skill. It walks through the two ways Tessl assesses skill quality, review and evaluation, and how you use each to make a skill better. A review and an evaluation answer different questions. - [Check a skill's quality using review](/improving-your-skills/reviewing-skills.md): Run a review to score how well a skill is written, read the result, and apply fixes. - [Migrate from skill review to Tessl Review](/improving-your-skills/migrate-from-skill-review.md): How to switch from the removed tessl skill review to Tessl Review, and what to expect - [Prove a skill works using evaluation](/improving-your-skills/evaluate-skill-quality-using-scenarios.md): Generate scenarios, run an evaluation, and read the score difference to see whether a skill actually changes what an agent produces. - [Compare with test variants](/improving-your-skills/comparing-with-test-variants.md): Compare models, agents, skill revisions, and context using test variants, with examples of how to interpret the results. - [Read evaluation results](/improving-your-skills/reading-evaluation-results.md): View evaluation results, compare scores and costs, and understand variation and missing data. - [Troubleshooting reviews and evaluations](/improving-your-skills/troubleshooting-reviews-and-evals.md): Most problems with reviews and evaluations come down to a few causes. Work through these when something does not behave as expected. ## Codifying and enforcing your skill standards - [Overview](/codifying-and-enforcing/overview.md): Gate skill quality automatically and define your organisation's standard for what a good skill looks like. - [Verifiers overview](/codifying-and-enforcing/verifiers-overview.md): Use verifiers to check committed files against repository-specific invariants that a linter cannot express. - [Verify agent changes in CI](/codifying-and-enforcing/verify-agent-changes-in-ci.md): Write and calibrate a verifier, then run it as an advisory or blocking check on pull requests. - [Gate skill quality in CI](/codifying-and-enforcing/gate-skill-quality-in-ci.md): Run a review on every pull request and fail the build when a skill scores below your threshold. - [Define your own quality standards](/codifying-and-enforcing/define-your-own-quality-standards.md): Fork the default review rubric to encode your organisation's quality bar, then apply it to every review. ## Distribute - [Distributing via registry](/guides/distribute/distributing-via-registry.md): Distribute, share, and maintain plugins through the Tessl Registry - [Sharing with your team and publicly](/guides/distribute/sharing-plugins-publicly.md): Making your plugins publicly discoverable in the Tessl Registry - [Permissions](/guides/distribute/rollout-to-your-repositories/permissions.md): The following permissions are required to configure and use Tessl with your repositories. - [Connect Tessl to GitHub](/guides/distribute/rollout-to-your-repositories/connect-tessl-to-github.md): Connect a GitHub account or organization so Tessl can scan its repositories and report Context and Findings in your Organization. - [Connect Tessl to GitLab](/guides/distribute/rollout-to-your-repositories/connect-tessl-to-gitlab.md): To enable Tessl on your repositories, you will first navigate to the Tessl Registry and login, if required. - [Initialize a repository](/guides/distribute/rollout-to-your-repositories/initialize-a-repository.md): Using Setup on the Repositories view in Tessl Registry creates a tessl.json file and adds any plugins Tessl has for the dependencies your repository uses. It also creates a .mcp.json file so people working in the repository can use Tessl as an MCP server for their coding agent. - [Distribute plugins across multiple repositories](/guides/distribute/rollout-to-your-repositories/distribute-plugins-across-multiple-repositories.md): The Tessl web interface allows users, with the correct permissions, to create pull requests adding plugins to selected repositories. The following workflow demonstrates distributing a plugin that has guidelines that must be followed by the agents that company is using. This could include style guides, architecture and other guidelines that you now want to push across your organization. Before you start, make sure your repositories are connected to Tessl and you have the required permissions: Connect Tessl to GitHub or Connect Tessl to GitLabInitialize a repository if it has not been set up with Tessl yet To distribute a plugin, follow these steps: Navigate to the workspace your plugin resides in.Click Rollout next to the plugin you wish to push.
Indicate the Tessl workspace to roll the plugin out to.Select which repositories the pull request will be created in.
To complete the action, click Create a rollout PR.By doing this it will create a pull request adding the plugin to the tessl.json. A .tessl-plugin/plugin.json will be created if Tessl has not been initialized for that repository. An option to view the PR will be displayed:
The PR will then be merged by you or your pipeline automations. - [Removing the integration](/guides/distribute/rollout-to-your-repositories/removing-the-integration.md) - [Using plugins directly from your repo](/guides/distribute/repository-plugins.md): Use plugins directly from your repository for codebase-specific context - [Promote or claim a skill you have created](/distribute/promote-or-claim-a-skill-you-have-created.md): Have you authored a skill in GitHub and want to promote it using Tessl? Tessl allows you to take a skill from a local repository or GitHub repository, and generate the plugin.json, which is essential for Tessl plugins and Skills. Once imported, you will publish the plugin to make it available, publicly or privately, to your teams. The following section discusses organization of your skills and how to publish them. Additionally if you have authored a plugin on GitHub that appears in Tessl, there is a section on claiming that skill in Tessl. - [Review, lint & publish with GitHub Actions](/distribute/review-and-publish-with-github-actions.md): The following steps introduce the GitHub action to your repository. This action sets up tessl so it can be used for any CI/CD use case, such as auto-publishing plugins, linting or running skill reviews on PRs, etc. If you're migrating your skill into Tessl's registry, using the GitHub action will automatically link your plugin to the repository, and all skills we previously indexed in the repository will be hidden and redirected to the plugins.See Tessl's setup-tessl GitHub action for additional options and information. Create your workflow Create your workflow file in .github/workflows for your desired action. For example, here's how you'd set up an auto-publish action. Create an API Key Log into Tessl on web UI. Open your workspace, navigate to Settings, then API keys. Create a new API key. Copy the value as it will only be shown once. Add your API Key as a Repository Secret In GitHub, navigate to your repo Settings, select Secrets and variables, under actions find New Repository Secret. Provide the name: TESSL_TOKEN and the value is the Tessl API key you procured in the earlier step. Run your workflow Kick off your workflow by running the relevant trigger, or manually triggering from the UI if you enabled that in your workflow definition. ## Projects - [Overview](/projects/overview.md): Understand what Tessl projects are and why we need them. - [Manage projects from the CLI](/projects/manage-projects-from-the-cli.md): Set up and repair project links from the Tessl CLI. - [Repairing projects](/projects/repairing-projects.md): Understand how to diagnose and fix issues with projects. - [Projects in the app](/projects/projects-in-the-app.md): Browse projects, follow factory work from an issue to its run and pull request, and read factory metrics in the Tessl app. ## Reference - [CLI commands](/reference/cli-commands.md): The Tessl CLI provides commands for managing plugins, workspaces, authentication, repository configuration, and Tessl projects. This page provides a comprehensive reference for all available commands. - [Configuration files](/reference/configuration.md) - [Skill schemas](/reference/skill-schemas.md): How a launchable skill declares typed input and output JSON Schemas, how `$ref`s are resolved, and the structured result a cloud launch returns. - [Custom agent setup](/reference/custom-agent-setup.md): For agent setup, perform the following steps: Run tessl init from your project root first. Auto-detected agents (Cursor, Claude, Gemini, Copilot, Codex) need no further configuration. You can skip the rest of these steps and start your agent to validate it's configured. MCP configurationSetup rulesAccept running Tessl - [OpenCode](/reference/custom-agent-setup/opencode.md) - [OpenClaw](/reference/custom-agent-setup/openclaw.md): OpenClaw OpenClaw is an autonomous AI agent framework with its own workspace and skills system. Tessl integrates with OpenClaw by installing skills directly into an agent workspace — no MCP configuration or rules files are used, to keep config clean. How skills work with OpenClaw Tessl installs skills as symlinks into the skills/ directory of your OpenClaw agent workspace. OpenClaw reads skills from this directory automatically. Skills installed by Tessl are prefixed with tessl__ so they can be identified and managed separately from your other skills, if necessary. Installing skills Navigate to your agent workspace directory before running tessl install. A workspace is identified by the presence of a .openclaw/workspace-state.json file. If you run tessl install from anywhere other than a workspace root, Tessl will exit with an error and suggest the correct directories to navigate to. Multiple agents If you have more than one OpenClaw agent, run tessl install separately from each workspace: Installing for coding agents at the same time If your OpenClaw agent uses coding agents (Claude Code, Codex, etc.), use the --agent flag to control which agents receive skills: With no --agent flag, Tessl auto-detects which agents are present in the workspace directory, and installs for all of them. Using tessl init tessl init is not supported in OpenClaw workspaces. If you run it from a workspace root, Tessl will exit with an error and prompt you to run tessl install instead. - [Workspaces](/reference/workspaces.md): Overview of creating and managing Tessl workspaces - [MCP tools](/reference/mcp-tools.md): Overview of Tessl MCP tools for AI coding agents. - [MCP gateway](/reference/mcp-gateway.md): Register an external MCP server for your organization, understand which runs and people can reach it, and connect to a workspace server with `tessl mcp proxy`. - [GitHub badges](/reference/github-badges.md): Using GitHub badges is a great way to share your skill and show a score! - [Glossary](/reference/glossary.md): Key concepts and terminology used throughout Tessl. ## Support - [FAQs](/support/faqs.md): Find quick answers to the most common questions about Tessl. - [Giving feedback](/support/giving-feedback.md): Contact us You can get in touch with us if you need some help via the following methods: Email - support@tessl.ioDiscord - #tessl-product, a channel where you can quickly reach the teamGitHub Issues - tesslio/cliCLI - run tessl feedback in your command line to quickly send notes straight to the team! We really appreciate all feedback you have to give - brief, detailed, complimentary or critical - it helps us to improve. - [Supported platforms](/reference/supported-platforms.md): This page lists the supported version. Even if your favorite platform is not listed, it might still work as we support many industry standards. - [Troubleshooting](/reference/troubleshooting.md): The Tessl CLI provides diagnostic capabilities through the tessl doctor command that outputs information about the environment and the CLI itself. This information can be helpful to support and in diagnosing issues. Additionally the CLI will provide guidance on how to resolve issues that are detected. The CLI output defaults to human readable output and can be configured to output JSON for reporting automation. Usage Flags --json (boolean, optional): Output diagnostics as JSON for programmatic processing Examples - [CLI Changelog](/changelog-cli.md): Latest version = 0.119.0 - [Web Changelog](/changelog-web.md): Release notes for the Web and API surfaces. ## LEGAL - [Sharing Usage Data](/legal/sharing-usage-data.md): Tessl is committed to our users’ privacy, and protecting your data is our top priority. The nature of Tessl’s product requires it to see and participate in AI exchanges, and that may include sensitive and precious data. We take great care to earn the trust of handling such data, and want to be clear and transparent to our users about this. Opt out of sharing telemetry and usage data Tessl collects telemetry and usage data from its CLI and cloud service usage, and uses this to improve product quality, guide roadmap priorities and troubleshoot user issues. This may include conversations, code snippets and file contents used to guide Tessl actions. All data is encrypted at rest and well protected, and you can ask to delete this data at any time. You can easily opt out of data collection at any time by following the steps here. Doing so will ensure Tessl doesn't see your data for local actions, and doesn't persist it for cloud data. Opting out will not disable or hinder your AI usage, but may make it harder to troubleshoot issues with support. Tessl collaborates with highly trusted cloud LLM providers Tessl partners with the top AI labs to service our users. We take great care to only use providers with a strong security posture, and while we pass some data to those services as part of our product’s operation, we do not grant those partners any rights to your data. The most notable partners we work closely with are OpenAI, Anthropic and Google. Tessl uses your data to make our products better for you The sole purpose of data collection is to understand you, our users, and improve our products for you. We do not sell or monetize your data, and have absolutely no intent to do so. We reserve the right to train on data collected from our free tier usage, but have never done so to date. Instead, we focus our AI tuning on public data and purposely created synthetic data sets. If you have any questions or feedback, please email us at privacy@tessl.io. We may agree to custom enterprise terms for usage data on a case by case basis - please contact us to discuss this at legal@tessl.io. For more information on how we collect, use, disclose and process your personal data, see our full Privacy & Cookie Policy - [Open Source Attribution](/legal/open-source-attribution.md): The Tessl Registry has been enriched by insights from many open source projects. While no code has been copied, we acknowledge the broader open source community whose work has inspired and informed these specs. All licenses and rights remain with the original project contributors.