# service-debugging

A structured backend troubleshooting runbook that guides the agent from symptom gathering and log analysis to root-cause isolation.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · ★ 109
- Author: c0x12c
- License: not stated · policy=link-only · description only; the file stays with the author
- Source: https://github.com/c0x12c/ai-toolkit/tree/HEAD/toolkit/skills/service-debugging/SKILL.md
- Updated: 2026-06-18
- HTML: https://affpapa.org/en/nevibecode/skills/service-debugging

## What it does

This skill guides the agent through investigating backend incidents systematically instead of jumping straight into editing code. First, it collects failure details. The agent determines when the failure started, checks which users are affected, and inspects error messages. It then runs baseline sanity checks using `curl`, `grep`, and `psql` to rule out recent deployments, dropped database connections, or missing environment variables.

Next, the runbook correlates symptoms with targeted checks. A 500 error triggers a stack trace inspection, while slow endpoints call for query profiling via `EXPLAIN`. When regressions appear after a release, the agent relies on `git bisect` and targeted text searches. Before landing any fix, the workflow enforces writing a failing test to prove the bug.

Execution depends on terminal access via `Bash`, `Grep`, `Read`, and `Glob`. Without permission to inspect application logs and run shell checks, the diagnostic steps cannot run.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add c0x12c/ai-toolkit --skill service-debugging -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/service-debugging/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/service-debugging/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add c0x12c/ai-toolkit --skill service-debugging -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/service-debugging/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add c0x12c/ai-toolkit --skill service-debugging -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/service-debugging/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install c0x12c/ai-toolkit service-debugging
```

2. **Manually: put the files in place**
- File: `.github/skills/service-debugging/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add c0x12c/ai-toolkit --skill service-debugging -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/c0x12c/ai-toolkit --path toolkit/skills/service-debugging
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/service-debugging/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add c0x12c/ai-toolkit --skill service-debugging -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/c0x12c/ai-toolkit/tree/HEAD/toolkit/skills/service-debugging/SKILL.md

## When to use it
- Pinpoint backend failures using HTTP status codes and application logs
- Isolate breaking commits across the codebase with git bisect
- Verify database connectivity and environment variables during outages
- Reproduce an incident with a minimal request and a failing test

## Example prompts
- The `/api/orders` endpoint returns 500 errors after our deploy, investigate the issue
- Database responses degraded suddenly, run diagnostics to locate the bottleneck
- The service crashes on startup, check our configuration and container logs

## Similar
- [mcp-builder](https://affpapa.org/en/nevibecode/skills/mcp-builder.md) — skill · 130949 installs
- [claude-api](https://affpapa.org/en/nevibecode/skills/claude-api.md) — skill · 74198 installs
- [lark-im](https://affpapa.org/en/nevibecode/skills/lark-im.md) — skill · 472900 installs
- [lark-event](https://affpapa.org/en/nevibecode/skills/lark-event.md) — skill · 466800 installs
- [caveman-discover](https://affpapa.org/en/nevibecode/skills/caveman-discover.md) — skill · 104400 installs
- [migration](https://affpapa.org/en/nevibecode/skills/migration.md) — skill · 103900 installs

From the same set: [c0x12c/ai-toolkit](https://affpapa.org/en/nevibecode/by/c0x12c/ai-toolkit.md) — 33 cards

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md