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

package/skills/skill-creator/references/output-patterns.md

@@ -0,0 +1,82 @@
+# Output Patterns
+
+Use these patterns when skills need to produce consistent, high-quality output.
+
+## Template Pattern
+
+Provide templates for output format. Match the level of strictness to your needs.
+
+**For strict requirements (like API responses or data formats):**
+
+```markdown
+## Report structure
+
+ALWAYS use this exact template structure:
+
+# [Analysis Title]
+
+## Executive summary
+[One-paragraph overview of key findings]
+
+## Key findings
+- Finding 1 with supporting data
+- Finding 2 with supporting data
+- Finding 3 with supporting data
+
+## Recommendations
+1. Specific actionable recommendation
+2. Specific actionable recommendation
+```
+
+**For flexible guidance (when adaptation is useful):**
+
+```markdown
+## Report structure
+
+Here is a sensible default format, but use your best judgment:
+
+# [Analysis Title]
+
+## Executive summary
+[Overview]
+
+## Key findings
+[Adapt sections based on what you discover]
+
+## Recommendations
+[Tailor to the specific context]
+
+Adjust sections as needed for the specific analysis type.
+```
+
+## Examples Pattern
+
+For skills where output quality depends on seeing examples, provide input/output pairs:
+
+```markdown
+## Commit message format
+
+Generate commit messages following these examples:
+
+**Example 1:**
+Input: Added user authentication with JWT tokens
+Output:
+```
+feat(auth): implement JWT-based authentication
+
+Add login endpoint and token validation middleware
+```
+
+**Example 2:**
+Input: Fixed bug where dates displayed incorrectly in reports
+Output:
+```
+fix(reports): correct date formatting in timezone conversion
+
+Use UTC timestamps consistently across report generation
+```
+
+Follow this style: type(scope): brief description, then detailed explanation.
+```
+
+Examples help the Letta Code agent understand the desired style and level of detail more clearly than descriptions alone.

package/skills/skill-creator/references/workflows.md

@@ -0,0 +1,28 @@
+# Workflow Patterns
+
+## Sequential Workflows
+
+For complex tasks, break operations into clear, sequential steps. It is often helpful to give the Letta Code agent an overview of the process towards the beginning of SKILL.md:
+
+```markdown
+Filling a PDF form involves these steps:
+
+1. Analyze the form (run analyze-form.ts)
+2. Create field mapping (edit fields.json)
+3. Validate mapping (run validate-fields.ts)
+4. Fill the form (run fill-form.ts)
+5. Verify output (run verify-output.ts)
+```
+
+## Conditional Workflows
+
+For tasks with branching logic, guide the Letta Code agent through decision points:
+
+```markdown
+1. Determine the modification type:
+   **Creating new content?** → Follow "Creation workflow" below
+   **Editing existing content?** → Follow "Editing workflow" below
+
+2. Creation workflow: [steps]
+3. Editing workflow: [steps]
+```

package/skills/skill-creator/scripts/init-skill.ts

@@ -0,0 +1,279 @@
+#!/usr/bin/env npx ts-node
+/**
+ * Skill Initializer - Creates a new skill from template
+ *
+ * Usage:
+ *   npx ts-node init-skill.ts <skill-name> --path <path>
+ *
+ * Examples:
+ *   npx ts-node init-skill.ts my-new-skill --path .skills
+ *   npx ts-node init-skill.ts my-api-helper --path ~/.letta/skills
+ */
+
+import { chmodSync, existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+
+const SKILL_TEMPLATE = `---
+name: {skill_name}
+description: "[TODO: Complete and informative explanation of what the skill does and when to use it. Include WHEN to use this skill - specific scenarios, file types, or tasks that trigger it.]"
+---
+
+# {skill_title}
+
+## Overview
+
+[TODO: 1-2 sentences explaining what this skill enables]
+
+## Structuring This Skill
+
+[TODO: Choose the structure that best fits this skill's purpose. Common patterns:
+
+**1. Workflow-Based** (best for sequential processes)
+- Works well when there are clear step-by-step procedures
+- Example: DOCX skill with "Workflow Decision Tree" → "Reading" → "Creating" → "Editing"
+- Structure: ## Overview → ## Workflow Decision Tree → ## Step 1 → ## Step 2...
+
+**2. Task-Based** (best for tool collections)
+- Works well when the skill offers different operations/capabilities
+- Example: PDF skill with "Quick Start" → "Merge PDFs" → "Split PDFs" → "Extract Text"
+- Structure: ## Overview → ## Quick Start → ## Task Category 1 → ## Task Category 2...
+
+**3. Reference/Guidelines** (best for standards or specifications)
+- Works well for brand guidelines, coding standards, or requirements
+- Example: Brand styling with "Brand Guidelines" → "Colors" → "Typography" → "Features"
+- Structure: ## Overview → ## Guidelines → ## Specifications → ## Usage...
+
+**4. Capabilities-Based** (best for integrated systems)
+- Works well when the skill provides multiple interrelated features
+- Example: Product Management with "Core Capabilities" → numbered capability list
+- Structure: ## Overview → ## Core Capabilities → ### 1. Feature → ### 2. Feature...
+
+Patterns can be mixed and matched as needed. Most skills combine patterns (e.g., start with task-based, add workflow for complex operations).
+
+Delete this entire "Structuring This Skill" section when done - it's just guidance.]
+
+## [TODO: Replace with the first main section based on chosen structure]
+
+[TODO: Add content here. See examples in existing skills:
+- Code samples for technical skills
+- Decision trees for complex workflows
+- Concrete examples with realistic user requests
+- References to scripts/templates/references as needed]
+
+## Resources
+
+This skill includes example resource directories that demonstrate how to organize different types of bundled resources:
+
+### scripts/
+Executable code (TypeScript/Python/Bash/etc.) that can be run directly to perform specific operations.
+
+**Appropriate for:** Scripts that perform automation, data processing, or specific operations.
+
+**Note:** Scripts may be executed without loading into context, but can still be read by the Letta Code agent for patching or environment adjustments.
+
+### references/
+Documentation and reference material intended to be loaded into context to inform the Letta Code agent's process and thinking.
+
+**Appropriate for:** In-depth documentation, API references, database schemas, comprehensive guides, or any detailed information that the Letta Code agent should reference while working.
+
+### assets/
+Files not intended to be loaded into context, but rather used within the output the Letta Code agent produces.
+
+**Appropriate for:** Templates, boilerplate code, document templates, images, icons, fonts, or any files meant to be copied or used in the final output.
+
+---
+
+**Any unneeded directories can be deleted.** Not every skill requires all three types of resources.
+`;
+
+const EXAMPLE_SCRIPT = `#!/usr/bin/env npx ts-node
+/**
+ * Example helper script for {skill_name}
+ *
+ * This is a placeholder script that can be executed directly.
+ * Replace with actual implementation or delete if not needed.
+ */
+
+function main() {
+  console.log("This is an example script for {skill_name}");
+  // TODO: Add actual script logic here
+  // This could be data processing, file conversion, API calls, etc.
+}
+
+main();
+`;
+
+const EXAMPLE_REFERENCE = `# Reference Documentation for {skill_title}
+
+This is a placeholder for detailed reference documentation.
+Replace with actual reference content or delete if not needed.
+
+## When Reference Docs Are Useful
+
+Reference docs are ideal for:
+- Comprehensive API documentation
+- Detailed workflow guides
+- Complex multi-step processes
+- Information too lengthy for main SKILL.md
+- Content that's only needed for specific use cases
+
+## Structure Suggestions
+
+### API Reference Example
+- Overview
+- Authentication
+- Endpoints with examples
+- Error codes
+- Rate limits
+
+### Workflow Guide Example
+- Prerequisites
+- Step-by-step instructions
+- Common patterns
+- Troubleshooting
+- Best practices
+`;
+
+const EXAMPLE_ASSET = `# Example Asset File
+
+This placeholder represents where asset files would be stored.
+Replace with actual asset files (templates, images, fonts, etc.) or delete if not needed.
+
+Asset files are NOT intended to be loaded into context, but rather used within
+the output the Letta Code agent produces.
+
+## Common Asset Types
+
+- Templates: .pptx, .docx, boilerplate directories
+- Images: .png, .jpg, .svg, .gif
+- Fonts: .ttf, .otf, .woff, .woff2
+- Boilerplate code: Project directories, starter files
+- Icons: .ico, .svg
+- Data files: .csv, .json, .xml, .yaml
+
+Note: This is a text placeholder. Actual assets can be any file type.
+`;
+
+function titleCaseSkillName(skillName: string): string {
+  return skillName
+    .split("-")
+    .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+    .join(" ");
+}
+
+function initSkill(skillName: string, path: string): string | null {
+  const skillDir = resolve(path, skillName);
+
+  // Check if directory already exists
+  if (existsSync(skillDir)) {
+    console.error(`Error: Skill directory already exists: ${skillDir}`);
+    return null;
+  }
+
+  // Create skill directory
+  try {
+    mkdirSync(skillDir, { recursive: true });
+    console.log(`Created skill directory: ${skillDir}`);
+  } catch (e) {
+    console.error(
+      `Error creating directory: ${e instanceof Error ? e.message : String(e)}`,
+    );
+    return null;
+  }
+
+  const skillTitle = titleCaseSkillName(skillName);
+
+  // Create SKILL.md from template
+  const skillContent = SKILL_TEMPLATE.replace(
+    /{skill_name}/g,
+    skillName,
+  ).replace(/{skill_title}/g, skillTitle);
+
+  try {
+    writeFileSync(join(skillDir, "SKILL.md"), skillContent);
+    console.log("Created SKILL.md");
+  } catch (e) {
+    console.error(
+      `Error creating SKILL.md: ${e instanceof Error ? e.message : String(e)}`,
+    );
+    return null;
+  }
+
+  // Create resource directories with example files
+  try {
+    // Create scripts/ directory with example script
+    const scriptsDir = join(skillDir, "scripts");
+    mkdirSync(scriptsDir, { recursive: true });
+    const exampleScriptPath = join(scriptsDir, "example.ts");
+    writeFileSync(
+      exampleScriptPath,
+      EXAMPLE_SCRIPT.replace(/{skill_name}/g, skillName),
+    );
+    chmodSync(exampleScriptPath, 0o755);
+    console.log("Created scripts/example.ts");
+
+    // Create references/ directory with example reference doc
+    const referencesDir = join(skillDir, "references");
+    mkdirSync(referencesDir, { recursive: true });
+    writeFileSync(
+      join(referencesDir, "api-reference.md"),
+      EXAMPLE_REFERENCE.replace(/{skill_title}/g, skillTitle),
+    );
+    console.log("Created references/api-reference.md");
+
+    // Create assets/ directory with example asset placeholder
+    const assetsDir = join(skillDir, "assets");
+    mkdirSync(assetsDir, { recursive: true });
+    writeFileSync(join(assetsDir, "example-asset.txt"), EXAMPLE_ASSET);
+    console.log("Created assets/example-asset.txt");
+  } catch (e) {
+    console.error(
+      `Error creating resource directories: ${e instanceof Error ? e.message : String(e)}`,
+    );
+    return null;
+  }
+
+  // Print next steps
+  console.log(`\nSkill '${skillName}' initialized successfully at ${skillDir}`);
+  console.log("\nNext steps:");
+  console.log(
+    "1. Edit SKILL.md to complete the TODO items and update the description",
+  );
+  console.log(
+    "2. Customize or delete the example files in scripts/, references/, and assets/",
+  );
+  console.log("3. Run the validator when ready to check the skill structure");
+
+  return skillDir;
+}
+
+// CLI entry point
+if (require.main === module) {
+  const args = process.argv.slice(2);
+
+  if (args.length < 3 || args[1] !== "--path") {
+    console.log("Usage: npx ts-node init-skill.ts <skill-name> --path <path>");
+    console.log("\nSkill name requirements:");
+    console.log("  - Hyphen-case identifier (e.g., 'data-analyzer')");
+    console.log("  - Lowercase letters, digits, and hyphens only");
+    console.log("  - Max 64 characters");
+    console.log("  - Must match directory name exactly");
+    console.log("\nExamples:");
+    console.log("  npx ts-node init-skill.ts my-new-skill --path .skills");
+    console.log(
+      "  npx ts-node init-skill.ts my-api-helper --path ~/.letta/skills",
+    );
+    process.exit(1);
+  }
+
+  const skillName = args[0] as string;
+  const path = args[2] as string;
+
+  console.log(`Initializing skill: ${skillName}`);
+  console.log(`Location: ${path}\n`);
+
+  const result = initSkill(skillName, path);
+  process.exit(result ? 0 : 1);
+}
+
+export { initSkill, titleCaseSkillName };

package/skills/skill-creator/scripts/package-skill.ts

@@ -0,0 +1,268 @@
+#!/usr/bin/env npx ts-node
+/**
+ * Skill Packager - Creates a distributable .skill file of a skill folder
+ *
+ * Usage:
+ *   npx ts-node package-skill.ts <path/to/skill-folder> [output-directory]
+ *
+ * Example:
+ *   npx ts-node package-skill.ts .skills/my-skill
+ *   npx ts-node package-skill.ts .skills/my-skill ./dist
+ */
+
+import {
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  statSync,
+  writeFileSync,
+} from "node:fs";
+import { basename, dirname, join, relative, resolve } from "node:path";
+// Simple zip implementation using Node.js built-in zlib
+// For a proper zip file, we'll create the structure manually
+import { deflateSync } from "node:zlib";
+import { validateSkill } from "./validate-skill";
+
+interface ZipEntry {
+  path: string;
+  data: Buffer;
+  isDirectory: boolean;
+}
+
+function createZip(entries: ZipEntry[]): Buffer {
+  // Use archiver-like approach with raw buffer manipulation
+  // For simplicity, we'll use a basic ZIP format
+
+  const localHeaders: Buffer[] = [];
+  const centralHeaders: Buffer[] = [];
+  let offset = 0;
+
+  for (const entry of entries) {
+    const pathBuffer = Buffer.from(entry.path, "utf8");
+    const compressedData = entry.isDirectory
+      ? Buffer.alloc(0)
+      : deflateSync(entry.data);
+    const uncompressedSize = entry.isDirectory ? 0 : entry.data.length;
+    const compressedSize = compressedData.length;
+
+    // CRC32 calculation
+    const crc = entry.isDirectory ? 0 : crc32(entry.data);
+
+    // Local file header
+    const localHeader = Buffer.alloc(30 + pathBuffer.length);
+    localHeader.writeUInt32LE(0x04034b50, 0); // Local file header signature
+    localHeader.writeUInt16LE(20, 4); // Version needed to extract
+    localHeader.writeUInt16LE(0, 6); // General purpose bit flag
+    localHeader.writeUInt16LE(entry.isDirectory ? 0 : 8, 8); // Compression method (8 = deflate)
+    localHeader.writeUInt16LE(0, 10); // File last modification time
+    localHeader.writeUInt16LE(0, 12); // File last modification date
+    localHeader.writeUInt32LE(crc, 14); // CRC-32
+    localHeader.writeUInt32LE(compressedSize, 18); // Compressed size
+    localHeader.writeUInt32LE(uncompressedSize, 22); // Uncompressed size
+    localHeader.writeUInt16LE(pathBuffer.length, 26); // File name length
+    localHeader.writeUInt16LE(0, 28); // Extra field length
+    pathBuffer.copy(localHeader, 30);
+
+    localHeaders.push(localHeader);
+    localHeaders.push(compressedData);
+
+    // Central directory header
+    const centralHeader = Buffer.alloc(46 + pathBuffer.length);
+    centralHeader.writeUInt32LE(0x02014b50, 0); // Central directory signature
+    centralHeader.writeUInt16LE(20, 4); // Version made by
+    centralHeader.writeUInt16LE(20, 6); // Version needed to extract
+    centralHeader.writeUInt16LE(0, 8); // General purpose bit flag
+    centralHeader.writeUInt16LE(entry.isDirectory ? 0 : 8, 10); // Compression method
+    centralHeader.writeUInt16LE(0, 12); // File last modification time
+    centralHeader.writeUInt16LE(0, 14); // File last modification date
+    centralHeader.writeUInt32LE(crc, 16); // CRC-32
+    centralHeader.writeUInt32LE(compressedSize, 20); // Compressed size
+    centralHeader.writeUInt32LE(uncompressedSize, 24); // Uncompressed size
+    centralHeader.writeUInt16LE(pathBuffer.length, 28); // File name length
+    centralHeader.writeUInt16LE(0, 30); // Extra field length
+    centralHeader.writeUInt16LE(0, 32); // File comment length
+    centralHeader.writeUInt16LE(0, 34); // Disk number start
+    centralHeader.writeUInt16LE(0, 36); // Internal file attributes
+    centralHeader.writeUInt32LE(entry.isDirectory ? 0x10 : 0, 38); // External file attributes
+    centralHeader.writeUInt32LE(offset, 42); // Relative offset of local header
+    pathBuffer.copy(centralHeader, 46);
+
+    centralHeaders.push(centralHeader);
+
+    offset += localHeader.length + compressedData.length;
+  }
+
+  const centralDirOffset = offset;
+  const centralDirSize = centralHeaders.reduce((sum, h) => sum + h.length, 0);
+
+  // End of central directory record
+  const endRecord = Buffer.alloc(22);
+  endRecord.writeUInt32LE(0x06054b50, 0); // End of central directory signature
+  endRecord.writeUInt16LE(0, 4); // Number of this disk
+  endRecord.writeUInt16LE(0, 6); // Disk where central directory starts
+  endRecord.writeUInt16LE(entries.length, 8); // Number of central directory records on this disk
+  endRecord.writeUInt16LE(entries.length, 10); // Total number of central directory records
+  endRecord.writeUInt32LE(centralDirSize, 12); // Size of central directory
+  endRecord.writeUInt32LE(centralDirOffset, 16); // Offset of start of central directory
+  endRecord.writeUInt16LE(0, 20); // Comment length
+
+  return Buffer.concat([...localHeaders, ...centralHeaders, endRecord]);
+}
+
+// CRC32 implementation
+function crc32(data: Buffer): number {
+  let crc = 0xffffffff;
+  const table = getCrc32Table();
+
+  for (let i = 0; i < data.length; i++) {
+    // biome-ignore lint/style/noNonNullAssertion: array access within bounds
+    crc = (crc >>> 8) ^ (table[(crc ^ data[i]!) & 0xff] as number);
+  }
+
+  return (crc ^ 0xffffffff) >>> 0;
+}
+
+let crc32Table: number[] | null = null;
+function getCrc32Table(): number[] {
+  if (crc32Table) return crc32Table;
+
+  crc32Table = [];
+  for (let i = 0; i < 256; i++) {
+    let c = i;
+    for (let j = 0; j < 8; j++) {
+      c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+    }
+    crc32Table[i] = c;
+  }
+  return crc32Table;
+}
+
+function getAllFiles(dir: string, baseDir: string): ZipEntry[] {
+  const entries: ZipEntry[] = [];
+  const items = readdirSync(dir, { withFileTypes: true });
+
+  for (const item of items) {
+    const fullPath = join(dir, item.name);
+    const relativePath = relative(baseDir, fullPath);
+
+    if (item.isDirectory()) {
+      entries.push({
+        path: `${relativePath}/`,
+        data: Buffer.alloc(0),
+        isDirectory: true,
+      });
+      entries.push(...getAllFiles(fullPath, baseDir));
+    } else {
+      entries.push({
+        path: relativePath,
+        data: readFileSync(fullPath),
+        isDirectory: false,
+      });
+    }
+  }
+
+  return entries;
+}
+
+function packageSkill(skillPath: string, outputDir?: string): string | null {
+  const resolvedPath = resolve(skillPath);
+
+  // Validate skill folder exists
+  if (!existsSync(resolvedPath)) {
+    console.error(`Error: Skill folder not found: ${resolvedPath}`);
+    return null;
+  }
+
+  if (!statSync(resolvedPath).isDirectory()) {
+    console.error(`Error: Path is not a directory: ${resolvedPath}`);
+    return null;
+  }
+
+  // Validate SKILL.md exists
+  const skillMdPath = join(resolvedPath, "SKILL.md");
+  if (!existsSync(skillMdPath)) {
+    console.error(`Error: SKILL.md not found in ${resolvedPath}`);
+    return null;
+  }
+
+  // Run validation before packaging
+  console.log("Validating skill...");
+  const { valid, message } = validateSkill(resolvedPath);
+  if (!valid) {
+    console.error(`Validation failed: ${message}`);
+    console.error("Please fix the validation errors before packaging.");
+    return null;
+  }
+  console.log(`${message}\n`);
+
+  // Determine output location
+  const skillName = basename(resolvedPath);
+  const outputPath = outputDir ? resolve(outputDir) : process.cwd();
+
+  if (outputDir && !existsSync(outputPath)) {
+    mkdirSync(outputPath, { recursive: true });
+  }
+
+  const skillFilename = join(outputPath, `${skillName}.skill`);
+
+  // Create the .skill file (zip format)
+  try {
+    // Get all files, using parent directory as base so skill folder is included
+    const parentDir = dirname(resolvedPath);
+    const entries = getAllFiles(resolvedPath, parentDir);
+
+    // Add the skill directory itself
+    entries.unshift({
+      path: `${skillName}/`,
+      data: Buffer.alloc(0),
+      isDirectory: true,
+    });
+
+    const zipBuffer = createZip(entries);
+    writeFileSync(skillFilename, zipBuffer);
+
+    for (const entry of entries) {
+      if (!entry.isDirectory) {
+        console.log(`  Added: ${entry.path}`);
+      }
+    }
+
+    console.log(`\nSuccessfully packaged skill to: ${skillFilename}`);
+    return skillFilename;
+  } catch (e) {
+    console.error(
+      `Error creating .skill file: ${e instanceof Error ? e.message : String(e)}`,
+    );
+    return null;
+  }
+}
+
+// CLI entry point
+if (require.main === module) {
+  const args = process.argv.slice(2);
+
+  if (args.length < 1) {
+    console.log(
+      "Usage: npx ts-node package-skill.ts <path/to/skill-folder> [output-directory]",
+    );
+    console.log("\nExample:");
+    console.log("  npx ts-node package-skill.ts .skills/my-skill");
+    console.log("  npx ts-node package-skill.ts .skills/my-skill ./dist");
+    process.exit(1);
+  }
+
+  const skillPath = args[0] as string;
+  const outputDir = args[1];
+
+  console.log(`Packaging skill: ${skillPath}`);
+  if (outputDir) {
+    console.log(`Output directory: ${outputDir}`);
+  }
+  console.log();
+
+  const result = packageSkill(skillPath, outputDir);
+  process.exit(result ? 0 : 1);
+}
+
+export { packageSkill };