Creating skills

Learn how to create and manage skills using Tessl.

Skills are reusable capabilities that extend AI coding agents with specialized knowledge, workflows, or tool integrations. Tessl makes it easy to create, publish, and share skills with your team or the broader community through the Tessl Registry.

This guide walks you through creating a skill, publishing it, and installing it so your agent can use it.

Prerequisites

Before you begin, make sure you have:

• Tessl CLI installed (see Installation)

• Authenticated with Tessl (tessl login)

• A workspace created (see Workspace management)

Creating a skill

Step 1: Create a new skill

Use the tessl skill new command to create a new skill. You can run it interactively or with flags:

Option 1: Interactive wizard (recommended for first-time users)

tessl skill new

This launches an interactive wizard that guides you through creating the skill.

Option 2: Create with flags

You can create a skill with all parameters specified:

# Create a new skill
tessl skill new --name "database-migration-helper" --description "When you need to create and manage database migrations" --workspace myworkspace --path ./my-skill

The command creates a new directory with a SKILL.md file following the Agent Skills specification. See the CLI commands reference for all available options.

Option 3: Import an existing skill

If you already have a skill (e.g., from a GitHub repository or local directory), you can import it:

# Import from a local directory
tessl skill import ./path/to/my-skill --workspace myworkspace

# Import from GitHub
tessl skill import https://github.com/user/my-skill --workspace myworkspace

# Import and make it public
tessl skill import ./my-skill --workspace myworkspace --public

This validates and imports the skill into your workspace. See the CLI commands reference for all import options.

Step 2: Write your skill

Your skill file must be named SKILL.md and should contain the skill definition following the Agent Skills format. For the complete specification, see:

• Agent Skills Specification - The official Agent Skills format specification

• Anthropic Agent Skills Documentation - Anthropic's official documentation for Agent Skills

Example SKILL.md

Here's what a well-documented SKILL.md file looks like:

---
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

### Example: Adding a Column

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

    -- Down migration
    ALTER TABLE users DROP COLUMN email_verified;


## Best Practices

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

Key components:

• YAML frontmatter (required):

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

  • description: Clear description of the trigger when skill should activate - this is critical for skill discovery by agents

• Markdown body: Concise instructions, examples, and guidance

Important: Keep the documentation simple and focused. The frontmatter description helps agents discover your skill, while the body provides clear, actionable guidance.

Understanding the Tessl package structure

When you create a skill with tessl skill new, it creates a Tessl package structure with a tile.json manifest file. This file contains metadata about your skill:

my-skill/
├── tile.json          # Package manifest
└── SKILL.md          # Your skill file

The tile.json file looks like this:

{
  "name": "myworkspace/database-migration-helper",
  "version": "1.0.0",
  "summary": "Helper for creating and managing database migrations",
  "private": true,
  "skills": {
    "database-migration-helper": {
      "path": "SKILL.md"
    }
  }
}

Key fields:

• name: Package name in workspace/skill-name format

• version: Semantic version (semver)

• skills: Maps skill names to their SKILL.md file paths

You typically don't need to manually edit tile.json unless you're updating the version for a new release. For more details on the tile structure and configuration options, see Configuration files.

Step 3: Validate your skill

Before publishing, validate your skill structure and contents:

tessl skill lint ./my-skill

This command checks:

• SKILL.md format and structure

• Required frontmatter fields (name, description)

• Conformance to the Agent Skills specification

• Markdown validity

For a more comprehensive review with detailed recommendations:

tessl skill review ./my-skill

Fix any errors before proceeding.

Step 4: Publish your skill

Publish your skill to the Tessl Registry:

tessl skill publish ./my-skill --workspace myworkspace

By default, skills are published as private. This means only members of your workspace can install them.

If you're in the skill directory, you can omit the path:

cd my-skill
tessl skill publish --workspace myworkspace

To make a skill public (after approval):

tessl skill publish --workspace myworkspace --public

After publishing, your skill will be available in the Tessl Registry and can be installed by members of your workspace.

Giving others access to your private skill:

To allow team members to install your private skill, add them to your workspace using tessl workspace add-member. See Workspaces for details on managing workspace members and Workspace management for the complete command reference.

Installing a skill

Once published (as private or public), you or your team members can install the skill in any project:

tessl install myworkspace/my-skill

Or install a specific version:

tessl install myworkspace/[email protected]

Skills are installed as part of Tessl packages and automatically made available to your configured agent.

How skills are made available to your agent

When you install a skill (via tessl install), Tessl automatically makes it available to your configured agent:

1. Package installation: The skill is downloaded as part of a Tessl package to .tessl/tiles/<workspace>/<package-name>/ in your project

2. Skill extraction: Skills are extracted and made available to the agent

3. Agent integration: Skills are made available to your agent depending on your agent platform.

Updating a skill

To update a published skill:

1. Make your changes to the SKILL.md file

2. Update the version number in tile.json (following semantic versioning)

3. Validate with tessl skill lint or tessl skill review

4. Publish the new version with tessl skill publish

# Update your SKILL.md file
vim my-skill/SKILL.md

# Update version in tile.json (e.g., from "1.0.0" to "1.1.0")
vim tile.json

# Validate the changes
tessl skill lint ./my-skill

# Publish the updated version
tessl skill publish ./my-skill --workspace myworkspace

Important: Always increment the version in tile.json when publishing updates. Use semantic versioning:

• Patch (1.0.0 → 1.0.1): Bug fixes, minor improvements

• Minor (1.0.0 → 1.1.0): New features, backward-compatible changes

• Major (1.0.0 → 2.0.0): Breaking changes

Users who have installed your skill can update to the new version by running:

tessl install myworkspace/my-skill

This will automatically fetch the latest version of your skill.

Making your skill public (optional)

If you want to share your skill publicly so anyone can install it, you need to request to make it public:

1. Navigate to the Tessl Registry in your browser

2. Log in if you're not already authenticated

3. Navigate to your workspace and find your skill

4. Click on the skill to view its details

5. Select Actions → Make Public

6. Click Request to Make Public

Tessl will review your request and contact you about the status. Once approved, you can publish with the --public flag:

tessl skill publish --workspace myworkspace --public

For more details, see Sharing tiles publicly.

Best practices

• Use SKILL.md format: Skills must be named SKILL.md and follow the Agent Skills specification

• Write clear descriptions: The description in your frontmatter is critical for skill discovery - make it specific about when the skill should be used

• Keep skills focused: Each skill should have a single, clear purpose

• Test before publishing: Use tessl skill lint and tessl skill review to validate your skill before publishing

• Document clearly: Include concise instructions and examples in your SKILL.md body

• Use the --install flag: When creating a new skill, use --install to test it locally immediately

• Version carefully: Always update the version in tile.json before publishing updates (following semantic versioning)

Alternative: Creating a tile for your skill

The workflow above uses tessl skill commands for a skill-first approach. If you need more flexibility (such as combining docs, rules, and skills in one package), you can use the tile-first workflow:

1. Use tessl tile new to create a tile structure with tile.json

2. Add your SKILL.md file to the tile's skills/ directory

3. Reference the skill in tile.json:

   {
     "name": "myworkspace/my-skill",
     "version": "1.0.0",
     "skills": {
       "my-skill": {
         "path": "skills/my-skill/SKILL.md"
       }
     }
   }

4. Use tessl tile lint and tessl tile publish to validate and publish

This approach is useful when you want to package skills together with documentation and rules. For more details, see Creating documentation.

Related documentation

• Agent Skills Specification - The official Agent Skills format specification

• Anthropic Agent Skills Documentation - Anthropic's official documentation for Agent Skills

• Creating documentation - How to create documentation for tiles

• Distributing via registry - Share and maintain tiles via the registry

• Configuration files - Complete reference for tile.json structure

• CLI commands - Full command reference

• Custom agent setup - How agents access tiles and skills