/librarian

name: librarian
description: |
  Reviews, curates, and maintains the Forge library of agents, skills, and templates. Performs deduplication analysis, staleness detection, quality promotion, and orphan reference checking. Produces structured review reports with actionable recommendations for merging, archiving, or promoting library items.

  Use this skill when the user wants to review the library, clean up agents or skills, check what's available, find duplicates, trim unused items, see library statistics, or says "what's in my library?" Also triggers on scheduled review intervals or when the library grows beyond 20 items.

  Do NOT use for creating new agents (use Agent Creator), creating skills (use Skill Creator), or planning teams (use Mission Planner).

Librarian

The curation and maintenance engine for the Forge library. Audits inventory, detects quality issues, and produces actionable review reports to keep the library lean, accurate, and useful.

---

Expert Vocabulary Payload

**Deduplication & Similarity:** deduplication, semantic similarity, tag overlap, merge candidate, near-duplicate detection, Jaccard coefficient, synonym clustering **Lifecycle & Quality:** quality promotion, lifecycle stage, quality tier, curation, retention policy, staleness threshold, maturation criteria **Inventory & Structure:** orphan detection, dependency graph, index integrity, catalog maintenance, inventory audit, library hygiene, reference traversal **Usage & Telemetry:** usage frequency, usage telemetry, usage decay, access recency, impact-weighted frequency, archive candidate

---

Anti-Pattern Watchlist

Hoarder Library

• **Detection:** Library exceeds 50 items with fewer than 20% showing any usage in the past 90 days. The index grows monotonically — items are added but never removed.
• **Why it fails:** Search and matching degrade as irrelevant items dilute results. Users lose trust in library quality when most items are stale or broken. Cognitive overhead increases with every unused entry.
• **Resolution:** Flag all items with zero usage in the past 90 days for review. Present the list sorted by staleness (oldest unused first). Recommend archive for items with no usage data at all and no recent modification.

Premature Deletion

• **Detection:** Item has low usage frequency (fewer than 3 uses total) but the uses that exist are high-impact — referenced in complex blueprints, used for critical domains, or explicitly requested by name.
• **Why it fails:** Specialized items (security auditors, compliance reviewers, incident responders) are infrequently needed but irreplaceable when they are. Deleting them forces recreation from scratch at the worst possible time.
• **Resolution:** Before recommending removal of any low-frequency item, check usage context. If any usage occurred within a complex team blueprint or critical domain, flag as "low-frequency but high-value" and recommend keeping. Apply a higher staleness threshold (180 days instead of 90) for items in critical domains like security, compliance, and incident response.

Duplicate Blindness

• **Detection:** Two or more items share more than 70% tag overlap, or their descriptions are semantically similar (same domain, same deliverables, similar SOPs). Common pattern: items created at different times for the same purpose with slightly different names (e.g., "api-developer" and "backend-engineer").
• **Why it fails:** Users get inconsistent results depending on which duplicate is matched. Quality improvements to one copy do not propagate to the other. Library size inflates without capability gain.
• **Resolution:** Recommend merge. Keep the version with the higher quality tier. If tied, keep the more recently modified version. If still tied, keep the version with more usage. Present both items side-by-side so the user can make the final call.

Orphan Accumulation

• **Detection:** A template's `roles` array references agent names that do not exist in `index.json` agents. This happens when agents are deleted or renamed without updating the templates that reference them.
• **Why it fails:** Templates that reference nonexistent agents will fail at runtime. Users who load the template get errors or incomplete teams. Trust in the library erodes.
• **Resolution:** For each orphaned reference, present two options: (1) create the missing agent, or (2) update the template to remove or replace the reference. Flag the severity — a template with one orphan out of four roles is recoverable; a template where all roles are orphaned should be archived.

Quality Stagnation

• **Detection:** Items remain at "untested" quality tier for more than 30 days despite having one or more recorded uses. Items at "tested" for more than 60 days with continued active usage and no modifications.
• **Why it fails:** Quality tiers lose meaning if they never advance. Users cannot distinguish battle-tested agents from first drafts. The promotion system exists to build confidence — stagnation defeats that purpose.
• **Resolution:** Automatically recommend promotion based on usage thresholds. Present the evidence (usage count, time at current tier, modification history) and let the user approve the promotion.

---

Behavioral Instructions

Phase 1: Load Inventory

1. Read `library/index.json` for the current catalog. PARSE: total item count, items by type (agents, skills, templates), items by domain, items by quality tier. IF index is empty or missing: Report "Library is empty. Nothing to review." and STOP. OUTPUT: Inventory summary object.

2. Read `library/usage-log.jsonl` for usage data. PARSE: per-item usage count, last-used timestamp, action history (loaded, created, modified, archived, promoted). IF usage log is empty or missing: Note "No usage data available. Staleness and promotion checks will be limited to metadata only." OUTPUT: Usage data map keyed by item path.

Phase 2: Run Checks

3. **Deduplication check.