/ Directory / Playground / skill-doctor
← All servers ↗ GitHub
● Community marian2js ⚡ Instant

skill-doctor

by marian2js · marian2js/skill-doctor

Lint your Claude skills before shipping — frontmatter, resource refs, trigger clarity, eval hygiene, scored 0-100 with severities.

skill-doctor is a CLI that scans a local skill package and flags problems that hurt activation, reliability, or quality. It checks YAML frontmatter and metadata, verifies resource references are unbroken, evaluates trigger descriptions for clarity, and validates evals/evals.json. Output is a 0–100 score with severity-labeled findings; supports text, JSON, and score-only modes — perfect for pre-commit, pre-route, or CI gating.

▶ Watch demo 📦 Install 💡 Use Cases

Why use it

Key features

Live Demo

What it looks like in practice

skill-doctor-skill.replay ▶ ready
0/0

Install

Pick your client

~/Library/Application Support/Claude/claude_desktop_config.json  · Windows: %APPDATA%\Claude\claude_desktop_config.json
{
  "mcpServers": {
    "skill-doctor-skill": {
      "command": "npx",
      "args": [
        "-y",
        "skill-doctor@latest",
        "."
      ],
      "_inferred": false
    }
  }
}

Open Claude Desktop → Settings → Developer → Edit Config. Restart after saving.

~/.cursor/mcp.json · .cursor/mcp.json
{
  "mcpServers": {
    "skill-doctor-skill": {
      "command": "npx",
      "args": [
        "-y",
        "skill-doctor@latest",
        "."
      ],
      "_inferred": false
    }
  }
}

Cursor uses the same mcpServers schema as Claude Desktop. Project config wins over global.

VS Code → Cline → MCP Servers → Edit
{
  "mcpServers": {
    "skill-doctor-skill": {
      "command": "npx",
      "args": [
        "-y",
        "skill-doctor@latest",
        "."
      ],
      "_inferred": false
    }
  }
}

Click the MCP Servers icon in the Cline sidebar, then "Edit Configuration".

~/.codeium/windsurf/mcp_config.json
{
  "mcpServers": {
    "skill-doctor-skill": {
      "command": "npx",
      "args": [
        "-y",
        "skill-doctor@latest",
        "."
      ],
      "_inferred": false
    }
  }
}

Same shape as Claude Desktop. Restart Windsurf to pick up changes.

~/.continue/config.json
{
  "mcpServers": [
    {
      "name": "skill-doctor-skill",
      "command": "npx",
      "args": [
        "-y",
        "skill-doctor@latest",
        "."
      ]
    }
  ]
}

Continue uses an array of server objects rather than a map.

~/.config/zed/settings.json
{
  "context_servers": {
    "skill-doctor-skill": {
      "command": {
        "path": "npx",
        "args": [
          "-y",
          "skill-doctor@latest",
          "."
        ]
      }
    }
  }
}

Add to context_servers. Zed hot-reloads on save.

claude mcp add skill-doctor-skill -- npx -y skill-doctor@latest .

One-liner. Verify with claude mcp list. Remove with claude mcp remove.

Use Cases

Real-world ways to use skill-doctor

Lint your skill before publishing to a marketplace

👤 Skill authors about to share a SKILL.md ⏱ ~15 min beginner

When to use: You finished a skill and want a sanity pass before anyone else installs it.

Prerequisites
  • Node 18+ — nvm install 18
Flow
  1. Run the doctor
    Run skill-doctor at the skill root.✓ Copied
    → Score + list of findings by severity
  2. Fix high-severity items
    Fix high-severity issues first; re-run until score ≥ 85.✓ Copied
    → Score climbs; criticals disappear

Outcome: A skill that activates when you expect it to and doesn't have broken references.

Pitfalls
  • Chasing a perfect 100 — Low-severity items (style nits) are often fine; focus on triggers and resources
Combine with: oaustegard-claude-skills

Gate a skills repo on a minimum quality score in CI

👤 Teams maintaining multiple skills in one repo ⏱ ~30 min intermediate

When to use: You ship skills often and want drift prevention.

Prerequisites
  • GitHub Actions (or equivalent) — Repo with .github/workflows/
Flow
  1. Add the workflow
    Add a GH Actions job that runs skill-doctor and fails if score < 80.✓ Copied
    → Workflow file added; runs on PR
  2. Set strictness per path
    Production skills fail < 90; drafts allow < 70.✓ Copied
    → Matrix or conditional thresholds in the workflow

Outcome: PRs that degrade skill quality get caught before merge.

Pitfalls
  • Locking the bar too high too early — Start permissive, tighten over 2-3 months as findings are fixed
Combine with: agent-skills-cli-skill

Diagnose why a skill isn't activating

👤 Skill users with activation problems ⏱ ~15 min beginner

When to use: You installed a skill but Claude never triggers it.

Flow
  1. Run the doctor on the skill directory
    Run skill-doctor on ~/.claude/skills/<skill>.✓ Copied
    → Findings call out weak trigger or frontmatter issues
  2. Edit the description
    Rewrite the description so the concrete user-task keywords appear in it.✓ Copied
    → Trigger-clarity severity drops

Outcome: Clearer activation; Claude picks the skill for the right tasks.

Combinations

Pair with other MCPs for X10 leverage

skill-doctor-skill + oaustegard-claude-skills

Lint before publishing to the marketplace

Run skill-doctor locally; then open a PR to oaustegard/claude-skills.✓ Copied
skill-doctor-skill + agent-skills-cli-skill

Chain skill-doctor with other skill-authoring tools

Use agent-skills-cli to scaffold; skill-doctor to validate before commit.✓ Copied
skill-doctor-skill + claude-skill

Follow the authoring guide, then lint

Write per the claude-skill guide; verify with skill-doctor.✓ Copied

Tools

What this MCP exposes

ToolInputsWhen to callCost
skill-doctor <path> skill directory path Before publishing, in CI, or to diagnose activation issues 0

Cost & Limits

What this costs to run

API quota
None — local static analysis
Tokens per call
None (CLI, not an API)
Monetary
Free
Tip
Run only on directories that changed; in CI, use path filters to avoid scanning the whole repo every PR.

Security

Permissions, secrets, blast radius

Credential storage: No credentials
Data egress: None — local analysis only

Troubleshooting

Common errors and fixes

Doctor says SKILL.md not found

Run from the skill root (directory containing SKILL.md), not the repo root.

Verify: ls SKILL.md in CWD
'evals/evals.json' schema failures

Make sure each eval has the required fields; a minimal stub is better than broken.

Verify: jq . evals/evals.json
Score doesn't improve after edits

Re-run; if a finding persists, read the severity and detail — sometimes fixes introduce new low-severity issues.

Verify: Diff the JSON reports between runs

Alternatives

skill-doctor vs others

AlternativeWhen to use it insteadTradeoff
agent-skills-cli-skillYou want general CLI tools for scaffolding/managing skillsDifferent feature set; not a linter
claude-skillYou want the authoring guide to understand what 'good' looks likeDocs, not a linter

More

Resources

📖 Read the official README on GitHub

🐙 Browse open issues

🔍 Browse all 400+ MCP servers and Skills