@letta-ai/letta-code 0.7.4-next.2 → 0.7.4-next.3

package/letta.js

@@ -3233,7 +3233,7 @@ var package_default;
 var init_package = __esm(() => {
   package_default = {
     name: "@letta-ai/letta-code",
-    version: "0.7.4-next.2",
+    version: "0.7.4-next.3",
     description: "Letta Code is a CLI tool for interacting with stateful Letta agents from the terminal.",
     type: "module",
     bin: {
@@ -5905,7 +5905,7 @@ Remember: Your memory blocks persist across sessions. What you store now will in
 var init_remember = () => {};
 
 // src/agent/prompts/skill_creator_mode.md
-var skill_creator_mode_default = '# Skill Creation Mode\n\nThe user has invoked the `/skill` command. Your task is to help them **design and create a new Skill** for this project.\n\nYou are a Letta Code agent with:\n- Access to the current conversation, project files, and memory blocks\n- Access to the `Skill` tool (for loading skills) and `AskUserQuestion` (for asking clarifying questions)\n- Access to file tools (Read, Write, Edit, ApplyPatch, etc.) via the toolset\n\nYour goal is to guide the user through a **focused, collaborative workflow** to create or update a Skill that will be reused in the future.\n\n## 1. Load the skill-creator Skill (if available)\n\n1. Inspect your memory blocks:\n   - `skills` – list of available skills and their descriptions\n   - `loaded_skills` – SKILL.md contents for currently loaded skills\n2. If a `skill-creator` skill is **not already loaded** in `loaded_skills`, you should **attempt to load it** using the `Skill` tool:\n   - Call the `Skill` tool with:\n     - `command: "load", skills: ["skill-creator"]`\n   - The environment may resolve this from either the project’s `.skills` directory or a bundled `skills/skills/skill-creator/SKILL.md` location.\n3. 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.\n\nDo **not** load unrelated skills unless clearly relevant to the user’s request.\n\n## 2. Understand the requested skill\n\nThe `/skill` command may have been invoked in two ways:\n\n1. `/skill` (no description)\n2. `/skill <description>` (with a short description, e.g. `/skill image editor for marketing screenshots`)\n\nYou should always:\n\n1. Consider:\n   - The current conversation and what the user has been working on\n   - Relevant project context from files and memory blocks (especially `project` and `skills`)\n2. If a description was provided:\n   - Treat it as the **initial specification** of the skill.\n   - Restate it briefly in your own words to confirm understanding.\n\n## 3. Ask upfront clarifying questions (using AskUserQuestion)\n\nBefore you start proposing a concrete skill design, you MUST ask a small bundle of **high‑value upfront questions** using the `AskUserQuestion` tool.\n\nKeep the initial question set small (3–6 questions) and focused. Examples:\n\n1. Purpose and scope:\n   - “What is the main purpose of this skill?”\n   - “Is this skill meant for a specific project or to be reused across many projects?”\n2. Implementation details:\n   - “Do you want this skill to be mostly guidance (instructions) or to include reusable scripts/templates?”\n   - “Where should the skill live? (e.g. `.skills/your-skill-id` in this repo)”\n\nBundle these together in a single `AskUserQuestion` call. After you receive answers, you can ask follow‑up questions as needed, but avoid overwhelming the user.\n\n## 4. Propose a concrete skill design\n\nUsing:\n- The user’s description (if provided)\n- Answers to your questions\n- The current project and conversation context\n\nYou should propose a **concrete skill design**, including at minimum:\n\n- A skill ID (directory name), e.g. `image-editor`, `pdf-workflow`, `webapp-testing`\n- A concise human‑readable name\n- A one‑paragraph description focused on:\n  - What the skill does\n  - When it should be used\n  - Who is likely to use it\n- Example triggering queries (how users will invoke it in natural language)\n- The planned structure of the skill:\n  - `SKILL.md` contents (sections, key instructions)\n  - Any `scripts/` you recommend (and what each script does)\n  - Any `references/` files (and when to read them)\n  - Any `assets/` (templates, fonts, icons, starter projects, etc.)\n\nValidate this design with the user before you start writing files. If something is ambiguous or high‑impact, ask a brief follow‑up question using `AskUserQuestion`.\n\n## 5. Create or update the skill files\n\nOnce the design is agreed upon:\n\n1. Determine the target directory for the skill (in this order):\n   - First, check whether the host environment or CLI has configured a default skills directory for this agent (for example via a `--skills` flag or project settings). If such a directory is provided, use it as the base directory for the new skill unless the user explicitly requests a different path.\n   - If no explicit skills directory is configured, check the `skills` memory block for a `Skills Directory: <path>` line and use that as the base directory.\n   - If neither is available, default to a local `.skills/<skill-id>/` directory in the current project root (or another path the user has requested).\n2. Create or update:\n   - `.skills/<skill-id>/SKILL.md` – the main entry point for the skill\n   - Optional: `.skills/<skill-id>/scripts/` – reusable scripts\n   - Optional: `.skills/<skill-id>/references/` – longer documentation, schemas, or examples\n   - Optional: `.skills/<skill-id>/assets/` – templates, fonts, images, or other resources\n3. Use file tools (Write, Edit, ApplyPatch, etc.) to create and refine these files instead of asking the user to do it manually.\n\nWhen writing `SKILL.md`, follow the conventions used by existing skills in this repository:\n\n- YAML frontmatter at the top, including at least:\n  - `name`: human‑readable name\n  - `description`: when and how the skill should be used\n- Clear sections that:\n  - Explain when to use the skill\n  - Describe the recommended workflows\n  - Link to `scripts/`, `references/`, and `assets/` as needed\n  - Emphasize progressive disclosure (only load detailed references as needed)\n\nKeep `SKILL.md` focused and concise; move long reference content into separate files.\n\n## 6. Keep questions focused and iterative\n\nThroughout the process:\n\n- Prefer a small number of **high‑impact questions** over many tiny questions.\n- When you need more detail, group follow‑up questions into a single `AskUserQuestion` call.\n- Use concrete examples from the user’s project or repository when possible.\n\nYour goal is to:\n\n1. Understand the desired skill thoroughly.\n2. Propose a clear, reusable design.\n3. Implement or update the actual skill files in the repository.\n4. 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.\n5. Leave the user with a ready‑to‑use skill that appears in the `skills` memory block and can be loaded with the `Skill` tool.';
+var skill_creator_mode_default = '# Skill Creation Mode\n\nThe user has invoked the `/skill` command. Your task is to help them **design and create a new Skill** for this project.\n\nYou are a Letta Code agent with:\n- Access to the current conversation, project files, and memory blocks\n- Access to the `Skill` tool (for loading skills) and `AskUserQuestion` (for asking clarifying questions)\n- Access to file tools (Read, Write, Edit, ApplyPatch, etc.) via the toolset\n\nYour goal is to guide the user through a **focused, collaborative workflow** to create or update a Skill that will be reused in the future.\n\n## 1. Load the creating-skills Skill (if available)\n\n1. Inspect your memory blocks:\n   - `skills` – list of available skills and their descriptions\n   - `loaded_skills` – SKILL.md contents for currently loaded skills\n2. If a `creating-skills` skill is **not already loaded** in `loaded_skills`, you should **attempt to load it** using the `Skill` tool:\n   - Call the `Skill` tool with:\n     - `command: "load", skills: ["creating-skills"]`\n   - The environment may resolve this from either the project’s `.skills` directory or a bundled `skills/skills/creating-skills/SKILL.md` location.\n3. If loading `creating-skills` 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.\n\nDo **not** load unrelated skills unless clearly relevant to the user’s request.\n\n## 2. Understand the requested skill\n\nThe `/skill` command may have been invoked in two ways:\n\n1. `/skill` (no description)\n2. `/skill <description>` (with a short description, e.g. `/skill image editor for marketing screenshots`)\n\nYou should always:\n\n1. Consider:\n   - The current conversation and what the user has been working on\n   - Relevant project context from files and memory blocks (especially `project` and `skills`)\n2. If a description was provided:\n   - Treat it as the **initial specification** of the skill.\n   - Restate it briefly in your own words to confirm understanding.\n\n## 3. Ask upfront clarifying questions (using AskUserQuestion)\n\nBefore you start proposing a concrete skill design, you MUST ask a small bundle of **high‑value upfront questions** using the `AskUserQuestion` tool.\n\nKeep the initial question set small (3–6 questions) and focused. Examples:\n\n1. Purpose and scope:\n   - “What is the main purpose of this skill?”\n   - “Is this skill meant for a specific project or to be reused across many projects?”\n2. Implementation details:\n   - “Do you want this skill to be mostly guidance (instructions) or to include reusable scripts/templates?”\n   - “Where should the skill live? (e.g. `.skills/your-skill-id` in this repo)”\n\nBundle these together in a single `AskUserQuestion` call. After you receive answers, you can ask follow‑up questions as needed, but avoid overwhelming the user.\n\n## 4. Propose a concrete skill design\n\nUsing:\n- The user’s description (if provided)\n- Answers to your questions\n- The current project and conversation context\n\nYou should propose a **concrete skill design**, including at minimum:\n\n- A skill ID (directory name), e.g. `image-editor`, `pdf-workflow`, `webapp-testing`\n- A concise human‑readable name\n- A one‑paragraph description focused on:\n  - What the skill does\n  - When it should be used\n  - Who is likely to use it\n- Example triggering queries (how users will invoke it in natural language)\n- The planned structure of the skill:\n  - `SKILL.md` contents (sections, key instructions)\n  - Any `scripts/` you recommend (and what each script does)\n  - Any `references/` files (and when to read them)\n  - Any `assets/` (templates, fonts, icons, starter projects, etc.)\n\nValidate this design with the user before you start writing files. If something is ambiguous or high‑impact, ask a brief follow‑up question using `AskUserQuestion`.\n\n## 5. Create or update the skill files\n\nOnce the design is agreed upon:\n\n1. Determine the target directory for the skill (in this order):\n   - First, check whether the host environment or CLI has configured a default skills directory for this agent (for example via a `--skills` flag or project settings). If such a directory is provided, use it as the base directory for the new skill unless the user explicitly requests a different path.\n   - If no explicit skills directory is configured, check the `skills` memory block for a `Skills Directory: <path>` line and use that as the base directory.\n   - If neither is available, default to a local `.skills/<skill-id>/` directory in the current project root (or another path the user has requested).\n2. Create or update:\n   - `.skills/<skill-id>/SKILL.md` – the main entry point for the skill\n   - Optional: `.skills/<skill-id>/scripts/` – reusable scripts\n   - Optional: `.skills/<skill-id>/references/` – longer documentation, schemas, or examples\n   - Optional: `.skills/<skill-id>/assets/` – templates, fonts, images, or other resources\n3. Use file tools (Write, Edit, ApplyPatch, etc.) to create and refine these files instead of asking the user to do it manually.\n\nWhen writing `SKILL.md`, follow the conventions used by existing skills in this repository:\n\n- YAML frontmatter at the top, including at least:\n  - `name`: human‑readable name\n  - `description`: when and how the skill should be used\n- Clear sections that:\n  - Explain when to use the skill\n  - Describe the recommended workflows\n  - Link to `scripts/`, `references/`, and `assets/` as needed\n  - Emphasize progressive disclosure (only load detailed references as needed)\n\nKeep `SKILL.md` focused and concise; move long reference content into separate files.\n\n## 6. Keep questions focused and iterative\n\nThroughout the process:\n\n- Prefer a small number of **high‑impact questions** over many tiny questions.\n- When you need more detail, group follow‑up questions into a single `AskUserQuestion` call.\n- Use concrete examples from the user’s project or repository when possible.\n\nYour goal is to:\n\n1. Understand the desired skill thoroughly.\n2. Propose a clear, reusable design.\n3. Implement or update the actual skill files in the repository.\n4. 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.\n5. Leave the user with a ready‑to‑use skill that appears in the `skills` memory block and can be loaded with the `Skill` tool.';
 var init_skill_creator_mode = () => {};
 
 // src/agent/prompts/skill_unload_reminder.txt
@@ -67691,7 +67691,7 @@ Press Enter to continue, or type anything to cancel.`, false, "running");
         const cmdId2 = uid4("cmd");
         const [, ...rest] = trimmed.split(/\s+/);
         const description = rest.join(" ").trim();
-        const initialOutput = description ? `Starting skill creation for: ${description}` : "Starting skill creation. I’ll load the skill-creator skill and ask a few questions about the skill you want to build...";
+        const initialOutput = description ? `Starting skill creation for: ${description}` : "Starting skill creation. I’ll load the creating-skills skill and ask a few questions about the skill you want to build...";
         buffersRef.current.byId.set(cmdId2, {
           kind: "command",
           id: cmdId2,
@@ -67868,10 +67868,10 @@ ${recentCommits}
           const initMessage = `<system-reminder>
 The user has requested memory initialization via /init.
 
-## 1. Load the memory-init skill
+## 1. Load the initializing-memory skill
 
-First, check your \`loaded_skills\` memory block. If the \`memory-init\` skill is not already loaded:
-1. Use the \`Skill\` tool with \`command: "load", skills: ["memory-init"]\`
+First, check your \`loaded_skills\` memory block. If the \`initializing-memory\` skill is not already loaded:
+1. Use the \`Skill\` tool with \`command: "load", skills: ["initializing-memory"]\`
 2. The skill contains comprehensive instructions for memory initialization
 
 If the skill fails to load, proceed with your best judgment based on these guidelines:
@@ -67882,7 +67882,7 @@ If the skill fails to load, proceed with your best judgment based on these guide
 
 ## 2. Follow the loaded skill instructions
 
-Once loaded, follow the instructions in the \`memory-init\` skill to complete the initialization.
+Once loaded, follow the instructions in the \`initializing-memory\` skill to complete the initialization.
 ${gitContext}
 </system-reminder>`;
           await processConversation([
@@ -71599,4 +71599,4 @@ Error during initialization: ${message}`);
 }
 main();
 
-//# debugId=26E346E807B8948664756E2164756E21
+//# debugId=CAAC5BC4B213F90764756E2164756E21

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@letta-ai/letta-code",
-  "version": "0.7.4-next.2",
+  "version": "0.7.4-next.3",
   "description": "Letta Code is a CLI tool for interacting with stateful Letta agents from the terminal.",
   "type": "module",
   "bin": {

package/skills/{skill-creator → creating-skills}/SKILL.md

@@ -1,11 +1,11 @@
 ---
-name: skill-creator
+name: creating-skills
 description: Guide for creating effective skills. This skill should be used when users want to create a new skill (or update an existing skill) that extends Letta Code's capabilities with specialized knowledge, workflows, or tool integrations.
 ---
 
-# Skill Creator
+# Creating Skills
 
-This skill provides guidance for creating effective skills in Letta Code.
+This skill provides guidance for creating effective skills in Letta Code. For the complete official specification, see [agentskills.io](https://agentskills.io/specification).
 
 ## About Skills
 
@@ -48,10 +48,10 @@ Think of the Letta Code agent as exploring a path: a narrow bridge with cliffs n
 Every skill consists of a required SKILL.md file and optional bundled resources:
 
 ```
-skill-name/
+processing-pdfs/
 ├── SKILL.md (required)
 │   ├── YAML frontmatter metadata (required)
-│   │   ├── name: (required)
+│   │   ├── name: (required, must match directory name)
 │   │   └── description: (required)
 │   └── Markdown instructions (required)
 └── Bundled Resources (optional)
@@ -148,9 +148,9 @@ The Letta Code agent loads FORMS.md, REFERENCE.md, or EXAMPLES.md only when need
 For Skills with multiple domains, organize content by domain to avoid loading irrelevant context:
 
 ```
-bigquery-skill/
+querying-bigquery/
 ├── SKILL.md (overview and navigation)
-└── reference/
+└── references/
     ├── finance.md (revenue, billing metrics)
     ├── sales.md (opportunities, pipeline)
     ├── product.md (API usage, features)
@@ -162,7 +162,7 @@ When a user asks about sales metrics, the Letta Code agent only reads sales.md.
 Similarly, for skills supporting multiple frameworks or variants, organize by variant:
 
 ```
-cloud-deploy/
+deploying-to-cloud/
 ├── SKILL.md (workflow + provider selection)
 └── references/
     ├── aws.md (AWS deployment patterns)
@@ -217,9 +217,9 @@ Skip this step only when the skill's usage patterns are already clearly understo
 
 To create an effective skill, clearly understand concrete examples of how the skill will be used. This understanding can come from either direct user examples or generated examples that are validated with user feedback.
 
-For example, when building an image-editor skill, relevant questions include:
+For example, when building an `editing-images` skill, relevant questions include:
 
-- "What functionality should the image-editor skill support? Editing, rotating, anything else?"
+- "What functionality should the editing-images skill support? Editing, rotating, anything else?"
 - "Can you give some examples of how this skill would be used?"
 - "I can imagine users asking for things like 'Remove the red-eye from this image' or 'Rotate this image'. Are there other ways you imagine this skill being used?"
 - "What would a user say that should trigger this skill?"
@@ -235,17 +235,17 @@ To turn concrete examples into an effective skill, analyze each example by:
 1. Considering how to execute on the example from scratch
 2. Identifying what scripts, references, and assets would be helpful when executing these workflows repeatedly
 
-Example: When building a `pdf-editor` skill to handle queries like "Help me rotate this PDF," the analysis shows:
+Example: When building an `editing-pdfs` skill to handle queries like "Help me rotate this PDF," the analysis shows:
 
 1. Rotating a PDF requires re-writing the same code each time
 2. A `scripts/rotate-pdf.ts` script would be helpful to store in the skill
 
-Example: When designing a `frontend-webapp-builder` skill for queries like "Build me a todo app" or "Build me a dashboard to track my steps," the analysis shows:
+Example: When designing a `building-frontend-apps` skill for queries like "Build me a todo app" or "Build me a dashboard to track my steps," the analysis shows:
 
 1. Writing a frontend webapp requires the same boilerplate HTML/React each time
 2. An `assets/hello-world/` template containing the boilerplate HTML/React project files would be helpful to store in the skill
 
-Example: When building a `big-query` skill to handle queries like "How many users have logged in today?" the analysis shows:
+Example: When building a `querying-bigquery` skill to handle queries like "How many users have logged in today?" the analysis shows:
 
 1. Querying BigQuery requires re-discovering the table schemas and relationships each time
 2. A `references/schema.md` file documenting the table schemas would be helpful to store in the skill
@@ -304,13 +304,27 @@ Any example files and directories not needed for the skill should be deleted. Th
 
 Write the YAML frontmatter with `name` and `description`:
 
-- `name`: The skill name
-- `description`: This is the primary triggering mechanism for your skill, and helps the Letta Code agent understand when to use the skill.
-  - Include both what the Skill does and specific triggers/contexts for when to use it.
-  - Include all "when to use" information here - Not in the body. The body is only loaded after triggering, so "When to Use This Skill" sections in the body are not helpful to the Letta Code agent.
-  - Example description for a `docx` skill: "Comprehensive document creation, editing, and analysis with support for tracked changes, comments, formatting preservation, and text extraction. Use when the Letta Code agent needs to work with professional documents (.docx files) for: (1) Creating new documents, (2) Modifying or editing content, (3) Working with tracked changes, (4) Adding comments, or any other document tasks"
+**`name`** (required):
+- Use gerund form: `processing-pdfs`, `analyzing-data`, `creating-reports` (not `pdf-processor`)
+- Lowercase letters, numbers, and hyphens only
+- Must match the directory name exactly
+- Max 64 characters
+
+**`description`** (required):
+- Write in third person: "Processes PDF files..." (not "I help process..." or "You can use this to...")
+- Include both what the skill does AND when to use it
+- Include trigger keywords that help the agent identify relevant tasks
+- Max 1024 characters
+
+Example:
+```yaml
+---
+name: processing-pdfs
+description: Extracts text and tables from PDF files, fills forms, and merges documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.
+---
+```
 
-Do not include any other fields in YAML frontmatter.
+**Note:** The spec allows optional fields (`license`, `compatibility`, `metadata`, `allowed-tools`) but most skills don't need them. See [agentskills.io/specification](https://agentskills.io/specification) for details.
 
 ##### Body
 

package/skills/{skill-creator → creating-skills}/scripts/validate-skill.ts

@@ -10,20 +10,22 @@
  */
 
 import { existsSync, readFileSync } from "node:fs";
-import { join } from "node:path";
+import { basename, join } from "node:path";
 import { parse as parseYaml } from "yaml";
 
 interface ValidationResult {
   valid: boolean;
   message: string;
+  warnings?: string[];
 }
 
 const ALLOWED_PROPERTIES = new Set([
   "name",
   "description",
   "license",
-  "allowed-tools",
+  "compatibility",
   "metadata",
+  "allowed-tools",
 ]);
 
 export function validateSkill(skillPath: string): ValidationResult {
@@ -63,15 +65,15 @@ export function validateSkill(skillPath: string): ValidationResult {
     };
   }
 
-  // Check for unexpected properties
+  // Check for unexpected properties (warn but don't fail for forward-compatibility)
+  const warnings: string[] = [];
   const unexpectedKeys = Object.keys(frontmatter).filter(
     (key) => !ALLOWED_PROPERTIES.has(key),
   );
   if (unexpectedKeys.length > 0) {
-    return {
-      valid: false,
-      message: `Unexpected key(s) in SKILL.md frontmatter: ${unexpectedKeys.sort().join(", ")}. Allowed properties are: ${[...ALLOWED_PROPERTIES].sort().join(", ")}`,
-    };
+    warnings.push(
+      `Unknown frontmatter key(s): ${unexpectedKeys.sort().join(", ")}. Known properties are: ${[...ALLOWED_PROPERTIES].sort().join(", ")}`,
+    );
   }
 
   // Check required fields
@@ -116,6 +118,14 @@ export function validateSkill(skillPath: string): ValidationResult {
         message: `Name is too long (${trimmedName.length} characters). Maximum is 64 characters.`,
       };
     }
+
+    // Check name matches directory name (warn if not)
+    const dirName = basename(skillPath);
+    if (trimmedName !== dirName) {
+      warnings.push(
+        `Name '${trimmedName}' doesn't match directory name '${dirName}'. For portability, these should match.`,
+      );
+    }
   }
 
   // Validate description
@@ -144,7 +154,11 @@ export function validateSkill(skillPath: string): ValidationResult {
     }
   }
 
-  return { valid: true, message: "Skill is valid!" };
+  return {
+    valid: true,
+    message: "Skill is valid!",
+    warnings: warnings.length > 0 ? warnings : undefined,
+  };
 }
 
 // CLI entry point
@@ -155,7 +169,12 @@ if (require.main === module) {
     process.exit(1);
   }
 
-  const { valid, message } = validateSkill(args[0] as string);
+  const { valid, message, warnings } = validateSkill(args[0] as string);
   console.log(message);
+  if (warnings && warnings.length > 0) {
+    for (const warning of warnings) {
+      console.warn(`Warning: ${warning}`);
+    }
+  }
   process.exit(valid ? 0 : 1);
 }

package/skills/{memory-init → initializing-memory}/SKILL.md

@@ -1,9 +1,9 @@
 ---
-name: Memory Initialization
+name: initializing-memory
 description: Comprehensive guide for initializing or reorganizing agent memory. Load this skill when running /init, when the user asks you to set up your memory, or when you need guidance on creating effective memory blocks.
 ---
 
-# Memory Initialization Guide
+# Initializing Memory
 
 The user has requested that you initialize or reorganize your memory state. You have access to the `memory` tool which allows you to create, edit, and manage memory blocks.