@letta-ai/letta-code 0.27.4 → 0.27.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@letta-ai/letta-code",
-  "version": "0.27.4",
+  "version": "0.27.5",
   "description": "Letta Code is a CLI tool for interacting with stateful Letta agents from the terminal.",
   "type": "module",
   "packageManager": "bun@1.3.0",
@@ -36,7 +36,7 @@
   },
   "dependencies": {
     "@letta-ai/letta-client": "^1.10.2",
-    "@earendil-works/pi-ai": "^0.77.0",
+    "@earendil-works/pi-ai": "^0.78.1",
     "@pierre/diffs": "1.2.2",
     "glob": "^13.0.0",
     "ink-link": "^5.0.0",

package/skills/acquiring-skills/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: acquiring-skills
-description: Guide for safely discovering and installing skills from external repositories. Use when a user asks for something where a specialized skill likely exists (browser testing, PDF processing, document generation, etc.) and you want to bootstrap your understanding rather than starting from scratch.
+description: Discover and install skills from Hermes, ClawHub, GitHub, and other registries. Load this skill whenever a user asks for a capability you don't already have — image generation, social media, email, calendar, finance, DevOps, search, browser automation, etc.
 ---
 
 # Acquiring New Skills
 
-This skill teaches you how to safely discover and install skills from external sources.
+This skill teaches you how to safely discover and install skills from external sources, including the Hermes Skills Hub, ClawHub (OpenClaw), GitHub repositories, and Letta community repos.
 
 ## SAFETY - READ THIS FIRST
 
@@ -16,19 +16,33 @@ Skills can contain:
 ### Trusted Sources (no user approval needed for download)
 - `https://github.com/letta-ai/skills` - Letta's community skills
 - `https://github.com/anthropics/skills` - Anthropic's official skills
+- `official/*` - Hermes official optional skills (from `NousResearch/hermes-agent`)
 
 ### Untrusted Sources (ALWAYS verify with user)
-For ANY source other than letta-ai or anthropics:
+For ANY source other than the above:
 1. Ask the user before downloading
 2. Explain where the skill comes from
 3. Get explicit approval
 
+This includes ClawHub community skills and arbitrary GitHub repos.
+
 ### Script Safety
 Even for skills from trusted sources, ALWAYS:
 1. Read and inspect any scripts before executing them
 2. Understand what the script does
 3. Be wary of network calls, file operations, or system commands
 
+### Cross-Harness Compatibility
+Skills from Hermes, OpenClaw, and other ecosystems were written for their own harnesses. After installing, **read the full SKILL.md before using it** and watch for:
+
+- **Harness-specific commands** — e.g. `hermes skills config`, `openclaw plugins install`, `/curator`, `/kanban`. These won't exist in Letta. Determine whether the underlying capability can be achieved with Letta tools (Bash, the Skill tool, etc.) or if the skill simply doesn't apply.
+- **Harness-specific paths and state** — e.g. `~/.hermes/skills/`, `~/.openclaw/skills/`, `~/.hermes/config.yaml`. Letta stores skills in the agent's memfs (`<memory-dir>/skills/`). Adapt any path references.
+- **Toolset assumptions** — some skills assume specific tool names or APIs (e.g. Hermes `web` toolset, OpenClaw `browser` tool). Map these to the equivalent Letta tools or note when no equivalent exists.
+- **Platform gating** — skills may declare `platforms: [cli, discord, telegram]` in frontmatter. Ignore platform restrictions that don't apply to Letta.
+- **Environment variables** — skills may require API keys or credentials. Check `requires.env` in frontmatter and note any setup the user needs to do.
+
+If a skill's core knowledge (procedures, API references, best practices) is useful but its commands are harness-specific, adapt the instructions mentally or suggest the user install the relevant CLI tool. If a skill is entirely about harness-specific plumbing with no transferable knowledge, skip it and look for an alternative.
+
 ## When to Use This Skill
 
 **DO use** when:
@@ -45,78 +59,221 @@ Even for skills from trusted sources, ALWAYS:
 
 If you recognize a task that might have an associated skill, **ask the user first**:
 
-> "This sounds like something where a community skill might help (e.g., webapp testing with Playwright). Would you like me to look for available skills in the Letta or Anthropic repositories? This might take a minute, or I can start coding right away if you prefer."
+> "This sounds like something where a community skill might help. Would you like me to search for available skills? I can check the Hermes catalog, ClawHub, or GitHub. Or I can start coding right away if you prefer."
 
 The user may prefer to start immediately rather than wait for skill discovery.
 
 Only proceed with skill acquisition if the user agrees.
 
-## Skill Repositories
+## Skill Sources
+
+### 1. Hermes Skills Hub (NousResearch)
+
+Hermes has a full Skills Hub with 88k+ skills across multiple registries. It includes official optional skills shipped with the project, plus community skills from skills.sh, well-known endpoints, GitHub repos, ClawHub, LobeHub, and browse.sh.
+
+**Searching Hermes skills:**
+
+The Hermes CLI has built-in search and browse:
+
+```bash
+hermes skills browse                              # Browse all hub skills (official first)
+hermes skills browse --source official            # Browse only official optional skills
+hermes skills search kubernetes                   # Search all sources
+hermes skills search react --source skills-sh     # Search the skills.sh directory
+hermes skills search https://mintlify.com/docs --source well-known
+hermes skills inspect openai/skills/k8s           # Preview before installing
+```
+
+The web catalog is at https://hermes-agent.nousresearch.com/docs/skills.
+
+Hermes hub sources:
+
+| Source | Example identifier | Notes |
+|--------|--------------------|-------|
+| `official` | `official/security/1password` | Optional skills shipped with Hermes |
+| `skills-sh` | `skills-sh/vercel-labs/agent-skills/vercel-react-best-practices` | skills.sh directory |
+| `well-known` | `well-known:https://mintlify.com/docs/.well-known/skills/mintlify` | Skills hosted at `/.well-known/skills/` |
+| `url` | `https://sharethis.chat/SKILL.md` | Direct URL to a single SKILL.md |
+| `github` | `openai/skills/k8s` | GitHub repo/path |
+| `clawhub` | ClawHub registry skills | ClawHub marketplace |
+| `lobehub` | LobeHub registry skills | LobeHub marketplace |
+| `browse-sh` | `browse-sh/airbnb.com/search-listings-ddgioa` | browse.sh crawled skills |
+
+If Hermes is not installed, you can browse the official optional skills directly:
+
+```bash
+# Browse the catalog on GitHub
+# https://github.com/NousResearch/hermes-agent/tree/main/optional-skills
+# Categories: autonomous-ai-agents, blockchain, creative, devops, finance,
+#             health, mcp, mlops, productivity, research, security, ...
+
+# Or clone and browse locally
+git clone --depth 1 https://github.com/NousResearch/hermes-agent.git /tmp/hermes-browse
+ls /tmp/hermes-browse/optional-skills/
+ls /tmp/hermes-browse/optional-skills/finance/
+rm -rf /tmp/hermes-browse
+```
+
+**Installing Hermes skills** into Letta uses the `official/` prefix (for official optional skills):
+
+```bash
+letta skills install official/finance/stocks
+letta skills install official/blockchain/solana
+letta skills install official/research/duckduckgo-search
+letta skills install official/mlops/flash-attention
+letta skills install official/creative/meme-generation
+```
+
+The `official/<category>/<skill>` form clones `NousResearch/hermes-agent` and copies from `optional-skills/<category>/<skill>`.
+
+For non-official Hermes hub skills, use the GitHub URL or shorthand form to install into Letta (e.g., `letta skills install openai/skills/k8s`).
+
+### 2. ClawHub (OpenClaw)
+
+ClawHub (https://clawhub.ai) is the public registry for OpenClaw skills and plugins. It hosts community-contributed skills with versioning, security scans, and search.
+
+**Searching ClawHub skills:**
+
+```bash
+# Browse the web registry
+# https://clawhub.ai
+
+# Or use the clawhub CLI if installed
+clawhub search "calendar"
+clawhub search "screenshot"
+clawhub explore
+
+# Or search via the API directly
+curl -s "https://clawhub.ai/api/v1/skills?q=calendar" | jq '.items[].slug'
+```
+
+**Installing ClawHub skills** uses the `clawhub/` or `clawhub:` prefix:
+
+```bash
+letta skills install clawhub/nano-banana-pro
+letta skills install clawhub:nano-banana-pro
+letta skills install clawhub:nano-banana-pro@1.0.1      # pin a version
+letta skills install https://clawhub.ai/skills/my-skill  # URL form also works
+```
+
+**Note:** A bare slug like `letta skills install nano-banana-pro` will NOT resolve through ClawHub — you must include the `clawhub/` or `clawhub:` prefix.
+
+### 3. GitHub Repositories
+
+Any GitHub repository containing a `SKILL.md` can be installed directly.
+
+```bash
+# Full repo (installs from repo root)
+letta skills install https://github.com/owner/repo
+
+# Subdirectory (tree URL)
+letta skills install https://github.com/owner/repo/tree/main/path/to/skill
+
+# SKILL.md blob URL (installs parent directory)
+letta skills install https://github.com/owner/repo/blob/main/path/to/skill/SKILL.md
+
+# Shorthand: owner/repo/path
+letta skills install owner/repo/path/to/skill
+```
+
+### 4. Letta & Anthropic Community Repos
 
 | Repository | Description |
 |------------|-------------|
 | https://github.com/letta-ai/skills | Community skills for Letta agents |
 | https://github.com/anthropics/skills | Anthropic's official Agent Skills |
 
-Browse these repositories to discover available skills. Check the README for skill listings.
+These can be installed via the GitHub URL forms above, or manually cloned and copied.
+
+## The `letta skills install` Command
+
+The CLI handles downloading, placing the skill in the agent's memory, and committing the change:
+
+```bash
+letta skills install <source> --agent $AGENT_ID [--force]
+```
+
+Your agent ID is always available as `$AGENT_ID` in the environment. Pass it explicitly with `--agent` to install into your own memfs:
+
+```bash
+letta skills install official/finance/stocks --agent $AGENT_ID
+letta skills install clawhub/nano-banana-pro --agent $AGENT_ID
+```
+
+| Flag | Purpose |
+|------|---------|
+| `--agent <id>` | Install into a specific agent's memfs (use `$AGENT_ID` for yourself) |
+| `-n <name>` | Resolve agent by name instead of id |
+| `--force` | Replace an existing skill with the same name |
+
+Also available as a top-level alias: `letta install <source> --agent $AGENT_ID`.
+
+**Managing installed skills:**
+
+```bash
+letta skills list --agent $AGENT_ID
+letta skills delete <skill-name> --agent $AGENT_ID
+```
 
 ## Installation Locations
 
+When using `letta skills install`, skills are placed in the agent's memfs at `<memory-dir>/skills/<skill-name>/`.
+
+For manual installation:
+
 | Location | Path | When to Use |
 |----------|------|-------------|
-| **Agent-scoped** | `~/.letta/agents/<agent-id>/memory/skills/<skill>/` | Skills for a single agent (default for agent-specific capabilities) |
+| **Agent-scoped** | `~/.letta/agents/<agent-id>/memory/skills/<skill>/` | Skills for a single agent (default) |
 | **Global** | `~/.letta/skills/<skill>/` | General-purpose skills useful across projects |
 | **Project** | `.skills/<skill>/` | Project-specific skills |
 
-**Rule**: Default to **agent-scoped** for changes that should apply only to the current agent. Use **project** for repo-specific skills. Use **global** only if all agents should inherit the skill.
+**Rule**: Default to **agent-scoped**. Use **project** for repo-specific skills. Use **global** only if all agents should inherit the skill.
 
-## How to Download Skills
+## Manual Download (When CLI Install Isn't Available)
 
 Skills are directories containing SKILL.md and optionally scripts/, references/, examples/.
 
-### Method: Clone to /tmp, then copy
-
 ```bash
-# 1. Clone the repo (shallow)
+# Clone, copy, cleanup
 git clone --depth 1 https://github.com/anthropics/skills /tmp/skills-temp
-
-# 2. Copy the skill to your skills directory
-# For agent-scoped (recommended default):
 cp -r /tmp/skills-temp/skills/webapp-testing ~/.letta/agents/<agent-id>/memory/skills/
-# For global:
-# cp -r /tmp/skills-temp/skills/webapp-testing ~/.letta/skills/
-# For project:
-# cp -r /tmp/skills-temp/skills/webapp-testing .skills/
-
-# 3. Cleanup
 rm -rf /tmp/skills-temp
 ```
 
-### Alternative: rsync (preserves permissions)
+## Registering New Skills
 
-```bash
-git clone --depth 1 https://github.com/anthropics/skills /tmp/skills-temp
-rsync -av /tmp/skills-temp/skills/webapp-testing/ ~/.letta/agents/<agent-id>/memory/skills/webapp-testing/
-rm -rf /tmp/skills-temp
-```
+After installing (via CLI or manual copy), skills are automatically discovered on the next message. Skills are discovered from `~/.letta/skills/`, `.skills/`, and agent-scoped `~/.letta/agents/<agent-id>/memory/skills/` directories.
 
-## Registering New Skills
+## Search Strategy
+
+When looking for a skill to solve a user's problem:
 
-After downloading a skill, it will be automatically discovered on the next message. Skills are discovered from `~/.letta/skills/`, `.skills/`, and agent-scoped `~/.letta/agents/<agent-id>/memory/skills/` directories.
+1. **Search Hermes Skills Hub first** — `hermes skills search <query>` searches 88k+ skills across all registries. If Hermes CLI isn't available, browse the official optional-skills on GitHub (finance, mlops, blockchain, devops, research, creative, security, etc.).
+2. **Search ClawHub** — community registry with versioning. Use `clawhub search` or the web UI.
+3. **Search GitHub** — look for repos with `SKILL.md` files. Try `github.com/letta-ai/skills` and `github.com/anthropics/skills` first.
+4. **Ask the user** — they may know of a specific skill repo or have preferences about sources.
 
 ## Complete Example
 
-User asks: "Can you help me test my React app's UI?"
+User asks: "Can you help me track stock prices?"
+
+1. **Recognize opportunity**: Stock/finance data — Hermes has a stocks skill
+2. **Ask user**: "Hermes has an official stocks skill that covers quotes, history, search, and crypto via Yahoo. Want me to install it?"
+3. **If user agrees, install**:
+   ```bash
+   letta skills install official/finance/stocks --agent $AGENT_ID
+   ```
+4. **Review for compatibility**: Read the installed SKILL.md. Check for harness-specific commands, paths, or tools that need adaptation (see Cross-Harness Compatibility above). Confirm the skill's instructions make sense in Letta before using it.
+5. **Invoke**: `Skill(skill: "stocks")`
+6. **Use**: Follow the skill's instructions, adapting any harness-specific details as needed
+
+User asks: "Can you generate images with Nano Banana Pro?"
 
-1. **Recognize opportunity**: Browser/webapp testing - likely has a skill
-2. **Ask user**: "Would you like me to look for webapp testing skills, or start coding right away?"
-3. **If user agrees, find skill**: Check anthropics/skills for webapp-testing
-4. **Download** (trusted source):
+1. **Recognize opportunity**: Image generation skill on ClawHub
+2. **Ask user**: "There's a nano-banana-pro skill on ClawHub. Want me to install it?"
+3. **Install**:
    ```bash
-   git clone --depth 1 https://github.com/anthropics/skills /tmp/skills-temp
-   cp -r /tmp/skills-temp/skills/webapp-testing ~/.letta/agents/<agent-id>/memory/skills/
-   rm -rf /tmp/skills-temp
+   letta skills install clawhub/nano-banana-pro --agent $AGENT_ID
    ```
-5. **Inspect scripts**: Read any .py or .ts files before using them
-6. **Invoke**: `Skill(skill: "webapp-testing")`
-7. **Use**: Follow the skill's instructions for the user's task
+4. **Review for compatibility**: Read the SKILL.md, check for any OpenClaw-specific commands or setup, adapt as needed.
+5. **Invoke**: `Skill(skill: "nano-banana-pro")`

package/skills/creating-extensions/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: creating-extensions
-description: Creates and edits trusted local Letta Code extensions, including extension tools, slash commands, lifecycle/turn events, scoped conversation helpers, panels, status values, and capability-gated behavior. Use when the user asks to make an extension, add a tool the agent can call, add a slash command, transform turns, react to app events, or add lightweight extension UI outside the dedicated /statusline flow.
+description: Creates and edits trusted local Letta Code extensions, including tools, slash commands, local-only model providers, lifecycle/turn events, scoped conversation helpers, panels, status values, and capability-gated behavior. Use when asked to make an extension, add an agent-callable tool, add a slash command, add a local provider/model adapter, transform turns, react to app events, or add lightweight extension UI outside the dedicated /statusline flow.
 ---
 
 # Creating Extensions
@@ -13,6 +13,8 @@ Use this skill to create or update trusted global Letta Code extensions in:
 
 Extensions are trusted local apps for Letta Code. They add small composable capabilities through extension APIs, not by importing app internals. Prefer scoped handles (`ctx.conversation`, `ctx.cwd`, `ctx.agent`, `letta.getContext()`) and guard optional UI with `letta.capabilities`.
 
+Capabilities vary by surface. TUI/headless may load tools, commands, events, UI, and providers; the desktop listener loads provider-only extensions for local provider discovery. Always guard optional capabilities.
+
 ## Choose the right capability
 
 | User wants | Build |
@@ -24,6 +26,7 @@ Extensions are trusted local apps for Letta Code. They add small composable capa
 | Show transient output above input | Panel, usually from a command |
 | Show small persistent state | Status value |
 | React to app/session lifecycle or transform outbound turns | Event |
+| Add a custom model/API provider for local agents | Provider extension (local agents only) |
 | Change the bottom statusline appearance | Use `customizing-statusline`, not this skill |
 
 Default to a **tool** when the model should decide when to use the capability. Default to a **command** when the human explicitly invokes it. Compose capabilities when the UX needs it, e.g. command + panel + scoped conversation fork.
@@ -32,17 +35,16 @@ Default to a **tool** when the model should decide when to use the capability. D
 
 1. Inspect `~/.letta/extensions/` for related files.
 2. Preserve unrelated extension code. Prefer a focused new file if merging would be messy.
-3. Choose the extension shape:
-   - simple tool/command/event: read the specific recipe below
-   - multi-capability or stateful extension: also read `references/architecture.md`
-4. Load only the needed recipe:
+3. Choose the extension shape and load only the needed recipe:
    - tools: `references/tools.md`
    - commands: `references/commands.md`
+   - local custom providers: `references/providers.md`
    - events: `references/events.md`
    - panels/status/capabilities: `references/ui.md`
    - busy side-question pattern: `references/btw-command.md`
+4. For multi-capability or stateful extensions, also read `references/architecture.md`.
 5. Write a single-file extension unless the user asks for something larger.
-6. Return disposers for registered commands/tools/events, timers, subscriptions, and panels that should close on reload.
+6. Return disposers for registered providers/commands/tools/events, timers, subscriptions, and panels that should close on reload.
 7. Do a basic review: valid names, descriptions present, schemas are object schemas, optional capabilities guarded, scoped APIs used, cleanup returned.
 8. Tell the user the absolute file path changed and to run `/reload`. If an extension breaks startup or command handling, recover with `letta --no-extensions` or `LETTA_DISABLE_EXTENSIONS=1 letta`.
 
@@ -74,6 +76,7 @@ letta.capabilities.commands
 letta.capabilities.events.lifecycle
 letta.capabilities.events.tools
 letta.capabilities.events.turns
+letta.capabilities.providers
 letta.capabilities.ui.panels
 letta.capabilities.ui.statusValues
 letta.capabilities.ui.customStatuslineRenderer
@@ -89,9 +92,21 @@ letta.capabilities.ui.customStatuslineRenderer
 - Use `letta.client` only for server-specific Letta API calls; do not use it as a substitute for scoped conversation helpers.
 - Do not import `@/backend`, `@/cli`, or other Letta Code internals from extension files.
 
+## Diagnostics
+
+Use `letta.diagnostics.report({ message, severity })` sparingly as a debug utility for extension setup/runtime problems an agent should inspect, such as missing required environment variables or failed local configuration. Default severity is `"error"`; use `severity: "warning"` only for optional/degraded behavior. Keep messages short and actionable, and do not dump routine logs or large state.
+
+Agents can inspect local extension diagnostics at:
+
+```text
+~/.letta/extensions/diagnostics/latest.json
+```
+
 ## Rules
 
 - Global trusted code only for now. Do not create project extensions.
+- Custom provider extensions are local-backend/local-agent only. They do not add providers for Constellation/cloud agents.
+- Provider extensions may run in a provider-only listener context; keep provider registration independent from commands/tools/UI and guard everything else.
 - Do not assume extra npm packages are available.
 - Do not do surprising side effects on startup; extensions activate on app start and `/reload`.
 - Keep user-facing output short and intentional.
@@ -110,6 +125,7 @@ Before finishing, verify:
 - Tool descriptions explain when the model should call them.
 - JSON schemas are object schemas with useful descriptions.
 - Optional UI/event/statusline APIs are capability-guarded.
+- Provider extensions are capability-guarded and clearly documented as local-agent only.
 - Timers, intervals, event registrations, and panels are cleaned up in a disposer.
 - Busy commands return `{ type: "handled" }` quickly and avoid main-conversation sends.
 - Conversation work uses `ctx.conversation` or forked handles, not app internals.
@@ -118,9 +134,12 @@ Before finishing, verify:
 
 ## References
 
-- `references/architecture.md` - composition, state, cleanup, scoped conversation, and review checklist for complex extensions
-- `references/tools.md` - extension tools the model can call
-- `references/commands.md` - slash commands, command results, and skill-backed commands
-- `references/events.md` - lifecycle and turn event handlers
-- `references/ui.md` - panels, status values, capability guards
-- `references/btw-command.md` - advanced busy-safe side-question command using scoped conversation helpers
+| Reference | Load when |
+| --- | --- |
+| `references/tools.md` | The model should autonomously call a local capability |
+| `references/commands.md` | The human should invoke `/foo` |
+| `references/providers.md` | Adding a custom model/API provider for local agents |
+| `references/events.md` | Reacting to lifecycle/tool/turn events or transforming turns/tools |
+| `references/ui.md` | Panels, status values, or statusline capability guards are involved |
+| `references/btw-command.md` | Building a busy-safe side-question command with a forked conversation |
+| `references/architecture.md` | Multiple capabilities, local state, cleanup, background model work, or non-trivial composition |

package/skills/creating-extensions/references/architecture.md

@@ -2,6 +2,16 @@
 
 Use this reference for non-trivial extensions: multiple capabilities, local state, timers, background model work, or UI.
 
+## Contents
+
+- Mental model
+- Capability composition patterns
+- Local state
+- Timers and subscriptions
+- Scoped conversation handles
+- Error handling
+- Final review checklist
+
 ## Mental model
 
 An extension is trusted local code that registers capabilities during activation and cleans them up on reload/shutdown. Keep the public surface small:
@@ -13,6 +23,8 @@ An extension is trusted local code that registers capabilities during activation
 
 Do not import Letta Code internals. If the extension API does not expose a capability yet, avoid reaching around it.
 
+Capabilities vary by host surface. Keep each registration behind the matching `letta.capabilities` guard so one file can run in TUI, headless, and provider-only listener contexts.
+
 ## Capability composition patterns
 
 ### Tool + command

package/skills/creating-extensions/references/commands.md

@@ -4,6 +4,15 @@ Use commands when the human explicitly invokes `/foo`.
 
 For complex command-driven extensions with panels, timers, local state, or background model work, also read `architecture.md`.
 
+## Contents
+
+- Decide command vs skill vs tool
+- Command IDs
+- Prompt command
+- Output-only command
+- Panel command
+- Busy-safe conversation command
+
 ## Decide command vs skill vs tool
 
 | Need | Use |

package/skills/creating-extensions/references/events.md

@@ -2,6 +2,16 @@
 
 Use events when trusted local code should react to app/session changes or transform outbound turns without the human explicitly invoking a command. For event-driven extensions with state, timers, panels, or background model work, also read `architecture.md`.
 
+## Contents
+
+- Capabilities
+- Supported events
+- Tool argument transforms and denial
+- Turn input transforms
+- Event handler context
+- Conversation status example
+- Rules
+
 This is the first slice of the hooks-v2 direction. The long-term goal is for typed extension events to replace settings-based hooks. Existing hooks still own blocking decisions and model feedback injection until each event has a typed return contract.
 
 ## Capabilities