feat: update Skill tool to support load/unload commands (#219)

Co-authored-by: Letta <noreply@letta.com>

src/agent/memory.ts

@@ -16,6 +16,12 @@ export const PROJECT_BLOCK_LABELS = [
   "loaded_skills",
 ] as const;
 
+/**
+ * Block labels that should be read-only (agent cannot modify via memory tools).
+ * These blocks are managed by specific tools (e.g., Skill tool for skills/loaded_skills).
+ */
+export const READ_ONLY_BLOCK_LABELS = ["skills", "loaded_skills"] as const;
+
 /**
  * Check if a block label is a project-level block
  */
@@ -77,8 +83,9 @@ async function loadMemoryBlocksFromMdx(): Promise<CreateBlock[]> {
       }
       const { frontmatter, body } = parseMdxFrontmatter(content);
 
+      const label = frontmatter.label || filename.replace(".mdx", "");
       const block: CreateBlock = {
-        label: frontmatter.label || filename.replace(".mdx", ""),
+        label,
         value: body,
       };
 
@@ -86,6 +93,11 @@ async function loadMemoryBlocksFromMdx(): Promise<CreateBlock[]> {
         block.description = frontmatter.description;
       }
 
+      // Set read-only for skills blocks (managed by Skill tool, not memory tools)
+      if ((READ_ONLY_BLOCK_LABELS as readonly string[]).includes(label)) {
+        block.read_only = true;
+      }
+
       memoryBlocks.push(block);
     } catch (error) {
       console.error(`Error loading ${filename}:`, error);

src/agent/prompts/letta_claude.md

@@ -154,7 +154,8 @@ How to store Skills:
 How to use Skills:
 - Skills are automatically discovered on bootup.
 - Review available skills from the `skills` block and loaded skills from the `loaded_skills` block when you are asked to complete a task.
-- If any skill is relevant, load it using the `Skill` tool.
+- If any skill is relevant, load it using the `Skill` tool with `command: "load"`.
 - Then, navigate and discover additional linked files in its directory as needed. Don't load additional files immediately, only load them when needed.
-- When the task is completed, unload irrelevant skills from the `loaded_skills` block.
-IMPORTANT: Always remove irrelevant skills using memory management tools from the `loaded_skills` block.
+- When the task is completed, unload irrelevant skills using the Skill tool with `command: "unload"`.
+- After creating a new skill, use `command: "refresh"` to re-scan the skills directory and update the available skills list.
+IMPORTANT: Always unload irrelevant skills using the Skill tool to free up context space.

src/agent/prompts/letta_codex.md

@@ -139,7 +139,8 @@ How to store Skills:
 How to use Skills:
 - Skills are automatically discovered on bootup.
 - Review available skills from the `skills` block and loaded skills from the `loaded_skills` block when you are asked to complete a task.
-- If any skill is relevant, load it using the `Skill` tool.
+- If any skill is relevant, load it using the `Skill` tool with `command: "load"`.
 - Then, navigate and discover additional linked files in its directory as needed. Don't load additional files immediately, only load them when needed.
-- When the task is completed, unload irrelevant skills from the `loaded_skills` block.
-IMPORTANT: Always remove irrelevant skills using memory management tools from the `loaded_skills` block.
+- When the task is completed, unload irrelevant skills using the Skill tool with `command: "unload"`.
+- After creating a new skill, use `command: "refresh"` to re-scan the skills directory and update the available skills list.
+IMPORTANT: Always unload irrelevant skills using the Skill tool to free up context space.

src/agent/prompts/letta_gemini.md

@@ -100,7 +100,8 @@ How to store Skills:
 How to use Skills:
 - Skills are automatically discovered on bootup.
 - Review available skills from the `skills` block and loaded skills from the `loaded_skills` block when you are asked to complete a task.
-- If any skill is relevant, load it using the `Skill` tool.
+- If any skill is relevant, load it using the `Skill` tool with `command: "load"`.
 - Then, navigate and discover additional linked files in its directory as needed. Don't load additional files immediately, only load them when needed.
-- When the task is completed, unload irrelevant skills from the `loaded_skills` block.
-IMPORTANT: Always remove irrelevant skills using memory management tools from the `loaded_skills` block.
+- When the task is completed, unload irrelevant skills using the Skill tool with `command: "unload"`.
+- After creating a new skill, use `command: "refresh"` to re-scan the skills directory and update the available skills list.
+IMPORTANT: Always unload irrelevant skills using the Skill tool to free up context space.

src/agent/prompts/loaded_skills.mdx

@@ -1,6 +1,6 @@
 ---
 label: loaded_skills
-description: A memory block to store the full instructions and capabilities from each loaded SKILL.md file in this block.
+description: A memory block to store the full instructions and capabilities from each loaded SKILL.md file in this block. Do not manually edit this block - use the Skill tool to load and unload skills.
 ---
 
-[CURRENTLY EMPTY]
+[CURRENTLY EMPTY]

src/agent/prompts/skill_creator_mode.md

@@ -16,7 +16,7 @@ Your goal is to guide the user through a **focused, collaborative workflow** to
    - `loaded_skills` – SKILL.md contents for currently loaded skills
 2. If a `skill-creator` skill is **not already loaded** in `loaded_skills`, you should **attempt to load it** using the `Skill` tool:
    - Call the `Skill` tool with:
-     - `skill: "skill-creator"`
+     - `command: "load", skills: ["skill-creator"]`
    - The environment may resolve this from either the project’s `.skills` directory or a bundled `skills/skills/skill-creator/SKILL.md` location.
 3. If loading `skill-creator` fails (for example, the tool errors or the file is missing), or if the environment does not provide it, continue using your own judgment based on these instructions.
 
@@ -118,6 +118,5 @@ Your goal is to:
 1. Understand the desired skill thoroughly.
 2. Propose a clear, reusable design.
 3. Implement or update the actual skill files in the repository.
-4. Leave the user with a ready‑to‑use skill that appears in the `skills` memory block and can be loaded with the `Skill` tool.
-
-
+4. After creating or updating the skill files, use the `Skill` tool with `command: "refresh"` to re-scan the skills directory and update the `skills` memory block.
+5. Leave the user with a ready‑to‑use skill that appears in the `skills` memory block and can be loaded with the `Skill` tool.

src/agent/prompts/skill_unload_reminder.txt

@@ -1,6 +1,5 @@
 <system-reminder>
 The `loaded_skills` block has at least one skill loaded. You should:
 1. Check if loaded skills are relevant for the current task.
-2. For any skills that are irrelevant, unload them using the `memory` tool.
-If the block will be empty after unloading, add a "[CURRENTLY EMPTY]" tag.
+2. For any skills that are irrelevant, unload them using the `Skill` tool with `command: "unload"`.
 </system-reminder>

src/agent/prompts/skills.mdx

@@ -1,6 +1,6 @@
 ---
 label: skills
-description: A memory block to store all available Skills with their metadata (name and description). Whenever a new Skill is discovered / created or an existing Skill is updated, I should store it here. I should always check the `.skills` directory for an updated skill list.
+description: A memory block listing all available skills with their metadata (name and description). This block is auto-generated based on the `.skills` directory. Do not manually edit this block.
 ---
 
-[CURRENTLY EMPTY: CREATE A LIST OF AVAILABLE SKILLS (DIRECTORIES WITH SKILL.MD FILE) WITH DESCRIPTIONS IN THIS MEMORY BLOCK. ALWAYS CHECK THE `.skills` DIRECTORY TO MAKE SURE YOU HAVE AN UPDATED LIST OF SKILLS]
+[CURRENTLY EMPTY]

src/agent/prompts/system_prompt.txt

@@ -35,7 +35,8 @@ How to store Skills:
 How to use Skills:
 - Skills are automatically discovered on bootup.
 - Review available skills from the `skills` block and loaded skills from the `loaded_skills` block when you are asked to complete a task.
-- If any skill is relevant, load it using the `Skill` tool.
+- If any skill is relevant, load it using the `Skill` tool with `command: "load"`.
 - Then, navigate and discover additional linked files in its directory as needed. Don't load additional files immediately, only load them when needed.
-- When the task is completed, unload irrelevant skills from the `loaded_skills` block.
-IMPORTANT: Always remove irrelevant skills using memory management tools from the `loaded_skills` block.
+- When the task is completed, unload irrelevant skills using the Skill tool with `command: "unload"`.
+- After creating a new skill, use `command: "refresh"` to re-scan the skills directory and update the available skills list.
+IMPORTANT: Always unload irrelevant skills using the Skill tool to free up context space.