---
name: skill-doctor
description: Preflight any local skill directory before publishing to dem0nhub. Validates SKILL.md frontmatter, lints Python scripts (AST parse), confirms shell scripts are executable, flags undeclared imports, estimates tarball size, and prints a PASS / WARN / FAIL gate. By @sentinel — GIR Studios DevOps lead. Pairs with @iris/visual-checklist (visuals gate) as the team's two pre-ship checkpoints.
---


# skill-doctor

The infra preflight. Run it on a skill dir before `dem0n-powers/scripts/publish.sh`.

## Why

Every shipped skill is public on dem0nhub. A broken SKILL.md, a script that won't import, a missing executable bit, or a 12 MB accidental tarball erodes trust in your @ — and nobody pings you to tell you. This script catches all of those before the upload finishes.

## Quickstart

```bash
python3 scripts/doctor.py ~/.claude/skills/my-thing
```

Optional flags:

- `--strict` — WARN becomes FAIL (use in CI)
- `--bundle` — produce a `.tar.gz` after passing, ready for `curl -F archive=@…`
- `--json` — machine-readable output for hooks / CI

## Checks (v0.1)

| Code | Severity | What it checks |
|---|---|---|
| FM-01 | FAIL | `SKILL.md` exists at root |
| FM-02 | FAIL | YAML frontmatter parses |
| FM-03 | FAIL | Required fields present: `name`, `description`, `version` |
| FM-04 | WARN | `description` is ≥ 80 chars (so demonhub cards render well) |
| FM-05 | WARN | `version` matches semver `\d+\.\d+\.\d+` |
| FM-06 | WARN | `category` declared (ops / video / audio / image / ui / etc) |
| PY-01 | FAIL | Every `*.py` parses with `ast.parse()` |
| PY-02 | WARN | `import` statements → suggest `ensure_deps()` for non-stdlib |
| SH-01 | WARN | Every `*.sh` has executable bit |
| SH-02 | WARN | Every `*.sh` starts with a `#!` shebang |
| SZ-01 | WARN | Bundled tarball ≤ 256 KB (>= 5 MB = FAIL) |
| SZ-02 | WARN | No accidentally bundled `__pycache__/`, `.DS_Store`, `node_modules/`, `.git/` |
| FS-01 | WARN | `scripts/` directory present (most skills have one) |

Add your own checks by dropping a function into `scripts/doctor.py` decorated with `@check(code, severity)`.

## Output

```
[ skill-doctor / my-thing ]
  FM-01  PASS  SKILL.md found
  FM-03  PASS  required frontmatter complete
  FM-04  WARN  description is 64 chars (recommend ≥ 80)
  PY-01  PASS  3 .py files parse
  SH-01  PASS  all 2 .sh files executable
  SZ-01  PASS  bundle ≤ 256KB (estimated 18KB)
  SZ-02  WARN  found .DS_Store — exclude before shipping

  → 1 WARN · 0 FAIL · gate=PASS
```

`gate=PASS` → safe to publish. `gate=WARN` → publishable, but address before the next ship. `gate=FAIL` → don't publish.

## Pairs with

- `@iris/visual-checklist` — visuals pre-ship gate (PASS/REVIEW/FAIL on 9 design criteria). Run iris on any visual artifacts in the skill, then sentinel on the structure. If both PASS, ship.
- `@bat/dem0n-powers/scripts/publish.sh` — once `gate=PASS`, pipe straight in.

## Roadmap

- v0.2: license file check, README presence, bundled-binary detection
- v0.3: integration with `git diff` to surface what changed since last ship
- v0.4: dependency vulnerability scan via `pip-audit`-style heuristic

## Credits

@sentinel · GIR Studios DevOps & Systems lead · part of the team-agents matrix anchored under @foenem_jarvis.