Quick start: package manager for context

Install Tessl, create a skill, evaluate it, and publish it to your workspace

This guide walks you through the core Tessl workflow: install the CLI, create or install a skill that teaches your agent a procedure, evaluate its quality, and publish it to your team to share.

What you need:

• An AI coding agent (Claude Code, Cursor, Gemini, Codex, Copilot CLI, Copilot in VSCode, etc.)

Step 1: Install Tessl

Native Install

curl -fsSL https://get.tessl.io | sh

Homebrew

npm (deprecated)

See detailed installation instructions for more options.

Log in and initialize Tessl in your project:

$ tessl login
$ mkdir my-project && cd my-project
$ tessl init

If you don't already have a Tessl account (sign up here), you'll be prompted to create one at login.

tessl init creates a tessl.json manifest and configures your coding agent for MCP support (auto-detects Claude Code, Cursor, Gemini, Codex, Copilot CLI, Copilot in VSCode). See custom agent setup for manual configuration.

Step 2: Install or create a skill

Skills are procedural guides that teach your agent how to perform specific workflows. They activate automatically when relevant - your agent loads them when the task matches the skill's description.

Option A: Install a skill from the registry

Browse available skills:

$ tessl search "database migration"

Or install a skill directly by name:

$ tessl install tessl-labs/api-design-patterns

Your agent now has access to the skill and will follow the skill procedure when the task matches.

Option B: Create your own skill

Create a new skill with the interactive wizard:

$ tessl skill new

This creates a directory with a SKILL.md file:

my-skill/
├── tile.json
└── SKILL.md

Edit SKILL.md to define your skill:

---
name: database-migration-helper
description: When you need to create and manage database migrations.
---

# Database Migration Helper

## Creating a Migration

When creating a new migration:

1. Always include both `up` and `down` migrations
2. Use transactions when possible
3. Test migrations on a copy of production data first

## Best Practices

- Never modify existing migrations that have been applied to production
- Always test rollbacks
- Keep migrations small and focused

Key fields:

• name: The skill identifier (lowercase, hyphens only)

• description: When the skill should activate — this is what agents use to decide when to load it, so make it specific

To test locally before publishing, install the skill from its local path:

$ tessl install file:./my-skill

Ask your agent to perform a task that matches the skill's description and verify it follows the procedure.

Step 3: Evaluate the skill

Tessl provides two complementary ways to evaluate a skill: reviews check your skill against structural best practices, and scenario evals measure how much the skill improves agent performance on real tasks.

Review: validate against best practices

Check the skill's format and structure:

$ tessl skill lint ./my-skill

For a scored quality review:

$ tessl skill review ./my-skill

The review produces three scores:

• Validation — structural checks: frontmatter, format, line count

• Implementation — quality of the skill body: conciseness, actionability, workflow clarity

• Activation — quality of the description: how likely agents are to load the skill at the right time

Example output:

$ tessl skill review ./my-skill

Validation Checks

  ✔ frontmatter_valid - YAML frontmatter is valid
  ✔ name_field - 'name' field is valid: 'database-migration-helper'
  ✔ description_field - 'description' field is valid
  ✔ body_present - SKILL.md body is present
  ✔ body_steps - Step-by-step structure detected

Overall: PASSED (0 errors, 0 warnings)

Judge Evaluation

  Description: 72%
  Content: 85%

Average Score: 78%

Aim for a score above 70% before publishing. Use the suggestions in the output to improve your skill. If you trust the suggestions and want to auto-apply them, run:

$ tessl skill review ./my-skill --optimize

To optimize your skill against the improvements.

Scenario evals: measure agent performance

Scenario evals run your agent on tasks with and without the skill injected, so you can see exactly how much the skill improves performance.

Generate scenarios from your skill: First create a workspace, if you haven't already:

$ tessl workspace create <name>

Then generate scenarios from your skill. Scenarios are the tasks that agents are assessed against.

$ tessl scenario generate ./my-skill --count=5 --workspace=engteam

Generation runs server-side. Check progress and download when complete:

$ tessl scenario list --mine
$ tessl scenario download --last
$ mv ./evals/ ./my-skill/evals/

Run the evaluation:

$ tessl eval run ./my-skill

To run against a specific model:

$ tessl eval run ./my-skill --agent=claude:claude-sonnet-4-6

You'll receive a URL in the terminal to monitor progress and view results in the Tessl web UI.

Review the results:

$ tessl eval list
$ tessl eval view --last

Results show how the agent performed on each scenario with and without the skill. If a scenario fails, adjust the scenario or retry:

$ tessl eval retry <id>

To compare your skill across Haiku, Sonnet, and Opus in one guided flow, install the model comparison skill:

$ tessl install tessl-labs/review-model-performance

Then ask your agent: "Run model comparison evals"

Step 4: Publish the skill

Once your skill passes review and evals, publish it to your workspace:

$ tessl skill publish ./my-skill --workspace engteam

Skills are published as private by default — only members of your workspace can install them. To share with your team:

$ tessl workspace add-member --username <tessl-username> --role member --workspace engteam

Team members can then install the skill in any project:

$ tessl install engteam/my-skill

A review runs automatically on publish and the score appears in the Tessl Registry.

Publishing updates: When you update the skill, increment the version in tile.json (following semver) and republish:

$ tessl skill publish ./my-skill --workspace engteam

Team members get the latest version by running tessl install engteam/my-skill again.

Explore more

Creating skills

Review a skill against best practices

Evaluate skill quality using scenarios

Distributing via registry