skill-tree 0.1.3 → 0.1.5

package/README.md

@@ -1,15 +1,17 @@
 # skill-tree
 
-A TypeScript library for managing agent skill versions and evolution. Extract, iterate, and adapt skills from agent trajectories.
+A TypeScript library for managing agent skill versions and evolution. Store, version, serve, sync, and federate reusable skills for AI agents.
 
 ## Overview
 
 skill-tree helps you build and maintain a library of reusable skills for AI agents by:
 
-- **Extracting skills** from agent sessions/trajectories (manual or automatic)
 - **Storing skills** in a versioned, searchable format (OpenSkills-compatible)
 - **Evolving skills** through versioning, forking, and merging
-- **Quality gates** to ensure extracted skills are reusable and non-trivial
+- **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
 
 Inspired by research on skill libraries ([arXiv:2512.17102](https://arxiv.org/abs/2512.17102)), [Claudeception](https://github.com/blader/Claudeception), and [OpenSkills](https://github.com/numman-ali/openskills).
 
@@ -22,139 +24,73 @@ npm install skill-tree
 ## Quick Start
 
 ```typescript
-import { createSkillBank } from 'skill-tree';
+import { createSkillBank, type Skill } from 'skill-tree';
 
 // Create a skill bank with filesystem storage
-const skillBank = createSkillBank({
-  storage: {
-    type: 'filesystem',
-    basePath: './skills',
-    openSkillsCompatible: true,
-  },
+const bank = createSkillBank({
+  storage: { basePath: './skills' },
 });
 
-await skillBank.initialize();
-
-// Parse a Claude Code session
-const trajectory = await skillBank.parseSession(sessionContent);
+await bank.initialize();
 
-// Extract a skill manually
-const result = await skillBank.extractManual(trajectory, {
-  suggestedName: 'typescript-import-fix',
+// Save a skill
+await bank.saveSkill({
+  id: 'typescript-esm-import-fix',
+  name: 'TypeScript ESM Import Fix',
+  version: '1.0.0',
   description: 'Fix TypeScript ES module import errors',
-  tags: ['typescript', 'imports'],
-});
-
-if (result.success) {
-  console.log('Extracted skill:', result.skill.name);
-}
+  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(),
+  updatedAt: new Date(),
+  status: 'active',
+  metrics: { usageCount: 0, successRate: 0, feedbackScores: [] },
+} as Skill);
 
 // Search for skills
-const skills = await skillBank.searchSkills('typescript error');
+const skills = await bank.searchSkills('typescript');
 
 // Create a new version
-const updated = await skillBank.createVersion('typescript-import-fix', {
-  solution: 'Updated solution...',
+const updated = await bank.createVersion('typescript-esm-import-fix', {
+  solution: 'Add .js extension, or use "moduleResolution": "bundler".',
 }, { bumpType: 'minor' });
+
+await bank.shutdown();
 ```
 
 ## Core Concepts
 
 ### Skills
 
-A skill represents a reusable piece of knowledge extracted from agent interactions:
+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 semantic 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
-  // ... metadata, metrics, lineage
-}
-```
-
-### Trajectories
-
-Agent sessions are parsed into trajectories:
-
-```typescript
-interface Trajectory {
-  sessionId: string;
-  turns: Turn[];       // User/assistant/tool interactions
-  metadata: TrajectoryMetadata;
-  outcome?: TrajectoryOutcome;
+  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, serving metadata
 }
 ```
 
-### Quality Gates
-
-Extraction includes quality gates (inspired by Claudeception) to ensure skills are:
-
-- **Reusable**: Applicable across multiple future tasks
-- **Non-trivial**: Involves discovery beyond documentation lookup
-- **Specific**: Has clear trigger conditions
-- **Verified**: Solution demonstrably works
-
-## Features
-
-### Session Adapters
-
-Parse different agent session formats:
-
-```typescript
-// Built-in: Claude Code JSONL
-const trajectory = await skillBank.parseSession(jsonlContent);
-
-// Register custom adapters
-skillBank.registerAdapter(myCustomAdapter);
-```
-
-### Extraction Modes
-
-**Manual extraction** with user guidance:
-
-```typescript
-const result = await skillBank.extractManual(trajectory, {
-  turnRange: [5, 15],           // Extract specific turns
-  suggestedName: 'my-skill',
-  tags: ['debugging'],
-});
-```
-
-**Automatic extraction** using LLM:
-
-```typescript
-skillBank.setLLMProvider(myLLMProvider);
-
-const results = await skillBank.extractAutomatic(trajectory, {
-  minConfidence: 0.7,
-});
-```
-
 ### Storage
 
-**Filesystem storage** (OpenSkills-compatible):
+Two backends:
 
 ```typescript
-const skillBank = createSkillBank({
-  storage: {
-    type: 'filesystem',
-    basePath: '~/.skills',
-    openSkillsCompatible: true,  // YAML frontmatter + Markdown
-  },
+// Filesystem (JSON source of truth + SQLite cache)
+const bank = createSkillBank({
+  storage: { basePath: './skills' },
 });
-```
 
-**Memory storage** (for testing):
-
-```typescript
-const skillBank = createSkillBank({
+// Memory (for testing)
+const bank = createSkillBank({
   storage: { type: 'memory' },
 });
 ```
@@ -172,45 +108,111 @@ skills/
         └── 1.1.0.json
 ```
 
+## Features
+
 ### Versioning
 
 Semantic versioning with full lineage tracking:
 
 ```typescript
 // Create new version
-const v2 = await skillBank.createVersion('my-skill', updates, {
+const v2 = await bank.createVersion('my-skill', updates, {
   bumpType: 'minor',
   changelog: 'Added alternative solution',
 });
 
 // Get version history
-const history = await skillBank.getVersionHistory('my-skill');
+const history = await bank.getVersionHistory('my-skill');
 
 // Rollback to previous version
-const restored = await skillBank.rollbackSkill('my-skill', '1.0.0');
+const restored = await bank.rollbackSkill('my-skill', '1.0.0');
 
 // Compare versions
-const diff = await skillBank.compareVersions('my-skill', '1.0.0', '2.0.0');
-```
-
-### Skill Evolution
+const diff = await bank.compareVersions('my-skill', '1.0.0', '2.0.0');
 
-Fork and merge skills:
-
-```typescript
 // Fork for a specialized use case
-const forked = await skillBank.forkSkill('my-skill', {
+const forked = await bank.forkSkill('my-skill', {
   newId: 'my-skill-react',
   newName: 'My Skill (React variant)',
   reason: 'Specialized for React projects',
 });
+```
+
+### Serving Layer
+
+Dynamic skill loadouts for agent context windows:
+
+```typescript
+const { server } = await bank.createServingLayer({
+  maxExpanded: 5,
+});
+
+// Orchestrator sets loadout based on task
+await server.setLoadoutForTask('Fix authentication bug');
+
+// Or use a built-in profile
+await server.setLoadoutFromProfile('debugging');
+
+// Render skills into system prompt
+const prompt = server.renderSystemPrompt();
+
+// Agent-side API
+const view = server.agentListLoadout();
+const skill = server.agentExpandSkill('some-skill-id');
+server.agentCollapseSkill('some-skill-id');
+await server.agentRequestSkills(['another-skill']);
+```
+
+### Multi-Agent Sync
+
+Git-based skill synchronization:
+
+```typescript
+import { createDefaultSyncConfig } from 'skill-tree';
+
+const bank = createSkillBank({
+  storage: { basePath: './skills' },
+  sync: {
+    config: createDefaultSyncConfig({
+      repoUrl: 'git@github.com:org/skills.git',
+      agentId: 'agent-1',
+    }),
+    pullOnInit: true,
+  },
+});
+
+await bank.initialize(); // auto-pulls remote changes
+
+// Manual sync
+await bank.sync.push();
+await bank.sync.pull();
+const status = await bank.sync.status();
+
+await bank.shutdown(); // flushes pending sync
+```
+
+### Federation
+
+Connect independent skill repositories:
+
+```typescript
+// Add a remote
+await bank.federation.addRemote('team', {
+  url: 'git@github.com:org/team-skills.git',
+  access: 'read-write',
+});
+
+// Browse remote skills
+const remoteSkills = await bank.federation.browse('team');
+
+// Import a skill
+const result = await bank.federation.import('team', 'useful-pattern');
 
-// Merge improvements back
-const merged = await skillBank.lineageTracker.mergeSkill(
-  'my-skill',
-  'my-skill-react',
-  { fields: ['solution', 'examples'] }
-);
+// Share a skill
+await bank.federation.share('my-skill', 'team');
+
+// Check for upstream updates
+const updates = await bank.federation.checkUpstream();
 ```
 
 ### Events
@@ -218,40 +220,135 @@ const merged = await skillBank.lineageTracker.mergeSkill(
 Subscribe to skill bank events:
 
 ```typescript
-const unsubscribe = skillBank.on((event) => {
+// Simple synchronous listeners
+const unsubscribe = bank.on((event) => {
   switch (event.type) {
     case 'skill:created':
       console.log('New skill:', event.skill.name);
       break;
-    case 'extraction:completed':
-      console.log('Extraction confidence:', event.result.confidence);
+    case 'skill:updated':
+      console.log('Updated:', event.skill.name, 'from', event.previousVersion);
       break;
   }
 });
+
+// Advanced: async hooks with priority and filtering
+bank.getHookRegistry().register({
+  event: 'storage:after-save',
+  handler: async (context) => {
+    console.log('Skill saved to storage');
+  },
+  priority: 'normal',
+});
+```
+
+### 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:
+
+```typescript
+import { createAgentsSync } from 'skill-tree';
+
+const sync = createAgentsSync(bank.getStorage());
+const result = await sync.sync('./AGENTS.md', {
+  direction: 'bidirectional',
+});
+```
+
+### Namespace Support
+
+Multi-tier skill trees for team environments:
+
+```typescript
+const bank = createSkillBank({
+  storage: { basePath: './skills' },
+  namespace: {
+    agentId: 'agent-1',
+    team: 'frontend',
+    defaultScope: 'personal',
+    defaultVisibility: 'private',
+  },
+});
+
+// List skills by scope
+const personal = await bank.listSkills({ scope: 'personal', owner: 'agent-1' });
+const teamSkills = await bank.listSkills({ scope: 'team', team: 'frontend' });
 ```
 
 ## API Reference
 
 ### SkillBank
 
-Main orchestrator class.
+Main orchestrator class, created via `createSkillBank(config)`.
 
 | Method | Description |
 |--------|-------------|
-| `initialize()` | Initialize storage (required before use) |
-| `parseSession(content, adapter?)` | Parse session into trajectory |
-| `extractManual(trajectory, options?)` | Extract skill with guidance |
-| `extractAutomatic(trajectory, options?)` | Extract skills using LLM |
+| `initialize()` | Initialize storage, federation, and sync |
+| `shutdown()` | Clean shutdown (flushes sync) |
 | `getSkill(id, version?)` | Get skill by ID |
 | `listSkills(filter?)` | List skills with optional filter |
-| `searchSkills(query)` | Search skills by text |
+| `searchSkills(query)` | Full-text search |
 | `saveSkill(skill)` | Save or update a skill |
 | `deleteSkill(id, version?)` | Delete a skill |
+| `deprecateSkill(id)` | Mark skill as deprecated |
 | `createVersion(id, updates, options?)` | Create new version |
 | `forkSkill(id, options)` | Fork a skill |
 | `getVersionHistory(id)` | Get version history |
+| `getLineage(id)` | Get full lineage |
 | `rollbackSkill(id, version)` | Rollback to version |
-| `on(handler)` | Subscribe to events |
+| `compareVersions(id, vA, vB)` | Diff two versions |
+| `on(handler)` | Subscribe to events (returns unsubscribe fn) |
+| `off(handler)` | Unsubscribe from events |
+| `getStats()` | Get skill bank statistics |
+| `exportAll()` | Export all skills |
+| `importSkills(skills)` | Bulk import skills |
+| `createServingLayer(config?)` | Create a SkillGraphServer |
+| `getStorage()` | Access underlying storage adapter |
+| `getHookRegistry()` | Access hook registry |
+| `sync` | SyncManager accessor (throws if not configured) |
+| `federation` | FederationManager accessor (requires basePath) |
 
 ### Versioning Utilities
 
@@ -269,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
 ---
@@ -286,37 +383,12 @@ 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.
-
-## Examples
-
-### Basic import fix
-
-**Before:**
-```typescript
-import { helper } from './utils'
-```
-
-**After:**
-```typescript
-import { helper } from './utils.js'
-```
 ```
 
 ## License