Skill Stocktake

To include project-level skills, run from that project's root directory:

cd ~/path/to/my-project
run the tool surface that invokes `skill-stocktake`

If the project has no repo-local skill directory for the active tool, only global skills and commands are evaluated.

Modes

Results cache: <config>/skills/skill-stocktake/results.json

Quick Scan Flow

Re-evaluate only skills that have changed since the last run (5–10 min).

1. Read <config>/skills/skill-stocktake/results.json
2. Run: node <config>/skills/skill-stocktake/scripts/quick-diff.js <config>/skills/skill-stocktake/results.json (Project dir is auto-detected from supported repo-local skill directories; override via SKILL_STOCKTAKE_PROJECT_DIR if needed)
3. If output is []: report "No changes since last run." and stop
4. Re-evaluate only those changed files using the same Phase 2 criteria
5. Carry forward unchanged skills from previous results
6. Output only the diff
7. Run: node <config>/skills/skill-stocktake/scripts/save-results.js <config>/skills/skill-stocktake/results.json with EVAL_RESULTS on stdin

Full Stocktake Flow

Phase 1 — Inventory

Run: node <config>/skills/skill-stocktake/scripts/scan.js

The script enumerates skill files, extracts frontmatter, and collects UTC mtimes. Project dir is auto-detected from the active tool's repo-local skill directory; pass it explicitly only if needed. Present the scan summary and inventory table from the script output:

Scanning:
  ✓ <config>/skills/         (17 files)
  ✗ {cwd}/.cursor/skills/    (not found — global skills only)

Phase 2 — Quality Evaluation

Launch a subagent with the full inventory and checklist. The subagent reads each skill, applies the checklist, and returns per-skill JSON:

{ "verdict": "Keep"|"Improve"|"Update"|"Retire"|"Merge into [X]", "reason": "..." }

Chunk guidance: Process ~20 skills per subagent invocation to keep context manageable. Save intermediate results to results.json (status: "in_progress") after each chunk.

After all skills are evaluated: set status: "completed", proceed to Phase 3.

Resume detection: If status: "in_progress" is found on startup, resume from the first unevaluated skill.

Each skill is evaluated against this checklist:

- [ ] Content overlap with other skills checked
- [ ] Overlap with durable instruction surfaces checked
- [ ] Freshness of technical references verified (use WebSearch if tool names / CLI flags / APIs are present)
- [ ] Usage frequency considered

Verdict criteria:

Evaluation is holistic AI judgment — not a numeric rubric. Guiding dimensions:

• Actionability: code examples, commands, or steps that let you act immediately
• Scope fit: name, trigger, and content are aligned; not too broad or narrow
• Uniqueness: value not replaceable by durable instructions or another skill
• Currency: technical references work in the current environment

Reason quality requirements — the reason field must be self-contained and decision-enabling:

• Do NOT write "unchanged" alone — always restate the core evidence
• For Retire: state (1) what specific defect was found, (2) what covers the same need instead
  • Bad: "Superseded"
  • Good: "disable-model-invocation: true already set; superseded by ai-learning which covers all the same patterns plus confidence scoring. No unique content remains."
• For Merge: name the target and describe what content to integrate
  • Bad: "Overlaps with X"
  • Good: "42-line thin content; Step 4 of chatlog-to-article already covers the same workflow. Integrate the 'article angle' tip as a note in that skill."
• For Improve: describe the specific change needed (what section, what action, target size if relevant)
  • Bad: "Too long"
  • Good: "276 lines; Section 'Framework Comparison' (L80–140) duplicates ai-era-architecture-principles; delete it to reach ~150 lines."
• For Keep (mtime-only change in Quick Scan): restate the original verdict rationale, do not write "unchanged"
  • Bad: "Unchanged"
  • Good: "mtime updated but content unchanged. Unique Python reference explicitly imported by rules/python/; no overlap found."

Phase 3 — Summary Table

Phase 4 — Consolidation

1. Retire / Merge: present detailed justification per file before confirming with user:
   • What specific problem was found (overlap, staleness, broken references, etc.)
   • What alternative covers the same functionality (for Retire: which existing skill/rule; for Merge: the target file and what content to integrate)
   • Impact of removal (any dependent skills, MEMORY.md references, or workflows affected)
2. Improve: present specific improvement suggestions with rationale:
   • What to change and why (e.g., "trim 430→200 lines because sections X/Y duplicate python-patterns")
   • User decides whether to act
3. Update: present updated content with sources checked
4. Check MEMORY.md line count; propose compression if >100 lines

Results File Schema

<config>/skills/skill-stocktake/results.json:

evaluated_at: Must be set to the actual UTC time of evaluation completion. The save-results.js script sets this automatically. Never use a date-only approximation like T00:00:00Z.

{
  "evaluated_at": "2026-02-21T10:00:00Z",
  "mode": "full",
  "batch_progress": {
    "total": 80,
    "evaluated": 80,
    "status": "completed"
  },
  "skills": {
    "skill-name": {
      "path": "<config>/skills/skill-name/SKILL.md",
      "verdict": "Keep",
      "reason": "Concrete, actionable, unique value for X workflow",
      "mtime": "2026-01-15T08:30:00Z"
    }
  }
}

Notes

• Evaluation is blind: the same checklist applies to all skills regardless of origin (MDT, self-authored, auto-extracted)
• Archive / delete operations always require explicit user confirmation
• No verdict branching by skill origin