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

Each skill is a directory containing a SKILL.md file. Skills can live in multiple locations:

Location	Scope	Description
.skills/	Project	Skills specific to this project (version controlled)
~/.letta/agents/{id}/skills/	Agent	Skills specific to one agent (personalization)
~/.letta/skills/	Global	Skills shared across all agents on this machine
(bundled)	Built-in	Skills that ship with Letta Code

Example project skills structure:

.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 all skill directories and makes available skills visible to the agent via system-reminder messages in the conversation. Skills with the same ID are resolved by priority - project skills override agent skills, which override global, which override bundled.

Priority order (highest to lowest):

1. Project (.skills/) - Current project only
2. Agent (~/.letta/agents/{id}/skills/) - Skills specific to this agent
3. Global (~/.letta/skills/) - Shared across all agents on this machine
4. Bundled - Built-in to Letta Code

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 listed in system-reminder messages and invokes them when relevant. You can also invoke skills directly using slash command syntax:

> /commit
> /review-pr 123

The Skill tool

The agent uses the Skill tool to invoke skills directly. The tool takes a skill name and optional arguments:

skill(skill='commit')
skill(skill='review-pr', args='123')
skill(skill='pdf')

When invoked, Letta Code reads the skill’s SKILL.md content and injects it into the conversation as context. The skill content is wrapped in XML tags matching the skill name (e.g., <commit>...</commit>) so the agent can detect already-loaded skills.

Skills are listed in system-reminder messages in the conversation. The agent matches user requests to available skills and invokes them automatically. You can also use /<skill-name> as shorthand to invoke a skill directly.

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
acquiring-skills	Discover and install skills from external repositories
creating-skills	Guide for creating effective skills
defragmenting-memory	Clean up and reorganize memory blocks (backup, edit, restore)
finding-agents	Find other agents on the same server
initializing-memory	Guide for initializing agent memory (used by /init)
messaging-agents	Send messages to other agents on your server
migrating-memory	Migrate memory blocks between agents
searching-messages	Search past messages to recall context
working-in-parallel	Guide for coordinating parallel work with other agents (git worktrees)

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.
• Choose the right scope:
  • Project (.skills/) for team-shared, repo-specific knowledge
  • Agent (~/.letta/agents/{id}/skills/) for personal workflows specific to one agent
  • Global (~/.letta/skills/) for personal skills you want across all your agents
• 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