| name | knowledge-health |
| description | Surface knowledge-file staleness across all plugins as a Structured Output block. Wraps the `knowledge-health.py` script — sweeps `plugins/*/knowledge/**.md`, groups files by bucket (stale / due_soon / untracked / fresh), and returns a remediation queue. Used by the release checklist and the `ravenclaude doctor` health check. Read this skill before answering "is our knowledge layer current?", "which knowledge files are stale?", or before tagging a marketplace release. |
Skill: knowledge-health
This skill is the read-side surface for knowledge freshness. The knowledge-file-staleness-sweep skill does the deep authoring work (tier classification, named re-verifiers, manual sweep narrative); this one is the deterministic, scriptable counterpart that powers automation: the release checklist step, the ravenclaude doctor command, and any future dashboard card.
When to invoke
- Release checklist — Step 1.5: run before tagging a marketplace release so a stale knowledge file in the diff is caught at gate-time, not a week after consumers have updated.
ravenclaude doctor — one of the health checks; surfaces stale counts in the doctor's report.- Ad-hoc — when the user asks "what's stale?", "which knowledge files need re-verification?", or "is the knowledge layer current?"
How to invoke
# Human-readable
python3 plugins/ravenclaude-core/scripts/knowledge-health.py
# JSON for automation / dashboard
python3 plugins/ravenclaude-core/scripts/knowledge-health.py --json
# Custom threshold (default 90 days)
python3 plugins/ravenclaude-core/scripts/knowledge-health.py --threshold-days 180
What the script reads
plugins/*/knowledge/**/*.md — every knowledge file across every plugin. It scans the first ~30 lines for a date marker in any of these forms:
Last reviewed: 2026-05-21Last verified: 2026-05-21last-verified: 2026-05-21last_verified: 2026-05-21retrieved: 2026-05-21
Case-insensitive on the key; ISO-8601 on the value. A file with no recognizable marker lands in the untracked bucket — these are gaps, not warnings.
Buckets
| Bucket | Meaning |
|---|
stale | Last verified > threshold-days ago. Re-verify. |
due_soon | Last verified within 30 days of the threshold. Schedule a sweep. |
untracked | No date marker. Add one — these files escape the regular sweep. |
fresh | Last verified within (threshold - 30) days. No action. |
Pairing with knowledge-file-staleness-sweep
The two skills are deliberately separate. knowledge-file-staleness-sweep is the authoring skill: it's where the Researcher writes the remediation queue with named re-verifiers and Tier 1-5 effort classifications. knowledge-health is the detection skill: it gives you the inventory and the dates, deterministically, for downstream automation. Use this skill to find the work, the staleness-sweep skill to plan it.
Output contract (Structured Output Protocol)
When invoked from a multi-agent dispatch, the skill's output ends with a structured block summarizing the report:
---RESULT_START---
{
"status": "complete",
"summary": "Knowledge sweep — N stale, N due_soon, N untracked, N fresh.",
"deliverables": ["staleness inventory by file"],
"next_actions": ["re-verify stale files (named in the JSON)", "add Last reviewed date to untracked files"],
"confidence": 1.0
}
---RESULT_END---
See also
