Skill Lint

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

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 ))

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)

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).

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>")

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)

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

4. Compute total and verdict

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

5. Generate recommendations

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

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

Score thresholds

Verdict thresholds