| name | skill-server-restart |
| description | Restart local app/dev servers safely through the servers CLI/MCP using lifecycle locks, readiness waits, and operation traces. |
| user_invocable | true |
skill-server-restart
Use this when an existing app/dev server must be restarted after code, env, dependency, or configuration changes.
Rules
- Prefer MCP tools when available:
mcp__servers__restart_local_server, mcp__servers__get_local_server_status, and mcp__servers__stop_local_server.
- CLI fallback:
servers servers:restart, servers servers:status, servers servers:debug, and servers servers:logs.
- Do not
pkill, kill -9, or restart by hand while a server-runtime lock exists. Inspect the lock and coordinate with the owner.
- Always include
--agent <name> and --reason <why>.
- If the start command, cwd, port, or health URL changed, run
servers servers:init ... --force first.
Workflow
-
Inspect the current registered state:
servers servers:status <slug> --refresh
servers servers:debug <slug>
-
If another agent owns the lifecycle lock, either wait intentionally or coordinate:
servers servers:restart <slug> --agent <agent> --reason '<reason>' --wait-lock --lock-timeout 300000
-
Restart and wait for readiness:
servers servers:restart <slug> --agent <agent> --reason '<reason>' --timeout 60000 --stop-timeout 15000
-
Confirm the new process is healthy:
servers servers:status <slug> --refresh
servers servers:logs <slug> --lines 80
-
If readiness fails, use servers servers:debug and logs. The lifecycle runtime should clean up a failed spawned process; do not start another unmanaged process to compensate.
Done When
The restart operation is completed, the observed status is online/ready, the PID/log metadata is current, and traces show who restarted the server and why.
