# Skill Doctor

> Use to audit Agent Skills catalogs or installed skill roots: validate SKILL.md frontmatter, Codex openai.yaml metadata, README catalog coverage, cli-* version pins, and relative resource links; optionally apply conservative --fix-safe metadata repairs.

- **Type:** Skill
- **Install:** `agentstack add skill-paulrberg-agent-skills-skill-doctor`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [PaulRBerg](https://agentstack.voostack.com/s/paulrberg)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [PaulRBerg](https://github.com/PaulRBerg)
- **Source:** https://github.com/PaulRBerg/agent-skills/tree/main/skills/skill-doctor

## Install

```sh
agentstack add skill-paulrberg-agent-skills-skill-doctor
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Skill Doctor

Audit local Agent Skills catalogs and installed skill roots, then apply only narrow metadata repairs when requested.

## Arguments

- `--root PATH`: Scan this catalog or installed skill root. Repeatable. Default: current working directory.
- `--format text|json`: Select report format. Default: `text`.
- `--fix-safe`: Create missing `agents/openai.yaml` files or update mismatched `policy.allow_implicit_invocation`.
- `--include-shelved`: Include `shelved/*/SKILL.md` in metadata checks. Shelved skills are never required in `README.md`.

## Workflow

1. Resolve the skill directory, then run the helper from that directory:

   ```sh
   uv run scripts/skill-doctor.py "$ARGUMENTS"
   ```

2. Use JSON when another command or agent will consume the result:

   ```sh
   uv run scripts/skill-doctor.py --root . --format json
   ```

3. Run safe fixes only after reading the findings:

   ```sh
   uv run scripts/skill-doctor.py --root . --fix-safe
   ```

4. Re-run without `--fix-safe` after any manual edits.

## Findings

- Treat `error` findings as catalog defects that should block publishing or syncing.
- Treat `warning` findings as review-required catalog hygiene issues.
- Use `path` and `line` from JSON output for precise follow-up edits.

## Safe Fix Policy

`--fix-safe` may only:

- Create a missing `agents/openai.yaml` with `policy.allow_implicit_invocation` derived from `SKILL.md`.
- Update an existing `allow_implicit_invocation` boolean when it disagrees with `disable-model-invocation`.

Do not use the helper to rewrite frontmatter order, descriptions, README rows, `references/version.txt`, or relative links. Make those edits manually and verify with a fresh audit.

## Exit Codes

- `0`: Clean, or all requested safe fixes succeeded and no findings remain.
- `1`: Findings remain.
- `2`: Invalid arguments or unreadable environment.
- `3`: A requested safe fix failed.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [PaulRBerg](https://github.com/PaulRBerg)
- **Source:** [PaulRBerg/agent-skills](https://github.com/PaulRBerg/agent-skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-paulrberg-agent-skills-skill-doctor
- Seller: https://agentstack.voostack.com/s/paulrberg
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.