skill-tree 0.1.6 → 0.2.0

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
 }
 ```