> For the complete documentation index, see [llms.txt](https://docs.tessl.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.tessl.io/creating-skills-and-plugins/create-a-skill.md). # Create a skill {% hint style="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`. {% endhint %} 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). {% hint style="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. {% endhint %} ## Prerequisites * The Tessl CLI installed (see [Installation](/introduction-to-tessl/set-up-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. ## 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, "skills": "skills/database-migration-helper" } ``` | 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. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.tessl.io/creating-skills-and-plugins/create-a-skill.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.