Creating Mods

What it does

When your agent uses it

• Asked to make a mod
• Add an agent-callable tool
• Add a slash command
• Add a local provider/model adapter

Example prompts

• “Use the creating-mods skill to create and edits trusted local Letta Code mods, including tools, slash commands, local-only model providers…”
• “/creating-mods”

Workflow steps

9 steps, taken from the first numbered list in SKILL.md.

1. 1Pick the target scope: harness mod file (~/.letta/mods/) by default, or agent mod file ($MEMORY_DIR/mods/) only when the behavior should…
2. 2Inspect the relevant mods directory for related files.
3. 3Preserve unrelated mod code. Prefer a focused new file if merging would be messy.
4. 4Choose the mod shape and load only the needed recipe
5. 5For multi-capability or stateful mods, also read references/architecture.md.
6. 6Write a single-file mod unless the user asks for something larger.
7. 7Return disposers for registered providers/commands/tools/events, timers, subscriptions, and panels that should close on reload.
8. 8Do a basic review: valid names, descriptions present, schemas are object schemas, optional capabilities guarded, scoped APIs used, cleanup…
9. 9Tell the user the absolute file path changed and to run /reload. If a mod breaks startup or command handling, recover with letta --no-mods…

What it can do on your machine

Read from SKILL.md and the folder at commit d31b879. It shows what the files ask for, not the result of running them.

• Tool permissions

  Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

  From allowed-tools in the SKILL.md frontmatter.

• Runs code

  No scripts in the folder and no shell commands in SKILL.md (its code samples are typescript).

  From the folder's file list and the shell code blocks in SKILL.md.

• Network

  No URLs in SKILL.md.

  From URLs in SKILL.md, links to its own repository left out.

• Credentials

  Names no API keys, tokens, secrets or passwords.

  From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Creating Mods loads about 2.5k tokens when it runs, and up to ~22k if it reads all its reference files. Until then it costs about 108 tokens; SKILL.md has 1,133 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it

~108

When it runs · the whole SKILL.md, loaded when a task matches

~2.5k

With references · SKILL.md plus every file in references/, read only if the agent opens them

~22k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from letta-ai/letta-code at commit d31b879, republished under its Apache-2.0 licence (© letta-ai). 1,133 words, ~2,469 tokens.

name

creating-mods

description

Creates and edits trusted local Letta Code mods, including tools, slash commands, local-only model providers, lifecycle/turn events, scoped conversation helpers, panels, and capability-gated behavior. Use when asked to make a mod, add an agent-callable tool, add a slash command, add a local provider/model adapter, transform turns, react to app events, or add lightweight mod UI outside the dedicated /statusline flow.

export default function activate(letta) {
  const disposers = [];

  if (letta.capabilities.tools) {
    disposers.push(letta.tools.register(/* ... */));
  }

  if (letta.capabilities.commands) {
    disposers.push(letta.commands.register(/* ... */));
  }

  return () => {
    for (const dispose of disposers.reverse()) dispose();
  };
}

letta.capabilities.tools
letta.capabilities.commands
letta.capabilities.events.lifecycle
letta.capabilities.events.tools
letta.capabilities.events.turns
letta.capabilities.events.compact
letta.capabilities.events.llm
letta.capabilities.permissions
letta.capabilities.providers
letta.capabilities.ui.panels

~/.letta/mods/diagnostics/latest.json

© letta-ai, Apache-2.0. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 9 other files (references) in src/skills/builtin/creating-mods of letta-ai/letta-code.

• SKILL.md
• references/analysis-mode.md
• references/architecture.md
• references/commands.md
• references/events.md
• references/permissions.md
• references/plan-mode.md
• references/providers.md
• references/tools.md
• references/ui.md

Open the folder on GitHubat commit d31b879