skill-lint

name	skill-lint
description	Score all skills for staleness using 5 dimensions (freshness, usage, integrity, format, dependencies). Reports CURRENT/STALE/BROKEN/DELETE verdicts with specific recommendations. TRIGGER when: asked to audit skills, check skill health, "are my skills stale", "skill lint", or periodically via heartbeat.

Skill Lint

Score every skill across two scopes on 5 deterministic dimensions and produce a CURRENT / STALE / BROKEN / DELETE verdict for each. No LLM judgment — scores come from file stats, grep counts, and path existence checks only.

Instructions

1. Parse target

Arguments received: $ARGUMENTS

Argument	Scope
all (default, or empty)	Root scope + workspace scope
root	/home/sandbox/harness/.claude/skills/ only
workspace	/home/sandbox/harness/workspace/.claude/skills/ only
<skill-name>	Single skill, auto-detect scope

2. Discover skills

# Root scope
ROOT_SKILLS=$(find /home/sandbox/harness/.claude/skills -name "SKILL.md" -maxdepth 3 2>/dev/null)

# Workspace scope
WS_SKILLS=$(find /home/sandbox/harness/workspace/.claude/skills -name "SKILL.md" -maxdepth 3 2>/dev/null)

Build a list of (skill-name, scope-label, skill-dir, skill-file) tuples. Scope label is root or ws.

3. Score each skill on 5 dimensions

For every skill file, compute dimensions independently using only shell commands and file checks.

---

Dimension A — Freshness (0-2)

# Get modification time as Unix timestamp
MTIME=$(stat -c %Y "<skill-file>")
NOW=$(date +%s)
AGE_DAYS=$(( (NOW - MTIME) / 86400 ))

Age	Score
<= 7 days	2
8 – 30 days	1
31+ days	0

---

Dimension B — Usage (0-2)

# Count daily memory logs that mention this skill name (case-insensitive)
SKILL_NAME="<skill-name>"
MENTION_COUNT=$(grep -rli "$SKILL_NAME" /home/sandbox/harness/memory/ 2>/dev/null | wc -l)

Mentions	Score
>= 2 log files	2
1 log file	1
0 log files	0

---

Dimension C — Integrity (0-2)

Scan the SKILL.md body for references to paths and skill invocations, then verify existence.

# Extract all bare absolute paths (e.g. /home/sandbox/harness/...)
PATH_REFS=$(grep -oP '`[^`]*`|"[^"]*"' "<skill-file>" | grep -oP '/[a-zA-Z0-9_./-]+' | sort -u)

# Extract skill invocations (e.g. /release, /ci-status, /agent-browser)
SKILL_REFS=$(grep -oP '/[a-z][a-z0-9-]+' "<skill-file>" | grep -v '^/home' | sort -u)

For each extracted path reference: check [ -e "<path>" ]. For each skill reference like /foo-bar: check whether <root>/.claude/skills/foo-bar/SKILL.md or <ws>/.claude/skills/foo-bar/SKILL.md exists.

Count total broken references (BROKEN_COUNT).

Broken refs	Score
0	2
1 – 2	1
3+	0

---

Dimension D — Format (0-2)

# Check for YAML frontmatter (opening --- block)
HAS_FM=$(grep -c '^---$' "<skill-file>" | awk '{print ($1 >= 2) ? "yes" : "no"}')

# Check for memory protocol section
HAS_MEM=$(grep -c '## Memory Protocol\|## \[.*\] — HH:MM UTC\|Memory Improvement Protocol' "<skill-file>")

# Check for guidelines section
HAS_GL=$(grep -c '^## Guidelines\|^## Important Notes\|^## Reference' "<skill-file>")

Conditions	Score
Has frontmatter AND memory protocol AND at least one of guidelines/reference	2
Has frontmatter, missing memory protocol	1
Missing frontmatter (--- block absent)	0

---

Dimension E — Dependencies (0-2)

Dependencies are skill references found in step C (SKILL_REFS). For each referenced skill:

1. If the skill exists, look up its total score (computed in this run, or estimate from freshness if not yet scored)
2. Classify the referenced skill's score using the verdict thresholds (see step 4)

Dep state	Score
No dependencies, OR all deps score >= 6 (CURRENT/STALE but functional)	2
1+ deps score 3-5 (STALE/warning)	1
1+ deps deleted OR score <= 2 (BROKEN/DELETE)	0

If a skill has no cross-skill references, assign score 2.

---

4. Compute total and verdict

TOTAL = A + B + C + D + E   (max 10)

Total	Verdict
8 – 10	CURRENT
5 – 7	STALE
3 – 4	BROKEN
0 – 2	DELETE

5. Generate recommendations

For each skill that is not CURRENT, produce one concrete recommendation line. Use this decision table:

Primary signal	Recommendation template
Format score = 0	Missing frontmatter — add YAML block with name/description
Integrity score = 0	Fix broken references — N paths/skills no longer exist
Freshness = 0, Usage = 0	Never triggered and not updated in 30+ days — remove or redesign
Usage = 0, Freshness >= 1	Never triggered — confirm still needed or add to a heartbeat
Deps score = 0	Depends on deleted or dead skills — update or remove cross-skill calls
Freshness = 0, Format < 2	Pattern drift — rewrite to current conventions

If multiple signals apply, pick the highest-impact one (integrity > format > deps > freshness > usage).

6. Emit report

Print today's date as YYYY-MM-DD (use date +%F).

## Skill Lint — YYYY-MM-DD

### Summary
N skills scanned | M CURRENT | S STALE | B BROKEN | D DELETE

### Scores
| Skill | Scope | Fresh | Usage | Integ | Fmt | Deps | Total | Verdict |
|-------|-------|-------|-------|-------|-----|------|-------|---------|
| <name> | root | A | B | C | D | E | T | VERDICT |
...

### Recommendations
- **DELETE**: <skill> — <reason>
- **BROKEN**: <skill> — <reason>
- **STALE**: <skill> — <reason>

Sort the Scores table by Total ascending (worst first). Omit CURRENT skills from the Recommendations section — they need no action.

7. Memory Protocol

Append to memory/YYYY-MM-DD/log.md where today = date -u +%Y-%m-%d:

## [Skill Lint] — HH:MM UTC
- **Result**: OP
- **Action**: scored N skills
- **Current**: M | **Stale**: S | **Broken**: B | **Delete**: D
- **Observation**: [one sentence — top finding]

See context/rules/memory.md for the canonical Memory Improvement Protocol.

Guidelines

• Scoring is fully deterministic — run the same commands twice and get the same scores. Do not adjust scores based on content quality or subjective judgment.
• Run Dimension E (Dependencies) last, after all other dimensions are scored, so referenced-skill scores are available without a second pass.
• When checking integrity references, skip references to standard Unix paths (/bin, /usr, /home/sandbox/harness itself as a directory) — only flag references to specific files or skills that do not exist.
• A skill that is the target of argument-hint: "all | root | workspace | <skill-name>" style hints should not be penalized for referencing those placeholder tokens.
• For the single-skill target mode ($ARGUMENTS = a skill name), run all 5 dimensions and emit the same table for just that skill, plus its recommendation.
• Heartbeat coverage is a bonus signal, not a scored dimension — note it in the Recommendation line if a skill has 0 usage and no heartbeat reference in workspace/heartbeats/.

Reference

Scope paths

Scope	Skills root
root	/home/sandbox/harness/.claude/skills/
ws	/home/sandbox/harness/workspace/.claude/skills/

Score thresholds

Dimension	2 (healthy)	1 (warning)	0 (stale)
Freshness	<= 7 days	8-30 days	31+ days
Usage	2+ log mentions	1 log mention	0 mentions
Integrity	0 broken refs	1-2 broken refs	3+ broken refs
Format	FM + memory protocol + guidelines/ref	FM only	No FM
Dependencies	All deps score >= 6 or none	Deps score 3-5	Deps deleted or score <= 2

Verdict thresholds

Score	Verdict	Action
8-10	CURRENT	No action needed
5-7	STALE	Review and update — may have drifted from current patterns
3-4	BROKEN	Fix broken references or rewrite — will fail if triggered
0-2	DELETE	Dead weight — remove or completely redesign