Create a skill

Scaffold a skill, write its SKILL.md, and validate it before you share it.

Takeaway A skill is a folder with a SKILL.md, packaged as a minimal plugin so you can version and share it. Scaffold one with tessl skill new, write a clear SKILL.md, and validate it with tessl skill lint and tessl review.

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.

All the steps on this page are also available through your agent. Install Tessl's plugin creator to scaffold, structure, and validate skills without leaving your editor: tessl install tessl/plugin-creator

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

Flag	Purpose
--name	Skill name, lowercase with hyphens.
--description	When the skill should trigger. This is what an agent reads to decide whether to load the skill, so make it specific.
--workspace	Workspace for the skill. Defaults to local.
--path	Directory to create the skill in.
--install	Install it into the current project immediately, so you can test it as you write.
--public	Make it public. Private by default.

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.

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,
  "skills": "skills/database-migration-helper"
}

Field	Meaning
name	workspace/name. Its identity on the registry.
version	Semantic version (semver). Bump it on each release.
description	Short summary shown on the registry.
private	true keeps it to your workspace; public is irreversible once published.
skills	Path, or array of paths, to your skill directories. Defaults to ./skills if omitted.

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.