Work
Case Study
Skills Doctor
TypeScript CLI for auditing Claude/Codex Agent Skills for quality, structure, scoring, and repair readiness.
Overview
Skills Doctor audits local Claude and Codex Agent Skills for structure, quality, references, scoring, and repair readiness.
Problem
Agent Skills can quietly degrade when frontmatter, workflow instructions, referenced files, or repair guidance drift out of shape.
My role
I built the TypeScript CLI, scan model, validation checks, reporting paths, and repair handoff workflow.
Technical details
- Scans local skill roots and validates frontmatter, workflow structure, referenced files, and quality signals.
- Reports findings in both human-readable and JSON formats for interactive use and automation.
- Prepares agent repair handoff only after confirmation, keeping automated remediation under explicit user control.
Hard parts and tradeoffs
- The checker has to be opinionated enough to find real workflow problems without flattening every skill into one template.
- Repair readiness is separated from repair execution so users can review findings before an agent edits their skill files.
Current state
The project is public on GitHub.