Metadata-Version: 2.4
Name: claude-skills-doctor
Version: 0.3.0
Summary: A doctor for your Claude Code agent skills: find the SKILL.md files Claude silently can't see (over the discovery budget), plus naming, routing and hygiene problems — deterministically, across every installed skill.
Project-URL: Homepage, https://github.com/gulmezeren2-byte/claude-skills-doctor
Project-URL: Repository, https://github.com/gulmezeren2-byte/claude-skills-doctor
Project-URL: Changelog, https://github.com/gulmezeren2-byte/claude-skills-doctor/blob/main/CHANGELOG.md
Author: Mehmet Eren Gülmez
License: MIT
License-File: LICENSE
Keywords: SKILL.md,agent-skills,ai-agents,claude,claude-code,claude-skills,linter,mcp,skill,skill-lint,skill-validator,skilldoctor,skills
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.10
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.0
Requires-Dist: typer>=0.12
Description-Content-Type: text/markdown

# claude-skills-doctor

**A doctor for your Claude Code agent skills — find the ones Claude silently can't see, before they cost you a session.**

> Install `claude-skills-doctor`, run `skilldoctor`.

You install a skill, it looks perfect, and Claude never uses it. No error, no warning. As of Claude Code 2.0.70 the combined skill + slash-command descriptions injected into the system prompt live under a **15,000-character budget** (~4,000 tokens, set by `SLASH_COMMAND_TOOL_CHAR_BUDGET`). Go over and Claude Code **just stops listing some skills** — and Claude is told not to use skills it wasn't told about. The failure is invisible from the inside. `skilldoctor` makes it visible.

```
$ skilldoctor
Discovery budget
████████████████████████████░░░░  13,120 / 15,000 chars (87%)

 severity   check                  target            detail
 error      name-folder-mismatch   pdf-tools         `name: pdf` must match the folder name `pdf-tools`
 error      frontmatter-invalid    my-skill          invalid YAML in frontmatter: mapping values are not allowed here
 warn       description-collision  review-code       description ~72% overlaps `code-review` — they may compete to trigger
 warn       budget-near            budget            skills + commands use ~13,120/15,000 discovery chars (87%) — nearing the silent-truncation cliff.

28 skill(s) · 6 command(s) · 2 error(s) · 2 warning(s)
```

## Install

```
uvx claude-skills-doctor            # run without installing
pip install claude-skills-doctor    # or install it
```

Then run `skilldoctor` (the command `claude-skills-doctor` works too).

## Use

```
skilldoctor                 # health-check every skill Claude Code can see; exits non-zero on errors
skilldoctor --fix           # show a concrete suggested fix for each finding
skilldoctor --json          # machine-readable, for CI
skilldoctor --strict        # fail on warnings too
skilldoctor budget          # the shareable view: the bar + the biggest contributors to trim
```

It scans everywhere Claude Code loads from — your user skills (`~/.claude/skills`), the project's (`.claude/skills`), and installed plugins — plus slash-commands, which share the same budget.

## What it checks

All deterministic. **No model calls, no network, no guessing** — it reads your files and reports.

- **Discovery budget** — the headline. Total skill + command description characters vs the 15,000 limit (honours `SLASH_COMMAND_TOOL_CHAR_BUDGET`). Over budget → some skills are silently unlisted.
- **Won't load** — invalid YAML frontmatter (which *silently* prevents loading), missing `name`/`description`, and `name` that doesn't match its folder (required, and the one Anthropic's own validator misses).
- **Won't route** — descriptions too thin to trigger, and descriptions written as a step-by-step how-to (which makes Claude follow the summary and skip loading the body).
- **Collisions** — two skills with the same `name`, or near-identical descriptions that compete to trigger.
- **Contract & hygiene** — `allowed-tools` that doesn't cover the tools the body actually uses, `<`/`>` in descriptions (prompt-injection risk), oversized bodies that belong in `references/`, reference chains more than one level deep, absolute paths, and human-facing docs (README/CHANGELOG) left inside a skill folder.
- **Security** — scans *every* skill (third-party plugins included) for `hidden-instruction` phrases (instruction-override / hide-from-user / prompt-extraction) in the SKILL.md and its references, and `script-network-call`s inside `scripts/`. Because "I installed a skill — is it safe?" is a real question, and a documentation-context filter keeps skills that *teach* prompt-injection safety from tripping it.

Errors make it exit non-zero, so it gates a pipeline: `skilldoctor && claude ...`. Add `--fix` to see a concrete suggested fix under each finding.

## How it's different from a skill linter

There are per-file `SKILL.md` linters and validators (and Anthropic's `skill-creator` model-evaluates **one** skill you're authoring). `claude-skills-doctor` is the complement: a **whole-system, install-time** health check across **every** skill you actually have — and the only one that measures the **cross-skill** failures a single-file linter structurally can't see: the shared discovery budget, duplicate names, and colliding descriptions. A linter checks a file; a doctor examines the whole patient.

## Honest about the numbers

The budget is measured as each skill/command's `name` + `description` characters. That's an estimate — the real budget adds minor per-entry formatting — so treat it as *close, and on the safe side*, not byte-exact. It lints *your own* skills fully; third-party plugin skills count toward the budget but are checked only for load-breakers, so it never nags about skills you can't fix. Every finding points at a file and a reason; nothing is invented.

## License

MIT
