> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Create a skill

:::info

**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](/improving-your-skills/overview-improving-skills-and-plugins.md), and sharing it is covered in [Publish and update](/creating-skills-and-plugins/publish-and-update.md).

:::info

Your agent can do all of this for you. Install Tessl's plugin creator with `tessl install tessl/plugin-creator`, or use Tessl Agent, which ships with those skills built in.

:::

## Prerequisites

- The Tessl CLI installed (see [Installation](/introduction-to-tessl/installation.md)).
- 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:

```bash
tessl skill new
```

Or pass flags to scaffold it directly:

```bash
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:

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

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

:::warning

**`skill import` handles one skill.** It writes `.tessl-plugin/plugin.json` inside the skill folder with `"skills": ["."]`, so that folder becomes the plugin root, and its `evals/` go there too.

If your repository has several skills, do not run `skill import` for each one. That makes one plugin per skill. Create one plugin at the repository root instead, and point its `skills` field at the folder that holds the skills:

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

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

When the skills sit in `./skills/`, you can leave out the `skills` field: Tessl finds them by convention. To list specific skill folders, give an array, for example `"skills": ["./skills/database-migration-helper", "./skills/seed-data-helper"]`. See [Configuration files](/reference/configuration.md) for the field reference.

:::

## Write the SKILL.md

A skill follows the [Agent Skills specification](https://agentskills.io/specification). The file is named `SKILL.md`: YAML frontmatter, then a Markdown body.

```markdown
---
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:

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

| Field         | Meaning                                                                                |
| ------------- | -------------------------------------------------------------------------------------- |
| `name`        | `workspace/name`. Its identity on the registry.                                        |
| `version`     | Semantic version ([semver](https://semver.org/)). 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](/reference/configuration.md).

## Validate

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

```bash
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:

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

Reviewing and improving are covered in full in [Check a skill's quality using review](/improving-your-skills/reviewing-skills.md).

## Next

- [Create a plugin](/creating-skills-and-plugins/create-a-plugin.md) - bundle this skill with others, or add rules and an MCP server.
- [Prove a skill works using evaluation](/improving-your-skills/evaluate-skill-quality-using-scenarios.md) - measure whether it improves the agent's output.
- [Publish and update](/creating-skills-and-plugins/publish-and-update.md) - share it with your team or publicly.