creating-mods
Creating Mods
Use this skill to create or update trusted Letta Code mod files. Mods are trusted local code that add small composable capabilities through mod APIs, not by importing app internals. Dynamic agent/conversation/workspace/model state is passed as ctx to tool, command, event, and permission callbacks (panels receive live agent/model in their render context); do not read mutable global context for model-callable behavior. Prefer scoped handles (ctx.conversation, ctx.cwd, ctx.agent) and guard optional UI with letta.capabilities.
Capabilities vary by surface — not every surface loads every capability. The TUI/headless host can load tools, commands, events, UI, and providers; the desktop listener loads tools, commands, providers, and tool/turn events, but not panel UI. Always guard each registration on the capabilities its behavior needs.
Choose where the mod file lives
Default to a single mod file unless the user asks for something larger.
| Location | Use when |
|---|---|
~/.letta/mods/foo.ts |
The behavior should apply to local sessions on this machine. Use this by default. |
$MEMORY_DIR/mods/foo.ts |
The behavior should travel with one agent's MemFS/memory. |
Do not create project mods.
Packaging is an upgrade path, not the default authoring path. If the user asks to share, publish, distribute, or use third-party package dependencies, first build a working mod file, then use letta mods package <mod-file> --name <package-name>. Package install/update/download/publish details belong outside this skill.