@letta-ai/letta-code 0.1.19 → 0.2.0

package/README.md

@@ -76,6 +76,75 @@ Letta Code uses a hierarchical memory system:
 Memory blocks are highly configurable — see our [docs](https://docs.letta.com/guides/agents/memory-blocks) for advanced configuration options.
 Join our [Discord](https://discord.gg/letta) to share feedback on persistence patterns for coding agents.
 
+## Skills
+
+**Skills are automatically discovered from a `.skills` directory in your project.**
+
+Skills allow you to define custom capabilities that the agent can reference and use. When you start a new session, Letta Code recursively scans for `SKILL.MD` files and loads any skill definitions found.
+
+### Creating Skills
+
+Create a `.skills` directory in your project root and organize skills in subdirectories:
+
+```bash
+mkdir -p .skills/data-analysis
+```
+
+Each skill is defined in a file named `SKILL.MD`. The directory structure determines the skill ID:
+
+```
+.skills/
+├── data-analysis/
+│   └── SKILL.MD          # skill id: "data-analysis"
+└── web/
+    └── scraper/
+        └── SKILL.MD      # skill id: "web/scraper"
+```
+
+Create a skill file (`.skills/data-analysis/SKILL.MD`):
+
+```markdown
+---
+name: Data Analysis Skill
+description: Analyzes CSV files and generates statistical reports
+category: Data Processing
+tags:
+  - analytics
+  - statistics
+  - csv
+---
+
+# Data Analysis Skill
+
+This skill analyzes data files and generates comprehensive reports.
+
+## Usage
+
+Use this skill to analyze CSV files and generate statistical summaries...
+```
+
+**Skill File Format:**
+
+- **File name:** Must be named `SKILL.MD` (case-insensitive)
+- **Required frontmatter:**
+  - `name` - Display name for the skill
+  - `description` - Brief description of what the skill does
+- **Optional frontmatter:**
+  - `category` - Category for organizing skills (skills are grouped by category in the agent's memory)
+  - `tags` - Array of tags for filtering/searching
+- **Body:** Additional details and documentation about the skill
+
+Skills are automatically loaded into the agent's memory on startup, making them available for reference throughout your session.
+
+### Custom Skills Directory
+
+You can specify a custom skills directory using the `--skills` flag:
+
+```bash
+letta --skills /path/to/custom/skills
+letta -p "Use the custom skills" --skills ~/my-skills
+```
+
 ## Usage
 
 ### Interactive Mode
@@ -86,10 +155,44 @@ letta --agent <id>       # Use specific agent ID
 letta --model <model>    # Specify model (e.g., claude-sonnet-4.5, gpt-4o)
 letta -m <model>         # Short form of --model
 letta --continue         # Resume global last agent (deprecated, use project-based)
+
+# Managing tools (requires --agent flag)
+letta --agent <id> --link      # Attach Letta Code tools to agent, then start session
+letta --agent <id> --unlink    # Remove Letta Code tools from agent, then start session
 ```
 
 > **Note:** The `--model` flag is inconsistent when resuming sessions. We recommend using the `/model` command instead to change models in interactive mode.
 
+#### Interactive Commands
+
+While in a session, you can use these commands:
+- `/agent` - Show current agent link
+- `/model` - Switch models
+- `/stream` - Toggle token streaming on/off
+- `/link` - Attach Letta Code tools to current agent (enables Read, Write, Edit, Bash, etc.)
+- `/unlink` - Remove Letta Code tools from current agent
+- `/clear` - Clear conversation history
+- `/exit` - Exit and show session stats
+- `/logout` - Clear credentials and exit
+
+#### Managing Letta Code Tools
+
+Letta Code provides tools like `Bash`, `Read`, `Write`, `Edit`, `Grep`, `Glob`, and more. You can attach or remove these tools from any agent:
+
+**Via CLI flags** (before starting session):
+```bash
+letta --agent <id> --link     # Attach Letta Code tools
+letta --agent <id> --unlink   # Remove Letta Code tools
+```
+
+**Via interactive commands** (during session):
+```bash
+/link      # Attach Letta Code tools to current agent
+/unlink    # Remove Letta Code tools from current agent
+```
+
+When you attach tools with `/link` or `--link`, they are added to the agent with approval rules enabled (human-in-the-loop). This means the agent can use these tools, but you'll be prompted to approve each tool call. Use permission modes to control approval behavior (see Permissions section below).
+
 ### Headless Mode
 ```bash
 letta -p "Run bun lint and correct errors"              # Auto-resumes project agent