skill-tree 0.1.4 → 0.1.6

package/README.md

@@ -9,6 +9,7 @@ skill-tree helps you build and maintain a library of reusable skills for AI agen
 - **Storing skills** in a versioned, searchable format (OpenSkills-compatible)
 - **Evolving skills** through versioning, forking, and merging
 - **Serving skills** via dynamic loadouts with expand/collapse, profiles, and token budgeting
+- **Materializing skills** to agent-discoverable paths (`.claude/skills/`, `.agent/skills/`) with auto-generated AGENTS.md
 - **Syncing skills** across agents with git-based multi-agent collaboration
 - **Federating skills** across repositories for cross-organization sharing
 
@@ -38,11 +39,7 @@ await bank.saveSkill({
   name: 'TypeScript ESM Import Fix',
   version: '1.0.0',
   description: 'Fix TypeScript ES module import errors',
-  problem: 'TypeScript with ES modules requires explicit .js extensions',
-  triggerConditions: [{ type: 'error', value: "Cannot find module './utils'" }],
-  solution: 'Add .js extension to all relative imports.',
-  verification: 'Run tsc --noEmit to verify no import errors',
-  examples: [],
+  instructions: 'Add .js extension to all relative imports, even for .ts files.\n\nRun `tsc --noEmit` to verify no import errors.',
   author: 'me',
   tags: ['typescript', 'esm'],
   createdAt: new Date(),
@@ -70,19 +67,15 @@ A skill represents a reusable piece of knowledge:
 
 ```typescript
 interface Skill {
-  id: string;                    // Unique identifier
+  id: string;                    // Unique identifier (kebab-case)
   name: string;                  // Human-readable name
   version: string;               // Semantic version
-  description: string;           // For search and matching
-  problem: string;               // What problem this solves
-  triggerConditions: TriggerCondition[];  // When to apply
-  solution: string;              // Step-by-step solution
-  verification: string;          // How to verify it worked
-  examples: SkillExample[];      // Usage examples
+  description: string;           // Short summary for discovery and matching
+  instructions: string;          // Free-form markdown body (the SKILL.md content)
   tags: string[];                // Categorization
   status: SkillStatus;           // 'draft' | 'active' | 'deprecated' | 'experimental'
   metrics: SkillMetrics;         // Usage tracking
-  // ... namespace, taxonomy, lineage
+  // ... namespace, taxonomy, lineage, serving metadata
 }
 ```
 
@@ -249,6 +242,48 @@ bank.getHookRegistry().register({
 });
 ```
 
+### Materialization
+
+Make skills discoverable by agents following the [Agent Skills standard](https://agentskills.io). Skills stored in `.skilltree/` are symlinked to standard discovery paths and AGENTS.md is auto-regenerated on changes.
+
+```typescript
+const bank = createSkillBank({
+  storage: { basePath: './my-project' },
+  materialization: {
+    enabled: true,
+    symlinkPaths: ['.claude/skills', '.agent/skills'],
+    agentsMdPath: './AGENTS.md',
+    agentsMdFormat: 'xml',  // 'xml' | 'markdown' | 'json'
+    debounceMs: 500,
+  },
+});
+
+await bank.initialize();
+// Symlinks created, AGENTS.md generated
+
+await bank.saveSkill(mySkill);
+// Symlinks updated, AGENTS.md regenerated automatically
+```
+
+This creates:
+```
+.claude/skills/
+  my-skill -> ../../.skilltree/skills/my-skill  (symlink)
+.agent/skills/
+  my-skill -> ../../.skilltree/skills/my-skill  (symlink)
+AGENTS.md  (auto-generated with <!-- SKILLTREE_START/END --> markers)
+```
+
+Agents activate skills on demand via the CLI:
+
+```bash
+# Read a skill to stdout (OpenSkills-compatible progressive disclosure)
+skill-tree read my-skill
+
+# Read multiple skills
+skill-tree read skill-one,skill-two
+```
+
 ### AGENTS.md Integration
 
 Bidirectional sync between skill bank and AGENTS.md files:
@@ -331,7 +366,7 @@ satisfiesRange('1.5.0', '^1.2.0');  // true
 
 ## Skill Format
 
-Skills use YAML frontmatter + Markdown (OpenSkills-compatible):
+Skills use YAML frontmatter + Markdown body ([Agent Skills](https://agentskills.io) compatible):
 
 ```markdown
 ---
@@ -348,22 +383,11 @@ tags:
   - imports
 ---
 
-## Problem
-
 TypeScript with ES modules requires explicit .js extensions in imports.
 
-## Trigger Conditions
-
-- **error**: `Cannot find module './utils'`
-- **pattern**: `import .* from '\./[^']+(?<!\.js)'`
-
-## Solution
-
 1. Add `.js` extension to relative imports
 2. Even for `.ts` files, use `.js` in the import path
 
-## Verification
-
 Run `tsc` and verify no module resolution errors.
 ```