Skills Doctor

Skills Doctor is a local-first TypeScript CLI that audits Claude and Codex Agent Skills and produces human-readable or machine-readable findings.

Agent Skills can silently drift when frontmatter, trigger descriptions, workflow instructions, references, scripts, evals, security boundaries, or local and global copies stop agreeing.

I designed and implemented the scanner, deterministic rule catalog, score model, security incident grouping, JSON API, local usage analysis, and consent-gated agent handoff. I authored 27 merged pull requests in the public repository.

• Root discovery finds project and user-level .claude/skills and .agents/skills directories, then the package scanner classifies SKILL.md, scripts, references, assets, configuration, symlinks, and executable files.
• A deterministic rule engine emits quality diagnostics and security capabilities; reporters turn the same scan into terminal summaries, schema-versioned JSON, repair artifacts, or the programmatic TypeScript API.
• The interactive layer can add local Codex usage evidence, select a finding subset, write a bounded handoff prompt, launch claude or codex only after confirmation, and re-scan after the agent exits.

npx skills-doctor@latest --yes --json --fail-on warning --fail-on-security P1 --min-score 95

• Rule logic and output shape live in the CLI; the packaged Agent Skill is a thin discovery and invocation wrapper rather than a second implementation.
• Security signals stay deterministic and rule-by-rule in JSON, while human output groups correlated signals into incidents for review.
• Non-interactive discovery fails on ambiguous roots instead of guessing, and agent repair remains a separate, explicitly confirmed action.

• Security checks have to connect prompt override, secret access, egress, remote execution, persistence, and approval bypass signals without presenting heuristics as proof of malicious intent.
• Root discovery must handle local/global shadowing, cross-ecosystem duplicates, symlinks, hidden files, and disabled skills without silently scanning the wrong scope.
• Usage analysis has to extract useful counts and context-pressure evidence from changing Codex trace formats without copying raw prompts or transcripts into reports.

• Static rules can flag suspicious capabilities and weak workflow structure, but they cannot establish author intent or replace a manual security review.
• The score deducts once per distinct rule rather than per repeated finding, which keeps noisy packages from dominating but intentionally compresses frequency information.
• Local usage analysis is best-effort and its coverage depends on which Codex history and pressure sources are present.

The latest tagged release is v0.6.2, published July 5, 2026. The public repository contains 27 merged pull requests authored by me and additional changes on main after the release.

• GitHub repository
• 27 merged pull requests
• v0.6.2 release

• Rule catalog and rationale
• Programmatic API reference
• Security scanning specification

August 9, 2026