| name | skill-server-debug |
| description | Debug local app/dev server lifecycle problems with servers CLI/MCP status, logs, operations, traces, and lock evidence. |
| user_invocable | true |
skill-server-debug
Use this when a dev/app server is down, stale, locked, returning the wrong URL, or confusing multiple agents.
Rules
- Prefer MCP tools when available:
mcp__servers__get_local_server_status, mcp__servers__start_local_server, mcp__servers__stop_local_server, and mcp__servers__restart_local_server.
- CLI fallback:
servers servers:debug, servers servers:status, servers servers:logs, servers operations, and servers traces.
- Preserve evidence: command, cwd, port, health URL, PID, log path, lock owner, operation ID, and failing output.
- Do not delete shared tasks or silently bypass locks. If the owning agent is active, communicate.
- If the
servers CLI/MCP itself is broken, create a task against @hasna/servers, fix it in open-servers, test, publish, reinstall, and verify before continuing.
Workflow
-
Capture the complete lifecycle snapshot:
servers servers:debug <slug> --json
servers servers:status <slug> --refresh --json
-
Read logs and recent operations:
servers servers:logs <slug> --lines 160
servers operations --server <slug> --limit 20
servers traces --server <slug> --limit 40
-
Classify the failure:
- Not registered: run
servers servers:init ....
- Wrong command/cwd/port: update with
servers servers:init ... --force.
- Locked by another active agent: coordinate or use
--wait-lock with a bounded timeout.
- Process running but not ready: inspect logs, fix the app, then
servers servers:restart.
- Metadata points at a dead PID: use
servers servers:status --refresh, then start/restart through the lifecycle command.
-
Apply the smallest fix through the lifecycle command:
servers servers:start <slug> --agent <agent> --reason '<reason>'
servers servers:restart <slug> --agent <agent> --reason '<reason>'
servers servers:stop <slug> --agent <agent> --reason '<reason>'
-
Verify from the user-visible URL, not only the command exit code.
Done When
The root cause is identified, status/logs/traces support the conclusion, the server is either ready or intentionally stopped, and any package-level bug has a tracked fix/release task.
