Skills

Skills are reusable modules that teach your agent new capabilities. They’re automatically discovered from your project’s .skills directory and loaded into the agent’s memory at session start.

How skills work

When you start a Letta Code session, the agent recursively scans the .skills directory for SKILL.md files (case-insensitive). All discovered skills are loaded into memory and grouped by category, making them available throughout your session.

Skill structure

Skills are stored in the .skills directory at the root of your project:

.skills/
├── data-analysis/
│   └── SKILL.md
├── web-scraper/
│   ├── SKILL.md
│   ├── scripts/
│   │   └── scrape.py
│   └── references/
│       └── api-docs.md
└── web/
    └── scraper/
        └── SKILL.md

The skill ID is derived from the directory path:

• .skills/data-analysis/SKILL.md → ID: data-analysis
• .skills/web/scraper/SKILL.md → ID: web/scraper

Creating a skill

Using the /skill command

The easiest way to create a skill is using the interactive skill creation mode:

Start skill creation

> /skill

Or with a description:

> /skill "A skill for generating test fixtures"

The agent will guide you through:

1. Defining the skill’s purpose
2. Writing documentation
3. Adding any scripts or assets

Manual creation

Create a SKILL.md file with frontmatter:

.skills/my-skill/SKILL.md

---
name: My Skill
description: What this skill does
category: Development
tags:
  - testing
  - automation
---

# My Skill

Instructions for using this skill...

## Usage

1. Step one
2. Step two

Skill file format

The skill file must be named SKILL.md (case-insensitive).

Frontmatter

---
name: Skill Display Name        # Required
description: What the skill does # Required
category: Category Name          # Optional - used for grouping
tags:                            # Optional - for filtering
  - tag1
  - tag2
---

Body

The body contains instructions and documentation that guide the agent when using the skill. Include concrete examples and step-by-step guidance.

Using skills

Since skills are loaded at session start, you can reference them directly in your prompts:

> Use the data-analysis skill to analyze this CSV file

The agent already has the skill in memory and will follow its instructions.

Additional resources

A skill directory can include supporting files:

.skills/my-skill/
├── SKILL.md          # Main entry point (required)
├── scripts/          # Reusable scripts
│   ├── setup.sh
│   └── process.py
├── references/       # Long-form documentation
│   └── detailed-guide.md
└── assets/           # Templates, images, etc.
    └── template.json

The agent can read these files when following the skill’s instructions.

Custom skills directory

You can specify a custom skills directory:

Use custom skills directory

letta --skills /path/to/custom/skills

In headless mode

letta -p "..." --skills ~/my-global-skills

Best practices

1. Keep skills focused - Each skill should do one thing well
2. Include examples - Show how to use the skill with concrete examples
3. Document prerequisites - List any dependencies or setup required
4. Use scripts for complex logic - Put reusable code in the scripts/ directory
5. Version control your skills - Commit .skills/ to share with your team