#Create a skill

A skill teaches an agent how to do one thing: a workflow, a convention, a piece of specialized knowledge. It is agent-agnostic, so the skill you write here works across every agent Tessl supports, adapted to each on install. This page covers scaffolding a skill, writing it, and checking it is well formed. Improving how well it performs is a separate step, covered in Improving your skills, and sharing it is covered in Publish and update.

#Prerequisites

• The Tessl CLI installed (see Installation).
• A logged-in session (tessl login), or a TESSL_TOKEN in the environment.
• A workspace to attribute your work to. Examples use engteam as a stand-in; run tessl workspace list to see yours and use one of those instead.

#Scaffold the skill

tessl skill new creates a new skill and its .tessl-plugin/plugin.json manifest. Run it with no flags for an interactive wizard:

tessl skill new

Or pass flags to scaffold it directly:

tessl skill new --name database-migration-helper --description "When you need to create and manage database migrations" --workspace engteam --path ./database-migration-helper

#Import an existing skill

If you already have a SKILL.md, tessl skill import generates the .tessl-plugin/plugin.json around it so it becomes an installable skill:

tessl skill import ./database-migration-helper --workspace engteam

Pass --public to make it public, or --force to overwrite an existing manifest.

my-repo/
├── .tessl-plugin/
│   └── plugin.json
├── skills/
│   ├── database-migration-helper/
│   │   └── SKILL.md
│   └── seed-data-helper/
│       └── SKILL.md
└── evals/

{
  "name": "engteam/my-repo",
  "version": "0.1.0",
  "description": "Database workflows for our services",
  "private": true,
  "skills": "./skills/"
}

#Write the SKILL.md

A skill follows the Agent Skills specification. The file is named SKILL.md: YAML frontmatter, then a Markdown body.

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

# Database migration helper

When creating a new migration:

1. Always include both `up` and `down` migrations.
2. Use a transaction where the engine supports it.
3. Test the migration on a copy of production data first.

## Example: adding a column

    -- Up
    ALTER TABLE users ADD COLUMN email_verified BOOLEAN DEFAULT FALSE;

    -- Down
    ALTER TABLE users DROP COLUMN email_verified;

## Best practices

- Never modify a migration that has already run in production.
- Keep migrations small and focused.

Two parts do the work:

• description (frontmatter) is how an agent discovers the skill. State what it does and when to use it. A vague description is the most common reason a skill never fires.
• The body is the instructions the agent follows once loaded. Keep it concise and actionable; push long reference material into a references/ folder beside the SKILL.md.

#Understand the package structure

tessl skill new creates a Tessl package: your skill plus a manifest that makes it installable.

database-migration-helper/
├── .tessl-plugin/plugin.json
└── skills/database-migration-helper/SKILL.md

The manifest holds the package metadata:

{
  "name": "engteam/database-migration-helper",
  "version": "1.0.0",
  "description": "Create and manage database migrations",
  "private": true
}

You rarely edit this by hand, except to bump version. The full reference is in Configuration files.

#Validate

Lint checks the structure and frontmatter against the Agent Skills specification:

tessl skill lint ./database-migration-helper

Fix any errors it reports before moving on. Then, for a scored review of how well the skill is written, run tessl review and read the result:

tessl review run ./database-migration-helper --workspace engteam

Reviewing and improving are covered in full in Check a skill's quality using review.

#Next

• Create a plugin - bundle this skill with others, or add rules and an MCP server.
• Prove a skill works using evaluation - measure whether it improves the agent's output.
• Publish and update - share it with your team or publicly.