feat(template): evidence-based knowledge governance — scan-usage skill + meta-skill admission standards

[BobbyZhouZijian]

Motivation

Inspired by the "library drift" line of work on self-evolving skill libraries (arXiv:2605.19576): ungoverned LLM-authored skills contribute roughly nothing on their own — the value comes from governance, i.e. evidence-based curation at retirement time and strict admission at birth time. CORAL already has the roles (librarian subagent, skill-creator, create-notes) but their decisions were disconnected from outcome evidence. This PR wires them together.

What's in here

1. scan-usage bundled skill — usage attribution from agent logs

Instead of asking agents to self-report which notes/skills they used, scripts/scan_usage.py scans every agent's session log (.claude/logs/*.log, NDJSON) and counts agent-initiated tool calls touching notes/ and skills/:

• Read / Bash cat|sed|grep of a specific note → read; Write/Edit and shell redirects (>, tee) → write; Glob/Grep → browse
• Skill tool invocations, reads/executions under skills/<name>/, coral skills --read <name> → skill use (authoring a skill is not a use)
• Tool results are ignored, so ls notes/ output doesn't mark every note as read
• Diffs against disk to report never-read notes and never-used skills; per-agent breakdown; --json
• Tolerant of codex-style command-execution JSONL; known blind spot documented (subagent tool calls aren't visible in logs)

The librarian template now runs this scan before touching anything, and applies an evidence floor: archive only on sustained zero reads with real run activity behind it (premature retirement destroys knowledge), never delete.

2. Meta-skill admission standards (skill-creator/references/meta-skill.md)

A five-point admission gate applied before drafting any new skill — recurrence evidence (≥3 occurrences or 2+ agents), outcome link (tied to scores/time saved, with citable evidence), beyond base-model competence, no existing home (70%+ overlap → update instead; unused adjacent skill → fix its description, don't birth a sibling), generalizes past the current task-state — plus skill-vs-note placement rules, scope/description standards, and lifecycle expectations. Both authoring paths (skill-creator and the librarian's extract-skills step) route through it.

3. Same principles applied to note creation (create-notes)

A "Before You Write — Admission and Placement" check: search for an existing home first (update / refutes: / supersedes: instead of forking near-duplicates; per-eval experiment notes stay append-only), route repeatable procedures to skill-creator's gate, and design for discovery — since the librarian's usage scan archives notes nobody reads.

Tests

• tests/test_scan_usage.py — 15 cases for the scanner (read/write/browse semantics, redirect detection, tool-result immunity, codex events, agent attribution, CLI e2e)
• tests/test_meta_skill.py — regression gate that the admission wiring survives future prompt edits (skill-creator, librarian, create-notes)
• Full suite: 636 passed, 1 skipped; ruff clean

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
coral	Ready	Preview, Comment	Jul 10, 2026 2:56pm