skill-tree 0.1.7 → 0.2.1

package/README.md

@@ -2,6 +2,33 @@
 
 A TypeScript library for managing agent skill versions and evolution. Store, version, serve, sync, and federate reusable skills for AI agents.
 
+## Metrics ownership (as of 0.2.0)
+
+skill-tree does **not** track per-skill usage metrics. The `Skill` shape no
+longer carries `metrics` — historical fields like `usageCount`, `successRate`,
+`lastUsed`, `feedbackScores` lived on it but were never updated by any code
+path in skill-tree, and the snapshots that consumers wrote at publish time
+drifted from the live data.
+
+Live usage tracking belongs to systems that observe agents running:
+- **cognitive-core** (`playbook.evolution.successCount` / `failureCount`,
+  `playbook.confidence`) is the canonical home. `recordSuccess` and
+  `recordFailure` mutate it on every trajectory.
+
+If you need ranked loadouts driven by live metrics, query that system
+first, then pass the resulting skill IDs to skill-tree's loadout compile
+via `include: [...]`. As of 0.2, `include` is a **presence guarantee** —
+every ID listed is in the result regardless of other filters, in the
+order specified. Combine with `maxSkills: include.length` for "exactly
+these N skills" semantics.
+
+skill-tree's `LoadoutCriteria` no longer supports `minSuccessRate` or
+`priorityOrder: 'usage' | 'successRate' | 'recent'` — the only
+recognized `priorityOrder` value is `'relevance'`, currently a no-op
+pending semantic ranking.
+
+See `CHANGELOG.md` for the full migration guide.
+
 ## Overview
 
 skill-tree helps you build and maintain a library of reusable skills for AI agents by:
@@ -45,7 +72,6 @@ await bank.saveSkill({
   createdAt: new Date(),
   updatedAt: new Date(),
   status: 'active',
-  metrics: { usageCount: 0, successRate: 0, feedbackScores: [] },
 } as Skill);
 
 // Search for skills
@@ -74,7 +100,6 @@ interface Skill {
   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
 }
 ```
@@ -215,6 +240,81 @@ await bank.federation.share('my-skill', 'team');
 const updates = await bank.federation.checkUpstream();
 ```
 
+### Importing from SkillNet
+
+Load skills from [SkillNet](https://github.com/zjunlp/SkillNet), a public index of
+GitHub-hosted SKILL.md skills. Search is free and needs no API key; each result is
+fetched directly from GitHub raw, parsed, and saved into the bank — fully versioned and
+servable like any other skill.
+
+```typescript
+import { createSkillNetClient } from 'skill-tree';
+
+const client = createSkillNetClient({
+  // githubToken: process.env.GITHUB_TOKEN,   // optional: private repos / rate limits
+  // githubMirror: 'https://ghfast.top/',     // optional: faster in restricted networks
+});
+
+// Search the index (keyword or semantic/vector)
+const results = await client.search('pdf', { mode: 'vector', threshold: 0.85, limit: 5 });
+
+// Import all matching skills into a SkillBank
+const summary = await client.importFromSearch('pdf', bank, { limit: 5 });
+console.log(`Imported ${summary.imported}, failed ${summary.failed}`);
+
+// Or import a single skill by its GitHub/SkillNet URL
+await client.importSkill(
+  'https://github.com/anthropics/skills/tree/main/skills/skill-creator',
+  bank,
+);
+```
+
+From the CLI:
+
+```bash
+# Search (free, no API key)
+skill-tree skillnet search "pdf" --mode vector --threshold 0.85
+
+# Import matching skills into the local bank
+skill-tree skillnet import "pdf" --limit 5
+
+# Import a single skill by URL
+skill-tree skillnet import --url https://github.com/owner/repo/tree/main/skills/foo
+```
+
+### Importing Local Skills
+
+Bulk-import SKILL.md skills from the filesystem — a single file or a directory tree of
+`<skill-id>/SKILL.md` folders (e.g. a downloaded skill pack, `.claude/skills/`, or any
+`skills/` directory). No network involved.
+
+```typescript
+import { importLocalSkillDir, importSkillMdFile, skillFromSkillMd } from 'skill-tree';
+
+// Import every SKILL.md found under a directory (recursive; skips hidden dirs)
+const result = await importLocalSkillDir('./downloaded-skills', bank);
+console.log(`Imported ${result.imported}, failed ${result.failed}`);
+
+// Import a single SKILL.md file (id derived from its folder name)
+await importSkillMdFile('./skills/deploy-helper/SKILL.md', bank);
+
+// Or just convert raw SKILL.md text to a Skill (source-agnostic, no I/O)
+const { skill, warnings } = skillFromSkillMd(rawMarkdown, { id: 'my-skill' });
+```
+
+From the CLI (the `import` command auto-detects directories and `.md` files):
+
+```bash
+# Import a directory of skills
+skill-tree import ./downloaded-skills
+
+# Import a single SKILL.md
+skill-tree import ./skills/deploy-helper/SKILL.md
+
+# Force SKILL.md mode for an unusual path
+skill-tree import ./some-path --skill-md
+```
+
 ### Events
 
 Subscribe to skill bank events: