skill-doctor

Name: skill-doctor
Author: dotCMS

Documentation Community

Repo stars 943
Author repo core

Interpretation is structured for decision-making; original keeps the upstream SKILL.md unchanged.

Decide Fit First

Core job: Use when a repo skill fails, produces errors, gives wrong instructions, or references stale information. Also use when a command…
Best fit: Use it when the task has reusable inputs, steps, and validation criteria rather than a one-off answer.
Avoid forcing it: If the source lacks commands, platform support, or external-service evidence, keep those fields unknown instead of guessing.

Design Intent

Structure: The skill is organized around “Routing”, “List”, “Feedback”, “Manage”, showing how the author expects the agent to judge fit, collect context, and produce verifiable output.
Trigger evidence: Prioritize the author’s wording around when to use it, what context to collect, and what output shape to produce.
Evidence boundary: Author text states facts, repository files prove commands and paths, and Fluxly only adds fit, limits, and usage judgment.

How To Use It

Inputs: Provide target material, scope, expected result, forbidden changes, and validation method.
Invocation: Name skill-doctor directly; if the source includes slash commands, start with the command and then add task context.
Validation: Start small and check whether the result follows “Routing / List / Feedback” before expanding.

Boundaries And Review

Dependencies: It usually needs no extra API key, so start with a small validation task.
Permissions: Declared permissions include read / write; ask the agent to state file, command, and rollback boundaries before acting.
Quality bar: A useful result names the deliverable, evidence, and next action. Generic prose means the task needs tighter context.

Skill Doctor

Diagnose issues with repository skills, manage local overrides, and optimize skill quality.

Scope: Skills in the current repository's .claude/skills/ directory only.

Routing

Parse $ARGUMENTS:

Pattern	Mode
`list`	list (all repo skills)
`info <skill>`	list (detail for one skill)
`feedback [skill] "<message>"`	feedback (quick note)
(empty) or `<skill-name>`	diagnose
`--optimize <skill>`	optimize
`--manage [skill]`	manage (status)
`clone/diff/sync/revert <skill>`	manage (lifecycle)
`report/gist/pr <skill>`	deliver
`resolve <skill>`	resolve

Unrecognized input: show this table and ask to rephrase. Then read ./reference.md for detailed procedures.

List

Dynamically discovers repo skills by reading .claude/skills/*/SKILL.md. Shows name, description, invocation, and override status. info <skill> reads the full SKILL.md to provide detailed usage guidance. All information comes from the skill files themselves — nothing is hardcoded. See reference.md for details.

Feedback

Lightweight path for quick notes. No investigation or quality gate — just scrub, preview, confirm, post. If skill name is omitted, ask which skill (or use the most recently invoked skill if known from conversation context). See reference.md for details.

Manage

Lifecycle: clone -> edit -> diff -> sync/revert -> pr/gist. Local overrides live at ~/.claude/skills/<name>/ with .skill-origin.json tracking.

Diagnose

Identify skill, validate it exists
Classify: invalid_command | wrong_assumption | stale_info | other
Investigate -- reproduce, root cause, determine fix, check related issues. Quality gate: confirmed problem + root cause + suggested fix
Duplicate check in Discussion thread. Match found: upvote, add context, or report anyway
Route: local override -> fix inline, stop. Repo -> offer clone-and-fix or report-only
Scrub PII, review with developer, deliver to GitHub Discussion + Slack

Optimize

Checks frontmatter, token efficiency (<500 words), structure quality, and staleness (file paths, commands, flags). Scored report with fixes. Local overrides fixed directly; repo versions cloned first.

Deliver & Resolve

Deliver: GitHub Discussion (primary, one thread per skill) + Slack #log-skill-feedback (optional notification). Check prerequisites first (gh auth, repo access). See reference.md.

Resolve: After fix PR merges, mark Discussion reports resolved, post Slack summary, offer to lock thread.

Common Mistakes

See reference.md for the full table. Key rules:

Never send reports without root cause + suggested fix
Always check Discussion thread for duplicates before reporting
Always run gh auth status before any delivery action
revert always shows diff and requires name confirmation

Override Warning

When ANY skill is invoked and ~/.claude/skills/<name>/.skill-origin.json exists, output before skill content:

SKILL OVERRIDE ACTIVE: <name>
  Using: ~/.claude/skills/<name>/ (local)
  Instead of: .claude/skills/<name>/ (repo)
  Cloned from: <sha> | Repo is N commits ahead
  Run /skill-doctor --manage <name> for options

Fluxly profile Author and license come from source; runtime, permissions, and network are Fluxly detections or estimates

Fluxly category: Documentation
Author-declared agents: No explicit declaration found; this is not inferred or tested compatibility
Static check: 88 / 100 · heuristic scan, not runtime safety proof
Author / version / license: @dotCMS · no license declared
Fluxly token estimate: Lean
Fluxly setup estimate: Plug-and-play
External API key: No requirement detected
Detected OS requirements: Unspecified
Runtime requirements: Unspecified
Detected file/system behavior: Read-only
Write / modify
Detected network behavior: Local-only
Install commands: None (reference only)

Profile is derived at build time from SKILL.md and install vectors. Subject to drift from author intent.

Heads up: 未限定 allowed-tools，默认拥有全部工具权限。

Output preview skill-doctor-dotcms.preview

The current SKILL.md does not define a fixed output example.

SKILL.md SKILL.md

# Skill Doctor

Diagnose issues with repository skills, manage local overrides, and optimize skill quality.

**Scope:** Skills in the current repository's `.claude/skills/` directory only.

## Routing

Parse `$ARGUMENTS`:

| Pattern | Mode |
|---------|------|
| `list` | **list** (all repo skills) |
| `info <skill>` | **list** (detail for one skill) |
| `feedback [skill] "<message>"` | **feedback** (quick note) |
| (empty) or `<skill-name>` | **diagnose** |
| `--optimize <skill>` | **optimize** |
| `--manage [skill]` | **manage** (status) |
| `clone/diff/sync/revert <skill>` | **manage** (lifecycle) |
| `report/gist/pr <skill>` | **deliver** |
| `resolve <skill>` | **resolve** |

Unrecognized input: show this table and ask to rephrase. Then **read `./reference.md`** for detailed procedures.

## List

Dynamically discovers repo skills by reading `.claude/skills/*/SKILL.md`. Shows name, description, invocation, and override status. `info <skill>` reads the full SKILL.md to provide detailed usage guidance. All information comes from the skill files themselves — nothing is hardcoded. See reference.md for details.

## Feedback

Lightweight path for quick notes. No investigation or quality gate — just scrub, preview, confirm, post. If skill name is omitted, ask which skill (or use the most recently invoked skill if known from conversation context). See reference.md for details.

## Manage

Lifecycle: clone -> edit -> diff -> sync/revert -> pr/gist. Local overrides live at `~/.claude/skills/<name>/` with `.skill-origin.json` tracking.

## Diagnose

1. **Identify** skill, validate it exists
2. **Classify**: `invalid_command` | `wrong_assumption` | `stale_info` | `other`

…

Evidence boundary and execution chain

Author text anchors workflow facts; Fluxly only indexes current sections, terms, files, and commands.

sections -> Routing → List → Feedback → Manage → Diagnose → Optimize
terms    -> Scope · list · feedback · diagnose · optimize · manage · deliver · resolve
files/cmd -> .claude/skills/ · $ARGUMENTS · list · info <skill> · feedback [skill] "<message>" · <skill-name> · --optimize <skill> · --manage [skill]
body sha256 -> f0345bc9f54d