Skills

Skills are knowledge your agent loads into memory (like a reference guide). For delegating work to separate agents, see Subagents.

Letta Code implements the open Agent Skills standard. Skills are portable across Cursor, Claude Code, VS Code, and other compatible agents.

Skills are directories containing instructions and resources that your agent can load when relevant. Think of them as reference guides your agent consults for specialized tasks—API patterns, testing workflows, deployment procedures.

Unlike memory blocks (which persist in the agent’s context), skills are loaded on-demand by the agent using a tool call. Your agent sees what skills are available and pulls in the full content only when working on a matching task.

Why skills matter

Letta Code agents are stateful and model-agnostic. This creates unique opportunities for skills:

• An agent using Claude can create a skill that a GPT-5 agent later uses
• Skills learned from one coding session transfer to future sessions
• Teams can share skills via version control, building collective expertise

Research on Context-Bench shows that skills measurably improve task completion. When agents learn skills from their own experience, the gains are even larger (Skill Learning blog post).

Interoperability

Letta Code skills follow the open Agent Skills standard. This means skills you create work across multiple agent products:

• Cursor - AI code editor
• Claude Code - Anthropic’s coding agent
• VS Code - GitHub Copilot
• OpenAI Codex - OpenAI’s coding agent
• OpenCode, Amp, Goose - and more

Create a skill once in Letta Code, commit it to your repo, and any skills-compatible agent can use it. This makes skills a portable way to capture team knowledge that isn’t locked to a single tool.

Structure

Skills live in .skills/ at your project root. Each skill is a directory with a SKILL.md file:

.skills/
├── testing/
│   └── SKILL.md
├── api-client/
│   ├── SKILL.md
│   └── references/
│       └── endpoints.md
└── deployment/
    ├── SKILL.md
    └── scripts/
        └── deploy.sh

How skills are discovered

When you start Letta Code, it scans the .skills/ directory and stores available skills in the agent’s skills memory block. Agents always see the name, path, and description of skills.

Skills Directory: /path/to/.skills

Available Skills:

### Testing
ID: `testing`
Description: Unit testing patterns and conventions

### API Client
ID: `api-client`
Description: API integration helpers and endpoints

Creating skills

Writing manually

Create .skills/my-skill/SKILL.md:

---
name: My Skill
description: When and why to use this skill
---

# My Skill

Instructions here...

The description field needs to clearly communicate the contents of the skill, as it is always available to the agent. The agent needs to know whether or not the skill should be loaded.

Learning from experience

After completing a task, run /skill to extract what worked into a reusable skill:

> /skill "Database migration patterns"

When asked to create a skill, the agent reflects on recent messages. It reviews successful approaches, pitfalls encountered, and verification strategies. The agent will then write a skill capturing that knowledge.

Skill learning allows agents to improve over time. See our Skill Learning blog post for details.

What goes in a skill

The SKILL.md file contains the basic instructions, workflows, conventions, and guidance. Good skills are specific and actionable:

## Git workflow

Always create feature branches from main:
git checkout main && git pull && git checkout -b feature/TICKET-123-description

Run lint before committing:
npm run lint && npm run test

Commit messages follow conventional commits: feat:, fix:, docs:, etc.

Example: A complete skill

Here’s a simple but complete skill showing proper structure:

.skills/hello-world/SKILL.md

---
name: Hello World
description: Conventions for greeting messages and welcome text. Use when writing user-facing welcome messages, onboarding copy, or greeting notifications.
---

# Hello World Conventions

When writing greeting messages for this project, follow these patterns:

## Welcome messages

Use a friendly, concise tone:
- "Welcome to [Product]! Let's get started."
- "Hey [Name], good to see you!"

Avoid:
- Overly formal greetings ("Dear valued customer...")
- Exclamation overload ("Welcome!!! So excited!!!")

## Onboarding copy

First-time user messages should:
1. State what the product does in one sentence
2. Offer a single clear next action
3. Provide a way to get help

Example:
"[Product] helps you [value prop]. Click 'New Project' to begin, or visit our docs if you need help."

This skill demonstrates clear description writing (explains what and when), organized sections, and actionable do’s and don’ts.

Bundled resources

Skills can include additional files beyond SKILL.md. The agent only loads these when explicitly referenced, so you can bundle comprehensive resources without consuming context upfront.

.skills/api-client/
├── SKILL.md                    # Main instructions (loaded when skill triggers)
├── references/
│   ├── endpoints.md            # API endpoint documentation
│   ├── error-codes.md          # Error handling reference
│   └── schemas/
│       └── user.json           # Data schemas
├── scripts/
│   ├── auth.py                 # Authentication helper
│   └── validate.py             # Request validation
└── examples/
    └── pagination.md           # Example patterns

Reference these in your SKILL.md:

## Authentication

Use the auth helper script for token management:
Run `scripts/auth.py refresh` to get a new token.

For the full list of endpoints, see `references/endpoints.md`.
For error handling patterns, see `references/error-codes.md`.

The agent reads references/endpoints.md only when it needs endpoint details for the current task. If it’s just refreshing a token, it runs the script without loading the reference docs.

Types of bundled content

Reference docs (references/): Detailed documentation the agent consults as needed—API specs, database schemas, configuration guides. These can be large; they only cost tokens when read.

Scripts (scripts/): Executable code the agent runs directly. More reliable than having the agent regenerate code, and the script source never enters the context—only the output does.

Examples (examples/): Sample code, templates, or patterns the agent can reference or copy. Useful for showing preferred approaches.

Assets (assets/): Configuration files, templates, or data files the agent might need to read or copy.

Using skills

Skills are automatically discovered when you create a new agent. The agent sees available skills in its memory and decides when to load them. Agents with access to skills call the Skill tool to load them into memory.

You can explicitly request a skill through prompting:

> Use the testing skill to add unit tests for this function

The Skill tool

The agent uses the Skill tool to manage loaded skills. The tool supports three commands:

Load skills (add to active memory):

skill(command='load', skills=['api-client'])
skill(command='load', skills=['testing', 'deployment'])  # batch load

Unload skills (remove from active memory):

skill(command='unload', skills=['api-client'])
skill(command='unload', skills=['testing', 'deployment'])  # batch unload

Refresh skills list (re-scan .skills directory):

skill(command='refresh')

When loading, Letta Code reads {skillsDir}/{skillId}/SKILL.md and appends the content to the loaded_skills memory block. When unloading, it cleanly removes those skills. Use refresh after creating new skills to make them discoverable.

Two memory blocks for skills

skills block (always visible, read-only): Contains the list of available skills with names and descriptions. This is how the agent knows what skills exist and when to use them. Updated by the skill(command='refresh') command when new skills are added.

loaded_skills block (modified during session, read-only): Contains the full SKILL.md content of actively loaded skills. Starts empty and grows as the agent loads skills. Modified only by the Skill tool—the agent cannot edit these blocks directly via memory tools.

This two-tier system means you can have 50 available skills but only 2 loaded—only the loaded ones consume context tokens. The read-only protection prevents accidental corruption of skill content.

Two ways to access skills

Using the Skill tool (persistent loading): The agent calls the tool to add skill content to its memory. Skill loading is the recommended pattern. Best for skills you’ll reference repeatedly during a task.

Reading directly (one-time access): The agent can Read(.skills/api-client/SKILL.md) without using the Skill tool. Useful for quick previews or one-time lookups where you don’t want the content persisting in memory. This skill will eventually disappear from the agent’s context.

Custom location

Use a different skills directory:

letta --skills ~/my-global-skills

Built-in skills

Letta Code includes built-in skills that are automatically available:

Skill	Description
adding-models	Guide for adding new LLM models to Letta Code
creating-skills	Guide for creating effective skills
initializing-memory	Guide for initializing agent memory (used by /init)

Tips

• Keep skills focused—one domain per skill. Split large skills into smaller ones.
• Write specific instructions, not general advice. “Run npm test -- --watch” is better than “make sure to test your code.”
• Version control .skills/ to share with your team.
• For deep dives on skill design and research, see Context-Bench Skills.

Resources

• Agent Skills Standard - Open specification for portable skills
• Letta’s skill repository - Community skills for general agent learning
• Example skills - Anthropic’s maintained skill examples