@axiom-lattice/core 2.1.56 → 2.1.57

package/dist/index.mjs

@@ -4837,6 +4837,285 @@ import { tool as tool38 } from "langchain";
 // src/tool_lattice/skill/load_skill_content.ts
 import z42 from "zod";
 import { tool as tool39 } from "langchain";
+
+// src/skill_lattice/builtinSkills.ts
+var BUILTIN_SKILLS = {
+  "create-skill": `---
+name: create-skill
+description: Create new skills, modify and improve existing skills. Use this skill whenever users mention creating a skill, wanting a new capability, asking to "make a skill for X", setting up automated workflows, or wanting to capture repeatable agent instructions \u2014 even if they don't use the word "skill."
+license: MIT
+metadata:
+  category: meta
+  version: "2.0"
+---
+
+# Skill Creator
+
+This skill guides you through creating and improving agent skills. Your job is to figure out where the user is in the process and help them progress \u2014 whether they're starting from scratch, have a rough idea, or want to improve an existing skill.
+
+At a high level, the process follows an iterative loop: **understand intent \u2192 interview \u2192 draft \u2192 test \u2192 review \u2192 improve \u2192 repeat** until satisfied. But always be flexible \u2014 if the user says "just vibe with me," do that instead.
+
+## Communicating With the User
+
+Users range from deep technical experts to people who just learned what a terminal is. Pay attention to context cues:
+- "JSON" and "assertion" \u2014 only use without explanation if the user shows comfort with them
+- "evaluation" and "benchmark" \u2014 borderline, briefly define if unsure
+- When in doubt, briefly explain terms. Short parenthetical definitions are fine.
+
+---
+
+## Step 1: Capture Intent
+
+Start by understanding what the user wants. The current conversation may already contain a workflow they want to capture (e.g., they say "turn this into a skill"). If so, extract answers from the conversation history first \u2014 the tools used, the sequence of steps, corrections made, input/output formats observed.
+
+Ask yourself:
+1. What capability does this skill enable?
+2. When should this skill trigger? (what user phrases, contexts, keywords)
+3. What is the expected output or behavior?
+4. Does it coordinate other skills (subSkills)?
+
+## Step 2: Interview and Research
+
+Proactively ask questions before writing anything:
+- **Edge cases**: What unusual inputs might arise? What should happen on failure?
+- **Input/output formats**: What formats are involved (files, data, text)?
+- **Dependencies**: Are specific tools, APIs, or data sources needed?
+- **Success criteria**: How will the user know the skill is working?
+
+Don't start writing until you've got clear answers. If the user is vague, ask clarifying questions \u2014 you'll save time by not guessing wrong.
+
+---
+
+## Step 3: Write the SKILL.md
+
+### Skill Directory Structure
+
+Skills use progressive disclosure \u2014 three levels of loading:
+
+\`\`\`
+skill-name/
+\u251C\u2500\u2500 SKILL.md              # Required \u2014 frontmatter + markdown body
+\u2514\u2500\u2500 resources/            # Optional \u2014 bundled files
+    \u251C\u2500\u2500 scripts/          # Executable code for repetitive tasks
+    \u251C\u2500\u2500 references/       # Docs loaded into context as needed
+    \u2514\u2500\u2500 assets/           # Files used in output (templates, icons)
+\`\`\`
+
+- **Metadata** (name + description) \u2014 always in context (~100 words)
+- **SKILL.md body** \u2014 loaded when skill triggers (aim for <500 lines)
+- **Bundled resources** \u2014 loaded as needed, unlimited
+
+If SKILL.md approaches 500 lines, add hierarchy with clear pointers to reference files.
+
+### File Location
+
+Write the skill to: \`/root/.agents/skills/{skill-name}/SKILL.md\`
+
+Resources go in: \`/root/.agents/skills/{skill-name}/resources/\`
+
+### Naming Rules
+
+Skill names (also the directory name) must follow these rules:
+- 1-64 characters, lowercase letters, digits, single hyphens
+- Pattern: \`^[a-z0-9]+(-[a-z0-9]+)*$\`
+- Cannot start or end with \`-\`, cannot contain consecutive \`--\`
+
+**Good**: \`pdf-processor\`, \`sql-query\`, \`code-review\`, \`data-analytics\`
+**Bad**: \`PDF-Processor\`, \`sql__query\`, \`-test\`, \`a\`
+
+### Frontmatter Reference
+
+\`\`\`yaml
+---
+name: my-skill-name         # Required \u2014 kebab-case identifier
+description: ...            # Required \u2014 what AND when (this drives triggering)
+license: MIT                # Optional
+compatibility: node         # Optional \u2014 runtime/context requirement
+metadata:                   # Optional \u2014 key-value tags for search/filter
+  category: tools
+  version: "1.0"
+subSkills:                  # Optional \u2014 coordinated sub-skill names
+  - sub-skill-1
+---
+
+# Markdown Body
+
+Instructional content for the agent.
+\`\`\`
+
+---
+
+## Writing Guide
+
+### The Description Field
+
+This is the most critical part. The description is the primary mechanism that determines whether an agent invokes your skill. Combine WHAT the skill does with specific contexts for WHEN to trigger.
+
+Agents tend to **undertrigger** \u2014 to not use skills when they'd be useful. To combat this, make descriptions a little "pushy":
+
+- Weak: "Helps with PDF files"
+- Better: "Extract text, tables, and metadata from PDF files. Use when users need to read, parse, or extract data from PDF documents."
+- Good: "Extract text, tables, and metadata from PDF files. Make sure to use this skill whenever the user mentions PDFs, extracting document data, or needs to read any kind of document file \u2014 even if they don't explicitly ask for 'PDF processing.'"
+
+Include domain-specific trigger words: file extensions, tool names, common user phrases.
+
+### Writing the Body
+
+Prefer **imperative form**. Write what the agent should DO, not what the skill IS:
+- "Check the database connection and verify table schemas" \u2014 good
+- "The database connection is checked and table schemas are verified" \u2014 weak
+
+**Explain WHY**, not just what. Use theory of mind \u2014 help the model understand the reasoning behind instructions so it can generalize to novel situations. If you find yourself writing ALWAYS or NEVER in all caps, that's a yellow flag \u2014 reframe and explain the reasoning.
+
+**Use examples** to ground abstract instructions:
+
+\`\`\`markdown
+## Commit message format
+**Example 1:**
+Input: Added user authentication with JWT tokens
+Output: feat(auth): implement JWT-based authentication
+\`\`\`
+
+**Define output formats** explicitly when structure matters:
+
+\`\`\`markdown
+## Report structure
+ALWAYS use this exact template:
+# [Title]
+## Executive summary
+## Key findings
+## Recommendations
+\`\`\`
+
+### Body Structure Checklist
+
+A well-written skill body typically includes:
+- **Role definition**: What role does the agent play when executing this skill?
+- **Workflow**: Step-by-step process in a clear sequence
+- **Guidelines**: Rules, constraints, quality standards, and the WHY behind them
+- **Scenarios**: 2-3 common scenarios with concrete examples of inputs and expected outputs
+- **Edge cases**: What to do when things go wrong, when data is missing, etc.
+
+---
+
+## Step 4: Test and Iterate
+
+After writing the draft, test it:
+
+1. **Create 2-3 test prompts** \u2014 the kind of thing a real user would actually say. Share them with the user: "Here are a few test cases I'd like to try. Do these look right?"
+2. **Run the skill** against each test prompt to see what the agent produces
+3. **Review outputs with the user**: evaluate both qualitatively (does the output look right?) and quantitatively (did it follow the workflow? use the right tools?)
+4. **Collect feedback**: What worked? What didn't? What surprised the user?
+
+### Improving the Skill
+
+When iterating based on feedback:
+
+1. **Generalize from feedback** \u2014 don't overfit to the test cases. The skill will be used across many different prompts. If a fix only helps one specific example, think bigger.
+2. **Keep it lean** \u2014 remove instructions that aren't pulling their weight. Read the full transcripts, not just final outputs. If the skill makes the agent waste time, trim it.
+3. **Look for repeated work** \u2014 if all test runs involved writing the same helper script, bundle that script into \`resources/scripts/\` and have the skill reference it instead.
+4. **Explain the why** \u2014 if you're adding a constraint because of a failure, explain the context so the model understands when to apply it and when it's safe to deviate.
+
+Repeat the test \u2192 review \u2192 improve loop until the user is satisfied.
+
+---
+
+## Step 5: Optimize the Description (Optional)
+
+After the skill works well, offer to optimize the description for better triggering accuracy.
+
+### How Triggering Works
+
+The agent sees skills as a list of name + description pairs. It decides whether to consult a skill based on that description. Important: agents only consult skills for tasks they can't easily handle on their own. Simple one-step queries may not trigger a skill even if the description matches \u2014 so make sure the description emphasizes the COMPLEX or SPECIALIZED nature of the task.
+
+### Optimization Approach
+
+1. Create 10-15 eval queries \u2014 a mix of should-trigger and should-not-trigger prompts
+2. For **should-trigger** (6-8): different phrasings of the same intent \u2014 formal, casual, indirect. Include cases where the user doesn't explicitly name the skill but clearly needs it
+3. For **should-not-trigger** (6-8): focus on near-misses \u2014 queries that share keywords but need something different. Don't make them obviously irrelevant
+4. Test the description against these queries and adjust based on misfires
+5. Show the user before/after and explain what changed
+
+---
+
+## Step 6: Package and Present
+
+When the skill is ready:
+1. Verify the SKILL.md is at \`/root/.agents/skills/{skill-name}/SKILL.md\` with correct frontmatter
+2. Confirm all resource files are in place under \`resources/\`
+3. Tell the user the skill is ready and available at its path
+4. Remind them that the skill will now appear in the available skills list for any agent using the skill system
+
+## Updating Existing Skills
+
+When the user wants to improve an existing skill:
+1. Read the current SKILL.md from \`/root/.agents/skills/{skill-name}/SKILL.md\`
+2. Understand what it currently does and where it falls short
+3. Follow the same interview \u2192 draft \u2192 test \u2192 iterate loop
+4. **Preserve the original name** \u2014 the directory name and \`name\` frontmatter field should stay the same
+5. Write the updated version back to the same path
+
+---
+
+## Example Walkthrough
+
+**User**: "I want a skill that helps me analyze CSV data"
+
+**You** (interview):
+- "What kinds of analysis \u2014 summary stats, filtering, charting?"
+- "Are the CSVs always the same format or varied?"
+- "Should it output results as text, new CSV, or visualizations?"
+
+**User**: "Mostly summary stats and filtering. The files vary but all have headers."
+
+**You** (draft frontmatter):
+\`\`\`yaml
+---
+name: csv-analyzer
+description: Analyze CSV data with statistical summaries, filtering, and aggregation. Use whenever users want to explore, summarize, or extract insights from CSV files \u2014 even if they don't say "analyze" explicitly.
+metadata:
+  category: data
+  version: "1.0"
+---
+\`\`\`
+
+**You** (draft body): Write a workflow that teaches the agent to:
+1. Inspect the CSV structure and headers
+2. Let the user choose analysis type (summary, filter, aggregate)
+3. Execute the analysis and present results clearly
+4. Handle edge cases: missing headers, empty files, mixed types
+
+**You** (write): Create \`/root/.agents/skills/csv-analyzer/SKILL.md\`
+
+**You** (test): "Here are 3 test cases \u2014 'summarize this sales CSV', 'filter rows where region is West', 'show monthly revenue trends'. Let me run these and we'll review."
+
+Then iterate based on what the user says.
+`
+};
+function getBuiltInSkillMeta(name) {
+  const content = BUILTIN_SKILLS[name];
+  if (!content) return null;
+  try {
+    const { meta } = parseSkillFrontmatter(content);
+    return meta;
+  } catch {
+    return null;
+  }
+}
+function getBuiltInSkillContent(name) {
+  return BUILTIN_SKILLS[name];
+}
+function getAllBuiltInSkillMetas() {
+  return Object.keys(BUILTIN_SKILLS).map((name) => getBuiltInSkillMeta(name)).filter((meta) => meta !== null);
+}
+function getBuiltInSkillNames() {
+  return Object.keys(BUILTIN_SKILLS);
+}
+function isBuiltInSkill(name) {
+  return name in BUILTIN_SKILLS;
+}
+
+// src/tool_lattice/skill/load_skill_content.ts
 var LOAD_SKILL_CONTENT_DESCRIPTION = `
 Execute a skill within the main conversation
 
@@ -4877,6 +5156,11 @@ var createLoadSkillContentTool = () => {
   return tool39(
     async (input, _exe_config) => {
       try {
+        const builtInContent = getBuiltInSkillContent(input.skill_name);
+        if (builtInContent) {
+          const { meta: meta2, body: body2 } = parseSkillFrontmatter(builtInContent);
+          return buildSkillFile(meta2, body2);
+        }
         const sandbox = await getSandboxFromExeConfig(_exe_config);
         const filePath = `/root/.agents/skills/${input.skill_name}/SKILL.md`;
         let content;
@@ -4934,6 +5218,7 @@ function createSkillMiddleware(params = {}) {
       createLoadSkillContentTool()
     ],
     beforeAgent: async (state, runtime) => {
+      let resolvedSkills = [];
       try {
         const runConfig = runtime?.context?.runConfig || {};
         const manager = getSandBoxManager();
@@ -4963,13 +5248,24 @@ function createSkillMiddleware(params = {}) {
           }
         }
         if (readAll) {
-          latestSkills = allSkills;
+          resolvedSkills = allSkills;
         } else if (skills && skills.length > 0) {
-          latestSkills = allSkills.filter((skill) => skills.includes(skill.id));
+          resolvedSkills = allSkills.filter((skill) => skills.includes(skill.id));
+        } else {
+          resolvedSkills = allSkills;
         }
       } catch (error) {
         console.error("Error fetching skills:", error);
       }
+      const builtinMetas = getAllBuiltInSkillMetas();
+      for (const meta of builtinMetas) {
+        resolvedSkills.push({
+          id: meta.name,
+          name: meta.name,
+          description: meta.description
+        });
+      }
+      latestSkills = resolvedSkills;
     },
     wrapModelCall: (request, handler) => {
       const skillsPrompt = latestSkills.filter((skill) => !!skill.name).map((skill) => `## ${skill.name}
@@ -16468,6 +16764,39 @@ var SandboxSkillStore = class {
       projectId: options.projectId
     };
   }
+  /**
+   * Build a Skill object from a built-in skill definition.
+   */
+  _builtInSkill(name, tenantId) {
+    const content = getBuiltInSkillContent(name);
+    if (!content) return null;
+    const { meta } = parseSkillFrontmatter(content);
+    const now = /* @__PURE__ */ new Date();
+    return {
+      id: meta.name || name,
+      tenantId,
+      name: meta.name || name,
+      description: meta.description || "",
+      license: meta.license,
+      compatibility: meta.compatibility,
+      metadata: meta.metadata || {},
+      content,
+      subSkills: meta.subSkills,
+      createdAt: now,
+      updatedAt: now
+    };
+  }
+  /**
+   * Get all built-in skills as Skill objects for a tenant.
+   */
+  _allBuiltInSkills(tenantId) {
+    const skills = [];
+    for (const name of Object.keys(BUILTIN_SKILLS)) {
+      const skill = this._builtInSkill(name, tenantId);
+      if (skill) skills.push(skill);
+    }
+    return skills;
+  }
   /**
    * Get sandbox manager
    */
@@ -16604,17 +16933,25 @@ ${body}` : `${frontmatter}
           }
         }
       }
+      const builtInSkills = this._allBuiltInSkills(tenantId);
+      for (const bis of builtInSkills) {
+        if (!skills.some((s) => s.id === bis.id)) {
+          skills.push(bis);
+        }
+      }
       console.log(`[SandboxSkillStore] Loaded ${skills.length} skills for tenant ${tenantId}`);
       return skills.sort((a, b) => b.createdAt.getTime() - a.createdAt.getTime());
     } catch (error) {
       console.error(`[SandboxSkillStore] Error listing skills for tenant ${tenantId}:`, error);
-      return [];
+      return this._allBuiltInSkills(tenantId);
     }
   }
   /**
     * Get skill by ID
     */
   async getSkillById(tenantId, id, context) {
+    const builtIn = this._builtInSkill(id, tenantId);
+    if (builtIn) return builtIn;
     return this.readSkillFile(tenantId, id, context);
   }
   /**
@@ -16622,6 +16959,11 @@ ${body}` : `${frontmatter}
     */
   async createSkill(tenantId, id, data, context) {
     validateSkillName(data.name);
+    if (isBuiltInSkill(data.name)) {
+      throw new Error(
+        `Skill "${data.name}" is a built-in skill and cannot be overwritten`
+      );
+    }
     if (id !== data.name) {
       throw new Error(
         `Skill id "${id}" must equal name "${data.name}" (name is used for path addressing)`
@@ -16652,6 +16994,11 @@ ${body}` : `${frontmatter}
     * Update an existing skill
     */
   async updateSkill(tenantId, id, updates, context) {
+    if (isBuiltInSkill(id)) {
+      throw new Error(
+        `Skill "${id}" is a built-in skill and cannot be modified`
+      );
+    }
     const skill = await this.readSkillFile(tenantId, id, context);
     if (!skill) {
       return null;
@@ -16694,6 +17041,11 @@ ${body}` : `${frontmatter}
     * Delete a skill by ID
     */
   async deleteSkill(tenantId, id, context) {
+    if (isBuiltInSkill(id)) {
+      throw new Error(
+        `Skill "${id}" is a built-in skill and cannot be deleted`
+      );
+    }
     try {
       const sandbox = await this.getSandbox(tenantId, context);
       const dirPath = this.getSkillDirectoryPath(tenantId, id);
@@ -16713,6 +17065,7 @@ ${body}` : `${frontmatter}
     * Check if skill exists
     */
   async hasSkill(tenantId, id, context) {
+    if (isBuiltInSkill(id)) return true;
     const skill = await this.getSkillById(tenantId, id, context);
     return skill !== null;
   }
@@ -19328,6 +19681,7 @@ export {
   AgentLatticeManager,
   AgentManager,
   AgentType,
+  BUILTIN_SKILLS,
   ChunkBuffer,
   ChunkBufferLatticeManager,
   CompositeBackend,
@@ -19438,7 +19792,11 @@ export {
   getAgentClient,
   getAgentConfig,
   getAllAgentConfigs,
+  getAllBuiltInSkillMetas,
   getAllToolDefinitions,
+  getBuiltInSkillContent,
+  getBuiltInSkillMeta,
+  getBuiltInSkillNames,
   getCheckpointSaver,
   getChunkBuffer,
   getEmbeddingsClient,
@@ -19460,6 +19818,7 @@ export {
   grepMatchesFromFiles,
   grepSearchFiles,
   hasChunkBuffer,
+  isBuiltInSkill,
   isUsingDefaultKey,
   isValidCronExpression,
   isValidSandboxName,