diagnostic-workflow
The diagnostic-workflow skill provides a structured five-layer troubleshooting sequence for deployment and runtime failures, progressing from deployment status checks through logs and container inspection to HTTP probing. Use it when investigating why an application failed to deploy or is misbehaving at runtime, stopping at the layer that reveals the root cause.
git clone --depth 1 https://github.com/nixopus/nixopus /tmp/diagnostic-workflow && cp -r /tmp/diagnostic-workflow/api/skills/diagnostic-workflow ~/.claude/skills/diagnostic-workflowSKILL.md
# Diagnostic Workflow
**All tools below are runtime tools. Use `search_tools` / `load_tool` to find and load them — do NOT use `skill_read` or `skill_search`.**
## Diagnostic Layers (IN ORDER, stop on root cause)
1. `get_application_deployments` — check deployment history and status
2. `get_deployment_logs` — read build and deploy logs for errors
3. `list_containers` → `search_tools("container logs")` → `load_tool(...)` → load needed tools
4. `get_container_logs` — check container runtime output
5. `search_tools("http probe")` → `load_tool("http_probe")` → probe public URL
If the issue appears application-level, check logs layer by layer. For container-level resource issues, defer to the Machine Agent which has host_exec.
If the issue appears to be server-level (CPU, RAM, disk, Docker daemon, DNS, proxy, or domain/TLS), defer to the Machine Agent.
Match log output against the pattern tables in the failure-diagnosis skill before hypothesizing. Tool 404 → skip layer. Root cause: bold summary, evidence in code block, fix in 1-2 sentences.Reference for all Nixopus API operations callable via nixopus_api(method, path, body)
Generate Caddyfile configurations for static sites and reverse proxies — SPA fallback routing, cache headers, compression, redirects, and error pages. Use when deploying a static site that needs custom Caddy configuration, or when the user needs SPA routing, caching, or redirect rules.
Generate docker-compose.yml for multi-service setups including databases, caches, and service dependencies. Use when the app needs a database, cache, message broker, or has multiple independently deployable services.
Size container memory and CPU limits, diagnose OOM kills and CPU throttling, and recommend resource adjustments by ecosystem. Use when containers are being OOM-killed, running slowly, or when setting initial resource limits for a deployment.
Build and deploy C/C++ applications — CMake, Meson, Ninja, and Dockerfile patterns. Use when deploying a C or C++ project, or when CMakeLists.txt or meson.build is detected.
Run database migrations safely during deployment — framework-specific commands, pre-deploy vs post-deploy timing, health gates, and rollback strategies. Use when the app has a database migration system and needs migrations run during deployment.
Build and deploy Deno applications — version detection, dependency caching, and Dockerfile patterns. Use when deploying a Deno project, or when deno.json or deno.jsonc is detected.
Sub-agent routing table — which agent handles diagnostics, machine health, infrastructure, GitHub, billing, and notifications. Load when the current task is not a direct deployment.