mtk-doctor - SKILL.md Agent Skill

name: mtk-doctor description: Run an MTK install health check (core files, components, hooks, integrity) with PASS/WARN/FAIL diagnostics, --json for CI, and --fix for safe auto-repairs. type: skill allowed-tools: Read, Bash argument-hint: [--json] [--fix] [--strict] user-invocable: true

MTK Doctor

Overview

mtk-doctor is the holistic health check for an MTK installation. Where validate-toolkit.sh checks structural integrity (manifest matches files, frontmatter shape), the doctor catches runtime rot: deprecated model IDs in agents, oversized CLAUDE.md, missing gitignore entries, stale analytics, dangling hook registrations.

When To Use

Periodically (e.g. before bumping the toolkit version)
When the engineer asks "is the toolkit healthy?" or "is anything broken?"
After upgrading MTK in a target repo (catch deprecated IDs and hook drift)
In CI as bash scripts/mtk-doctor.sh --strict --json for dashboards

When NOT To Use

For structural validation in tight loops — use validate-toolkit.sh (faster, focused).
To debug a specific failing skill — use context-report instead.

Workflow

Run the script. Default: human-readable output.
```
bash scripts/mtk-doctor.sh
```
Apply safe fixes. Auto-fix gitignore additions and chmod issues:
```
bash scripts/mtk-doctor.sh --fix
```
FAILs are never auto-fixed. Auto-fix is for known-safe items only.
CI mode. Strict + JSON:
```
bash scripts/mtk-doctor.sh --strict --json
```
Strict treats WARN as failure (exit 1). JSON output suits dashboards.
Triage failures. Each FAIL entry includes a detail field pointing at the fix path. Common cases:
- "version mismatch" → bump both manifest.json and plugin.json (and marketplace.json) to the same value
- "deprecated model" → update agent frontmatter to a current model ID
- "hook missing" → either add the hook script or remove its registration from settings.json
- "skill name mismatch" → rename the directory or update frontmatter name: to match

Categories Checked

CORE — required files (manifest, plugin.json, README, AGENTS, validate-toolkit), CLAUDE.md line budget if present
COMPONENTS — version sync, skill counts, skill name/directory consistency, deprecated model detection
HOOKS — registered hooks exist and are executable, event names valid, all hooks use set -euo pipefail
INTEGRITY — manifest paths exist, gitignore coverage, analytics freshness, validate-toolkit passes

Verification

Output shows non-zero PASS in every category (no empty section)
Summary line printed last
Exit code 1 on any FAIL
--strict exits 1 on WARN
--json output is valid JSON parseable by jq
--fix only modifies gitignore and file permissions; never edits source files

Red Flags

Doctor reports PASS when validate-toolkit.sh fails — checks are out of sync
--fix modifies source code or skill content (it shouldn't — only gitignore + chmod)
New checks added that overlap with validate-toolkit.sh — keep validator structural, doctor holistic
Deprecated model list goes stale — update DEPRECATED_MODELS in scripts/mtk-doctor.sh when Anthropic deprecates more