Service Debugging
c0x12c/ai-toolkit
Structured debugging runbook for backend services. An agent skill from c0x12c/ai-toolkit.
Debugging: guided diagnosis of application bugs, and post-mortem of failed agent sessions.
Install Debugging
$ npx skills add notque/vexjoy-agent --skill debugging -a claude-codeProject install by default; add -g for ~/.claude/skills/.
$ gh skill install notque/vexjoy-agent debugging --agent claude-codeProject scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).
$ git clone --depth 1 https://github.com/notque/vexjoy-agent.git skills-src && mkdir -p .claude/skills && cp -r skills-src/skills/process/debugging .claude/skills/debugging && rm -rf skills-srcUse ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.
Claude Code skills documentation · loads skills from .claude/skills/
Install the "debugging" agent skill from https://github.com/notque/vexjoy-agent/tree/main/skills/process/debugging into .claude/skills/debugging/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "debugging", then confirm the skill loads.Claude Code copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$skill-installer install https://github.com/notque/vexjoy-agent/tree/main/skills/process/debuggingType this inside Codex. $skill-installer <name> installs a curated skill from openai/skills. The installer writes to $CODEX_HOME/skills (default ~/.codex/skills). Restart Codex if the skill does not show up.
$ npx skills add notque/vexjoy-agent --skill debugging -a codexProject install goes to .agents/skills/; add -g for ~/.codex/skills/.
$ gh skill install notque/vexjoy-agent debugging --agent codexProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/notque/vexjoy-agent.git skills-src && mkdir -p .agents/skills && cp -r skills-src/skills/process/debugging .agents/skills/debugging && rm -rf skills-srcUse ~/.agents/skills/ instead of .agents/skills for a personal install.
Codex skills documentation · loads skills from .agents/skills/
Install the "debugging" agent skill from https://github.com/notque/vexjoy-agent/tree/main/skills/process/debugging into .agents/skills/debugging/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "debugging", then confirm the skill loads.Codex copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ npx skills add notque/vexjoy-agent --skill debugging -a cursorProject install goes to .agents/skills/; add -g for ~/.cursor/skills/.
$ gh skill install notque/vexjoy-agent debugging --agent cursorProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/notque/vexjoy-agent.git skills-src && mkdir -p .cursor/skills && cp -r skills-src/skills/process/debugging .cursor/skills/debugging && rm -rf skills-srcUse ~/.cursor/skills/ instead of .cursor/skills for a personal install.
Cursor skills documentation · loads skills from .cursor/skills/, .agents/skills/, .claude/skills/, .codex/skills/
Install the "debugging" agent skill from https://github.com/notque/vexjoy-agent/tree/main/skills/process/debugging into .cursor/skills/debugging/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "debugging", then confirm the skill loads.Cursor copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ gemini skills install https://github.com/notque/vexjoy-agent.git --path skills/process/debugging--scope user (default) or --scope workspace; --path is the subfolder of the repo that holds the skill; --consent skips the security confirmation prompt.
$ npx skills add notque/vexjoy-agent --skill debugging -a gemini-cliProject install goes to .agents/skills/; add -g for ~/.gemini/skills/.
$ gh skill install notque/vexjoy-agent debugging --agent gemini-cliProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/notque/vexjoy-agent.git skills-src && mkdir -p .gemini/skills && cp -r skills-src/skills/process/debugging .gemini/skills/debugging && rm -rf skills-srcUse ~/.gemini/skills/ instead of .gemini/skills for a personal install, then run /skills reload.
Gemini CLI skills documentation · loads skills from .gemini/skills/, .agents/skills/
Install the "debugging" agent skill from https://github.com/notque/vexjoy-agent/tree/main/skills/process/debugging into .gemini/skills/debugging/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "debugging", then confirm the skill loads.Gemini CLI copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ gh skill install notque/vexjoy-agent debuggingInstalls for Copilot at project scope by default; add --scope user for a personal install. Preview a skill first with gh skill preview. Needs GitHub CLI 2.90.0 or later (public preview).
$ npx skills add notque/vexjoy-agent --skill debugging -a github-copilotProject install goes to .agents/skills/; add -g for ~/.copilot/skills/.
$ git clone --depth 1 https://github.com/notque/vexjoy-agent.git skills-src && mkdir -p .github/skills && cp -r skills-src/skills/process/debugging .github/skills/debugging && rm -rf skills-srcUse ~/.copilot/skills/ instead of .github/skills for a personal install. Commit .github/skills so cloud agent and code review can use it.
GitHub Copilot skills documentation · loads skills from .github/skills/, .claude/skills/, .agents/skills/
Install the "debugging" agent skill from https://github.com/notque/vexjoy-agent/tree/main/skills/process/debugging into .github/skills/debugging/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "debugging", then confirm the skill loads.GitHub Copilot copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ npx skills add notque/vexjoy-agent --skill debugging -a opencodeOpenCode documents no install command of its own. Project install goes to .agents/skills/; add -g for ~/.config/opencode/skills/.
$ gh skill install notque/vexjoy-agent debugging --agent opencodeProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/notque/vexjoy-agent.git skills-src && mkdir -p .opencode/skills && cp -r skills-src/skills/process/debugging .opencode/skills/debugging && rm -rf skills-srcUse ~/.config/opencode/skills/ instead of .opencode/skills for a personal install.
OpenCode skills documentation · loads skills from .opencode/skills/, .claude/skills/, .agents/skills/
Install the "debugging" agent skill from https://github.com/notque/vexjoy-agent/tree/main/skills/process/debugging into .opencode/skills/debugging/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "debugging", then confirm the skill loads.OpenCode copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
Facts
- Skill name
debugging- GitHub stars
- 435
- Token cost
- ~1.9k tokens
- SKILL.md length
- 909 words
- Files
- 3 (incl. references)
- Skills in repo
- 61
- Repo updated
- First seen
- Licence
- MIT
At a glance
Debugging: guided diagnosis of application bugs, and post-mortem of failed agent sessions.
- Works in 3 steps: GATHER → DETECT → REPORT
- Tasks that involve Debugging
- SKILL.md covers Mode 1: Socratic Debugging, Mode 2: Forensics (Post-Mortem) and Deep References
- Calls git
What it does
Debugging is an agent skill from notque/vexjoy-agent. Debugging: guided diagnosis of application bugs, and post-mortem of failed agent sessions.
Its SKILL.md is about 1.9k tokens, which your agent loads only when the skill is triggered. The skill folder holds 3 other files, including reference files (for example `references/detectors.md` and `references/failure-signatures.md`).
It sits in Development, covering Debugging and Runbooks and postmortems. The repository describes itself as: VexJoy AI Agent with Jev Intelligent Routing - /do routes plain-English requests to the right specialist agent and gates the work with reviews, tests, and a learning loop. The licence is MIT.
When your agent uses it
- Tasks that involve Debugging
- Tasks that involve Runbooks and postmortems
Example prompts
- “/debugging”
Requirements
- Pre-approved tools (allowed-tools): Read, Grep, Glob, Bash
Workflow steps
3 steps, taken from the step headings in SKILL.md.
What it can do on your machine
Read from SKILL.md and the folder at commit 5218674. It shows what the files ask for, not the result of running them.
Tool permissions
Pre-approves these tools, so the agent can use them without asking each time:
ReadGrepGlobBash
From allowed-tools in the SKILL.md frontmatter.
Runs code
Shell commands in SKILL.md call:
git
From the folder's file list and the shell code blocks in SKILL.md.
Network
No URLs in SKILL.md. Its commands use git, which can reach the network depending on how they are called.
From URLs in SKILL.md, links to its own repository left out.
Credentials
Names no API keys, tokens, secrets or passwords.
From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.
Context cost
Debugging loads about 1.9k tokens when it runs, and up to ~6k if it reads all its reference files. Until then it costs about 25 tokens; SKILL.md has 909 words of instructions outside code blocks.
Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.
Safety
Auto-check: notes
The automated check noted patterns worth knowing about, such as sudo or a known installer.
- NotePre-approves every shell command (allowed-tools: Bash)SKILL.md
allowed-tools: Read, Grep, Glob, Bash
Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.
SKILL.md
The full file from notque/vexjoy-agent at commit 5218674, republished under its MIT licence (© notque). 909 words, ~1,924 tokens.
Download SKILL.mdSave it as
.claude/skills/debugging/SKILL.md (or your agent's skills folder). This skill also uses 2 other files; get the full folder from GitHub.- name
- debugging
- description
- Debugging: guided diagnosis of application bugs, and post-mortem of failed agent sessions.
- allowed-tools
- Read, Grep, Glob, Bash
- user-invocable
- false
- routing.not_for
- code review (use review), building features (use workflow)
- routing.triggers
- guide debugging, question-based, teach debugging, ask me questions, help me think through, guide me, coaching mode, teach me to find it, forensics, what went…
- routing.category
- process
- routing.pairs_with
- workflow, review
Debugging Skill
Two modes. Pick one based on the request:
| Signal | Mode |
|---|---|
| Guide me, teach debugging, ask me questions, coaching | Socratic |
| What went wrong, post-mortem, stuck loop, session crashed | Forensics |
Mode 1: Socratic Debugging
Guide the user to discover root causes through structured inquiry. Never give the answer -- the user must arrive at it. Read relevant code with Read/Grep/Glob before formulating questions; code knowledge makes questions precise.
Question Progression
Follow these 9 phases in order. Each builds evidence for the next.
| Phase | Purpose | Example |
|---|---|---|
| 1. Symptoms | Gap between expected and actual | "What did you expect?" / "What happened instead?" |
| 2. Reproducibility | Deterministic or intermittent | "Can you reproduce this consistently?" |
| 3. Prior Attempts | Avoid retreading | "What have you already tried?" |
| 4. Minimal Case | Reduce search space | "What is the smallest failing input?" |
| 5. Error Analysis | Extract signal from output | "Which part of the error message is most informative?" |
| 6. State Inspection | Ground in actual data | "What is the value of X right before the error?" |
| 7. Code Walkthrough | Surface hidden assumptions | "Can you explain what this function does, line by line?" |
| 8. Assumption Audit | Challenge mental model | "What are you assuming that you haven't verified?" |
| 9. Hypothesis | Build investigative instinct | "Where do you think the problem is? Why there?" |
Execution
- User describes the bug. Read relevant code silently.
- Ask one Phase 1 question. No preamble, no diagnosis, no code references.
- Listen. Acknowledge briefly. Ask the next question toward root cause.
- After 12 questions without progress, offer escalation (see below).
- When user identifies root cause, confirm and ask what fix they would apply.
One question at a time. Mirror user terminology. Acknowledge discoveries before the next question. Open-ended questions that narrow focus are good hints; leading questions that contain the answer are violations.
Escalation
After 12 questions without progress, offer: "Would you like to switch to direct
debugging mode?" If accepted, call workflow with systematic-debugging,
passing: symptoms, what was tried, current hypothesis, relevant files/lines.
Error Handling
| Situation | Action |
|---|---|
| User says "just tell me" | Offer mode switch. If accepted, hand off to workflow. |
| User frustrated | Acknowledge. Offer escalation. If continuing, read more code and sharpen questions. |
| Bug trivially obvious | Still ask Phase 1, but make the question pointed enough that the user sees it immediately. |
Mode 2: Forensics (Post-Mortem)
Investigate failed or stuck agent sessions through git history, plan files, and session artifacts. Read-only -- never modify state. Even when asked to fix, complete the report and recommend remediation instead.
Key distinction: Tool errors ("ruff found 3 lint errors") are harness-level. Forensics handles workflow-level patterns ("agent edited the same file 5 times and never progressed").
Phase 1: GATHER
Collect raw evidence. Determine branch, plan, and time range.
Step 1: Identify target. Priority: explicit branch > current branch > explicit plan. Read CLAUDE.md if present -- conventions define "normal."
Step 2: Locate plan file. Check task_plan.md, .feature/state/plan/,
plan/active/. Record whether found. Three of five detectors work without a
plan (stuck loop, crash, degraded abandoned work), so never skip analysis for
a missing plan.
Step 3: Collect git history. Run git log main..HEAD --name-only --format="COMMIT %H %ai %s".
Check file change frequency, retry/fix language in messages, and commit message
uniqueness ratio. Focus on most recent 50 commits if the branch has hundreds.
Step 4: Check working tree. Run git status --short, check for orphaned
worktrees (git worktree list --porcelain | grep "prunable"), and locate plan files.
GATE: Git history available, branch identified. Proceed to DETECT.
Show full SKILL.md (340 more words)Show less
Phase 2: DETECT
Run all 5 anomaly detectors. Always run every detector -- anomalies correlate (stuck loop causes missing artifacts causes abandoned work). Each finding needs a confidence level (High/Medium/Low).
Run in order: Stuck Loop, Missing Artifacts, Abandoned Work, Scope Drift, Crash/Interruption. Load detector specs and failure signatures from the deep references below.
GATE: All 5 detectors ran. Each produced zero or more findings with confidence levels.
Phase 3: REPORT
Every claim must trace to specific evidence.
Step 1: Scrub. Scan evidence for sk-, ghp_, token=, password=,
secret=, key=, bearer tokens, base64 credentials. Replace with [REDACTED].
Replace absolute home paths with ~/.
Step 2: Anomaly table. Order by confidence (High first), then detector number.
Step 3: Root cause hypothesis. Connect anomalies into a causal chain. Must be specific, testable, evidence-grounded.
- Bad: "Something went wrong"
- Good: "Agent entered a lint fix loop on server.go (4 commits with 'fix lint'), consuming context before VERIFY could run, leaving test artifacts missing"
Step 4: Remediation. Advisory only -- never execute fixes.
| Anomaly | Typical Fix |
|---|---|
| Stuck loop | Identify root cause of loop. Fix manually, resume from last successful phase. |
| Missing artifacts | Re-run the failed phase. Clarify artifact definitions. |
| Abandoned work | Resume from last completed phase. Check plan status. |
| Scope drift | Review out-of-scope changes. Revert unrelated ones. |
| Crash/interruption | Preserve uncommitted changes. Clean orphaned worktrees. Resume from last commit. |
Step 5: Format report with sections: header (branch, commit count, plan path), anomaly table, root cause hypothesis, remediation list, evidence excerpts. All paths redacted, credentials scrubbed.
GATE: Report complete, scrubbed, formatted. Deliver to user.
Forensics Error Handling
| Error | Action |
|---|---|
| No git history | Report "insufficient evidence." |
| No plan file | Note limitation. Detectors 2/3/4 degrade or skip. 1/5 still work. |
| Orphaned worktree | Report as crash/interruption evidence. Do not clean up. |
| Git log too large | Focus on most recent 50 commits. Note truncation. |
| Ambiguous target | Ask: "Which branch? Current is [X]." |
Deep References
| When | Load | Content |
|---|---|---|
| Running Phase 2 detectors | references/detectors.md | 5 detector specs with confidence scoring tables and false-positive guidance |
| Matching symptoms to failure types | references/failure-signatures.md | Observable patterns, grep commands, causal chain analysis |
© notque, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file
Files
SKILL.md and 2 other files (references) in skills/process/debugging of notque/vexjoy-agent.
- SKILL.md
- references/detectors.md
- references/failure-signatures.md
Open the folder on GitHubat commit 5218674
Compare with similar skills
Debugging next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.
| Skill | Stars | Used in | Tokens | Auto-check | Licence | Repo updated |
|---|---|---|---|---|---|---|
| Debugging this skillnotque/vexjoy-agent | 435 | — | ~1.9k | Automated safety check: Notes | MIT | |
| Service Debuggingc0x12c/ai-toolkit | 106 | — | ~981 | Automated safety check: Pass | None | |
| Bug Fix ProtocolCodeAlive-AI/ai-driven-development | 155 | — | ~648 | Automated safety check: Pass | MIT | |
| Codebase Onboardingborghei/Claude-Skills | 874 | — | ~1.7k | Automated safety check: Pass | MIT | |
| Flowfile Node DevelopmentEdwardvaneechoud/Flowfile | 370 | — | ~9.3k | Automated safety check: Pass | MIT | |
| RAG Troubleshootlyonzin/knowledge-rag | 290 | — | ~1.8k | Automated safety check: Pass | MIT |
Similar skills
Bug Fix Protocol
CodeAlive-AI/ai-driven-development
8-step disciplined bug-fix protocol that treats every production bug as two failures — the code defect itself and the testing system that allowed it through.
Codebase Onboarding
borghei/Claude-Skills
Analyze a codebase and generate onboarding docs: architecture overviews, file maps, setup guides, runbooks, and debugging guides.
Flowfile Node Development
Edwardvaneechoud/Flowfile
End-to-end runbook for adding or modifying a Flowfile node type across all four layers (flowfilecore settings/graph/template, flowfilefrontend UI registry, flowfileframe Python API, flowfilewasm…
RAG Troubleshoot
lyonzin/knowledge-rag
When the user reports a bug, error message, stack trace, unexpected behavior, or "why is this broken" question, search the corpus first for prior occurrences, known fixes, or related runbooks.
Workflow Triaging
adobe/skills
Triage AEM Workflow issues on AEM 6.5 LTS and AMS by classifying symptoms, gathering the right logs and metrics, and mapping to runbooks or Splunk searches.
More from notque/vexjoy-agent
All 61 skills in this repoGame Asset Generator
notque/vexjoy-agent
Deterministic palette/matrix pixel art (not AI). An agent skill from notque/vexjoy-agent.
PR Workflow
notque/vexjoy-agent
Pull request lifecycle: commit, codex review, sync, review, fix, status, cleanup, and PR mining.
Architecture Deepening
notque/vexjoy-agent
Improve architecture across modules by deepening interfaces.
Code Quality
notque/vexjoy-agent
Code quality: cleanup, linting, formatting, quality gates. An agent skill from notque/vexjoy-agent.
Codebase Analyzer
notque/vexjoy-agent
Statistical rule discovery from Go codebase patterns. An agent skill from notque/vexjoy-agent.
Comment Quality
notque/vexjoy-agent
Review and fix temporal references in code comments. An agent skill from notque/vexjoy-agent.
Related
Categories
Questions about Debugging
What does Debugging do?
Debugging: guided diagnosis of application bugs, and post-mortem of failed agent sessions. Debugging is an agent skill from notque/vexjoy-agent. Debugging: guided diagnosis of application bugs, and post-mortem of failed agent sessions.
When should I use Debugging?
Debugging fits situations like: tasks that involve Debugging; tasks that involve Runbooks and postmortems.
How do I install Debugging in Claude Code?
Run `npx skills add notque/vexjoy-agent --skill debugging -a claude-code`. Or copy the skill folder (skills/process/debugging in notque/vexjoy-agent) into .claude/skills/debugging in your project. Claude Code loads it when a task matches its description.
How do I install Debugging in Codex?
Run `npx skills add notque/vexjoy-agent --skill debugging -a codex`. Or copy the skill folder (skills/process/debugging in notque/vexjoy-agent) into .agents/skills/debugging in your project. Codex loads it when a task matches its description.
Can I use Debugging in Cursor, Gemini CLI or GitHub Copilot?
Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add notque/vexjoy-agent --skill debugging -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/debugging, .gemini/skills/debugging, .github/skills/debugging and .opencode/skills/debugging in your project.
What does Debugging need to run?
Going by SKILL.md and its folder, Debugging needs the command-line tools its instructions call (git). Its frontmatter pre-approves these tools: Read, Grep, Glob, Bash.
Does Debugging access the network?
SKILL.md contains no URLs. Its commands use git, which can reach the network depending on how they are called. This is read from the text; nothing was executed.
Is Debugging safe to install?
Our automated static check of SKILL.md found notes only (pre-approves every shell command (allowed-tools: bash)), nothing it rates as a warning. It is not a guarantee. Review the folder before installing.
What licence does Debugging use?
Debugging is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.
How many tokens does Debugging use?
About 1.9k tokens (SKILL.md is roughly 7.7k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full. Its references folder adds about 4.1k tokens, read only when the agent opens those files.
What are the alternatives to Debugging?
Skills that share tags, products or a category with Debugging: Service Debugging (c0x12c/ai-toolkit, 106 stars), Bug Fix Protocol (CodeAlive-AI/ai-driven-development, 155 stars), Codebase Onboarding (borghei/Claude-Skills, 874 stars) and Flowfile Node Development (Edwardvaneechoud/Flowfile, 370 stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.
Who maintains Debugging?
notque (a GitHub user) maintains it in notque/vexjoy-agent, which has 435 GitHub stars. The repository holds 61 skills in this directory. The repository was last updated on October 3, 2026.
Source: notque/vexjoy-agent on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.