skill-tree 0.0.1 → 0.1.0

package/README.md

@@ -1 +1,324 @@
-# skill-trees
+# skill-tree
+
+A TypeScript library for managing agent skill versions and evolution. Extract, iterate, and adapt skills from agent trajectories.
+
+## 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
+
+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).
+
+## Installation
+
+```bash
+npm install skill-tree
+```
+
+## Quick Start
+
+```typescript
+import { createSkillBank } from 'skill-tree';
+
+// Create a skill bank with filesystem storage
+const skillBank = createSkillBank({
+  storage: {
+    type: 'filesystem',
+    basePath: './skills',
+    openSkillsCompatible: true,
+  },
+});
+
+await skillBank.initialize();
+
+// Parse a Claude Code session
+const trajectory = await skillBank.parseSession(sessionContent);
+
+// Extract a skill manually
+const result = await skillBank.extractManual(trajectory, {
+  suggestedName: 'typescript-import-fix',
+  description: 'Fix TypeScript ES module import errors',
+  tags: ['typescript', 'imports'],
+});
+
+if (result.success) {
+  console.log('Extracted skill:', result.skill.name);
+}
+
+// Search for skills
+const skills = await skillBank.searchSkills('typescript error');
+
+// Create a new version
+const updated = await skillBank.createVersion('typescript-import-fix', {
+  solution: 'Updated solution...',
+}, { bumpType: 'minor' });
+```
+
+## Core Concepts
+
+### Skills
+
+A skill represents a reusable piece of knowledge extracted from agent interactions:
+
+```typescript
+interface Skill {
+  id: string;                    // Unique identifier
+  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;
+}
+```
+
+### 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):
+
+```typescript
+const skillBank = createSkillBank({
+  storage: {
+    type: 'filesystem',
+    basePath: '~/.skills',
+    openSkillsCompatible: true,  // YAML frontmatter + Markdown
+  },
+});
+```
+
+**Memory storage** (for testing):
+
+```typescript
+const skillBank = createSkillBank({
+  storage: { type: 'memory' },
+});
+```
+
+Skills are stored in the OpenSkills format:
+
+```
+skills/
+├── my-skill/
+│   ├── SKILL.md           # Skill content (YAML + Markdown)
+│   └── .skilltree.json    # Metadata and lineage
+└── .versions/
+    └── my-skill/
+        ├── 1.0.0.json     # Version snapshots
+        └── 1.1.0.json
+```
+
+### Versioning
+
+Semantic versioning with full lineage tracking:
+
+```typescript
+// Create new version
+const v2 = await skillBank.createVersion('my-skill', updates, {
+  bumpType: 'minor',
+  changelog: 'Added alternative solution',
+});
+
+// Get version history
+const history = await skillBank.getVersionHistory('my-skill');
+
+// Rollback to previous version
+const restored = await skillBank.rollbackSkill('my-skill', '1.0.0');
+
+// Compare versions
+const diff = await skillBank.compareVersions('my-skill', '1.0.0', '2.0.0');
+```
+
+### Skill Evolution
+
+Fork and merge skills:
+
+```typescript
+// Fork for a specialized use case
+const forked = await skillBank.forkSkill('my-skill', {
+  newId: 'my-skill-react',
+  newName: 'My Skill (React variant)',
+  reason: 'Specialized for React projects',
+});
+
+// Merge improvements back
+const merged = await skillBank.lineageTracker.mergeSkill(
+  'my-skill',
+  'my-skill-react',
+  { fields: ['solution', 'examples'] }
+);
+```
+
+### Events
+
+Subscribe to skill bank events:
+
+```typescript
+const unsubscribe = skillBank.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);
+      break;
+  }
+});
+```
+
+## API Reference
+
+### SkillBank
+
+Main orchestrator class.
+
+| 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 |
+| `getSkill(id, version?)` | Get skill by ID |
+| `listSkills(filter?)` | List skills with optional filter |
+| `searchSkills(query)` | Search skills by text |
+| `saveSkill(skill)` | Save or update a skill |
+| `deleteSkill(id, version?)` | Delete a skill |
+| `createVersion(id, updates, options?)` | Create new version |
+| `forkSkill(id, options)` | Fork a skill |
+| `getVersionHistory(id)` | Get version history |
+| `rollbackSkill(id, version)` | Rollback to version |
+| `on(handler)` | Subscribe to events |
+
+### Versioning Utilities
+
+```typescript
+import {
+  parseVersion,
+  compareVersions,
+  bumpVersion,
+  satisfiesRange,
+} from 'skill-tree';
+
+bumpVersion('1.2.3', 'minor');  // '1.3.0'
+satisfiesRange('1.5.0', '^1.2.0');  // true
+```
+
+## Skill Format
+
+Skills use YAML frontmatter + Markdown (OpenSkills-compatible):
+
+```markdown
+---
+name: typescript-esm-import-fix
+description: |
+  Fix TypeScript ES module import errors by adding .js extension
+version: 1.0.0
+author: extracted
+status: active
+date: 2024-01-15
+tags:
+  - typescript
+  - esm
+  - 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
+
+MIT