Skip to content

majiayu000/spellbook / skills/skill-checkup

skill-checkup

Verified

Read-only checkup of installed agent skills across Claude Code and Codex: broken links or files, same-name copies that drifted apart, descriptions that compete or miss requests their skill already handles, and skills loaded by both agents but used by only one. Use when the user asks to check, audit or tidy their skills, compare Claude Code and Codex skills, asks why a skill did not trigger, or wants to test a reworded description against past requests. For unused Claude Code skills and token cost alone, Claude Code's /skill-doctor is enough. Not for agent config health or raw usage rankings (skill-usage-stats) or policy-driven ownership, exposure and retirement repairs (skill-ecosystem-doctor).

Skill Checkup

A thin entry point for skill-checkup, a read-only, offline Python tool with no dependencies. It reads installed skill folders (~/.claude/skills, ~/.agents/skills, ~/.codex/skills, the current project's .claude/skills and .agents/skills, and enabled Claude Code plugins) and local Claude Code and Codex session logs.

Operating Contract

  • Direct actions: run the checkup, summarize it, and explain the top actions.
  • Escalate before: editing, merging, moving or archiving any skill. The tool never does this; only change a skill when the user names that change.
  • Evidence-backed pushback: similarity findings and the silent appendix are lexical matches over past requests. Present them as candidates, not verdicts, and check one or two by reading the skill before recommending a change.
  • Feedback loop: after an approved wording change, rerun replay for that skill and report both rows.

Run

From the user's current project, so project-level skills are included:

uvx --from git+https://github.com/majiayu000/skill-checkup@v0.2.1 skill-checkup

Without uvx: pipx run --spec git+https://github.com/majiayu000/skill-checkup@v0.2.1 skill-checkup.

It prints a summary table and the top five actions, and writes the full report to ./skill-checkup-report.md. The first run reads up to 90 days of logs and can take a minute; later runs use a cache in ~/.cache/skill-checkup.

Useful options:

  • --lang zh or --lang en to match the conversation.
  • --show-examples only when the user wants to see which of their own requests were matched. Those quotes stay on the machine.
  • --context-tokens 1000000 when the user's model has a 1M-token window; the default assumes 200k.
  • --summary-json summary.json --anonymize for a counts-only file the user can share.

Check a reworded description

uvx --from git+https://github.com/majiayu000/skill-checkup@v0.2.1 skill-checkup replay <skill> --description "<new wording>"

Compare the current and new rows: higher hit@3 with similar steals@1 is better. The numbers are a lexical proxy, so compare rows rather than reading absolute values.

Reading the report

SectionWhat to do with it
BrokenFix first. Diverged copies: compare, keep one source, make the others identical.
CompetingMerge, or rewrite both descriptions so their boundaries differ.
One-sidedLoaded by both agents, used by one. Delete the idle copy only when the report says it's safe; when it says the copy is shared, turn the skill off in Claude Code's /skills menu instead. Copies in ~/.agents/skills may also serve Cursor or Gemini CLI.
UnusedArchive candidates. Keep emergency tools even if unused. In Claude Code, /skill-doctor gives the same list with token costs.
HeavyAn estimate; /context shows the measured listing size. On a 1M-token model it rarely matters.
New skill candidatesRepeated requests worth a skill; confirm with the user before writing one. An item marked "already handled in the body of X" means rewording X's description, not a new skill.
Appendix (silent)Low confidence: mentions and requests look alike. Treat as leads only.

Gotchas

  • Sessions started by claude -p, Agent SDK hosts or codex exec count as usage but are excluded from request analysis.
  • A Codex turn that reads 8+ skills is treated as an inventory sweep and not counted as use.
  • "Unused" only means no use in this machine's logs in the window.
  • The default budget estimate assumes a 200k-token window; pass --context-tokens 1000000 for 1M-token models.
  • Optional config ~/.config/skill-checkup/config.json can list deprecated directories and accepted known issues.
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall