ops-doctor
Health check and auto-repair for the ops plugin. Diagnoses manifest errors, broken permissions, invalid configs, stale caches, and missing files — then spawns an agent to fix everything automatically.
How do I install this agent skill?
npx skills add https://github.com/davepoon/buildwithclaude --skill ops-doctorIs this agent skill safe to install?
- Gen Agent Trust Hubpass
This skill performs automated health checks and repairs for a plugin by executing local diagnostic tools and spawning sub-agents. It involves dynamic command execution during skill loading and ingests local configuration data to guide its actions.
- Socketpass
No alerts
- Snykwarn
Risk: MEDIUM · 1 issue
What does this agent skill do?
Runtime Context
Before diagnosing, load:
- Preferences:
cat ${CLAUDE_PLUGIN_DATA_DIR:-$HOME/.claude/plugins/data/ops-ops-marketplace}/preferences.json— check all configured channels and services - Daemon health:
cat ${CLAUDE_PLUGIN_DATA_DIR}/daemon-health.json— primary diagnostic input - Secrets: Verify secret resolution chain works: Doppler MCP → env → Doppler CLI → password manager
OPS ► DOCTOR
CLI/API Reference
ops-doctor bin script
| Command | Usage | Output |
|---|---|---|
${CLAUDE_PLUGIN_ROOT}/bin/ops-doctor | Run full health diagnostics | JSON with errors, warnings, tools, env_vars, registry |
${CLAUDE_PLUGIN_ROOT}/bin/ops-doctor 2>/dev/null || echo '{"errors":["diagnostic_script_failed"]}' | Run with fallback | JSON or error sentinel |
Key files read by diagnostics
| File | Purpose |
|---|---|
${CLAUDE_PLUGIN_DATA_DIR}/daemon-health.json | Primary daemon health input |
${CLAUDE_PLUGIN_DATA_DIR}/preferences.json | Configured channels and services |
${CLAUDE_PLUGIN_ROOT}/.claude-plugin/plugin.json | Plugin manifest validation |
${CLAUDE_PLUGIN_ROOT}/scripts/registry.json | Project registry validation |
Phase 1 — Run diagnostics
Run the diagnostic script to get a full health report:
${CLAUDE_PLUGIN_ROOT}/bin/ops-doctor 2>/dev/null || echo '{"errors":["diagnostic_script_failed"],"warnings":[]}'
Parse the JSON output. Display a summary:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
OPS ► DOCTOR — [timestamp]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Plugin: [version] at [plugin_root]
Skills: [count] defined
Agents: [count] defined
Bin scripts:[count] available
ERRORS [count]
[list each error with description]
WARNINGS [count]
[list each warning with description]
TOOLS
[table of CLI tool availability]
ENV VARS
[table of env var status]
Registry: [status] ([project_count] projects)
Preferences:[status]
Cache: [versions list]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Agent Teams support
If CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 is set, use Agent Teams when multiple independent fix categories are identified (e.g., manifest issues + permission issues + registry issues). This enables:
- Fix agents work in parallel on different issue categories without stepping on each other
- You can prioritize: "fix manifest errors first, then permissions"
- Agents share context so a manifest fix can inform the registry repair
Team setup (only when flag is enabled, multiple issue categories):
TeamCreate("doctor-fixers")
Agent(team_name="doctor-fixers", name="fix-manifest", subagent_type="ops:doctor-agent", ...)
Agent(team_name="doctor-fixers", name="fix-permissions", subagent_type="ops:doctor-agent", ...)
Agent(team_name="doctor-fixers", name="fix-registry", subagent_type="ops:doctor-agent", ...)
If the flag is NOT set or only one issue category exists, use a single doctor-agent subagent.
Phase 2 — Decision
If $ARGUMENTS contains --check-only: stop here, display results only.
If there are errors or warnings:
Display: "Found [N] issues. Spawning doctor agent to auto-fix..."
Then spawn the doctor agent (or Agent Team — see above):
Agent({
subagent_type: "ops:doctor-agent",
prompt: "Fix the following ops plugin issues.\n\nDIAGNOSTIC_JSON: [paste full JSON]\nPLUGIN_ROOT: ${CLAUDE_PLUGIN_ROOT}\nCACHE_DIR: ~/.claude/plugins/cache/ops-marketplace/ops\n\nFix all errors and warnings. Re-run diagnostics after to verify.",
description: "Fix ops plugin issues"
})
If there are no errors and no warnings:
Display: "All checks passed. Plugin is healthy."
Phase 3 — Post-fix verification
After the agent completes, re-run diagnostics:
${CLAUDE_PLUGIN_ROOT}/bin/ops-doctor 2>/dev/null
Display updated results. If errors remain, report them to the user with manual fix instructions.
Native tool usage
WebSearch — known issue lookup
When diagnostics find errors, use WebSearch to check if the issue is a known Claude Code plugin bug, MCP server issue, or configuration problem. Include links to relevant GitHub issues or docs.
WebFetch — MCP health check
For MCP servers that appear disconnected, use WebFetch to test their underlying APIs directly (e.g., https://api.linear.app/graphql with a simple query) to distinguish between "MCP broken" and "API down".
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/davepoon/buildwithclaude/ops-doctor">View ops-doctor on skillZs</a>