Service Debugging
c0x12c/ai-toolkit
Structured debugging runbook for backend services. An agent skill from c0x12c/ai-toolkit.
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.
Install Bug Fix Protocol
$ npx skills add CodeAlive-AI/ai-driven-development --skill bug-fix-protocol -a claude-codeProject install by default; add -g for ~/.claude/skills/.
$ gh skill install CodeAlive-AI/ai-driven-development bug-fix-protocol --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/CodeAlive-AI/ai-driven-development.git skills-src && mkdir -p .claude/skills && cp -r skills-src/skills/bug-fix-protocol .claude/skills/bug-fix-protocol && 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 "bug-fix-protocol" agent skill from https://github.com/CodeAlive-AI/ai-driven-development/tree/main/skills/bug-fix-protocol into .claude/skills/bug-fix-protocol/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "bug-fix-protocol", 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/CodeAlive-AI/ai-driven-development/tree/main/skills/bug-fix-protocolType 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 CodeAlive-AI/ai-driven-development --skill bug-fix-protocol -a codexProject install goes to .agents/skills/; add -g for ~/.codex/skills/.
$ gh skill install CodeAlive-AI/ai-driven-development bug-fix-protocol --agent codexProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/CodeAlive-AI/ai-driven-development.git skills-src && mkdir -p .agents/skills && cp -r skills-src/skills/bug-fix-protocol .agents/skills/bug-fix-protocol && rm -rf skills-srcUse ~/.agents/skills/ instead of .agents/skills for a personal install.
Codex skills documentation · loads skills from .agents/skills/
Install the "bug-fix-protocol" agent skill from https://github.com/CodeAlive-AI/ai-driven-development/tree/main/skills/bug-fix-protocol into .agents/skills/bug-fix-protocol/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "bug-fix-protocol", 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 CodeAlive-AI/ai-driven-development --skill bug-fix-protocol -a cursorProject install goes to .agents/skills/; add -g for ~/.cursor/skills/.
$ gh skill install CodeAlive-AI/ai-driven-development bug-fix-protocol --agent cursorProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/CodeAlive-AI/ai-driven-development.git skills-src && mkdir -p .cursor/skills && cp -r skills-src/skills/bug-fix-protocol .cursor/skills/bug-fix-protocol && 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 "bug-fix-protocol" agent skill from https://github.com/CodeAlive-AI/ai-driven-development/tree/main/skills/bug-fix-protocol into .cursor/skills/bug-fix-protocol/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "bug-fix-protocol", 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/CodeAlive-AI/ai-driven-development.git --path skills/bug-fix-protocol--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 CodeAlive-AI/ai-driven-development --skill bug-fix-protocol -a gemini-cliProject install goes to .agents/skills/; add -g for ~/.gemini/skills/.
$ gh skill install CodeAlive-AI/ai-driven-development bug-fix-protocol --agent gemini-cliProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/CodeAlive-AI/ai-driven-development.git skills-src && mkdir -p .gemini/skills && cp -r skills-src/skills/bug-fix-protocol .gemini/skills/bug-fix-protocol && 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 "bug-fix-protocol" agent skill from https://github.com/CodeAlive-AI/ai-driven-development/tree/main/skills/bug-fix-protocol into .gemini/skills/bug-fix-protocol/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "bug-fix-protocol", 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 CodeAlive-AI/ai-driven-development bug-fix-protocolInstalls 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 CodeAlive-AI/ai-driven-development --skill bug-fix-protocol -a github-copilotProject install goes to .agents/skills/; add -g for ~/.copilot/skills/.
$ git clone --depth 1 https://github.com/CodeAlive-AI/ai-driven-development.git skills-src && mkdir -p .github/skills && cp -r skills-src/skills/bug-fix-protocol .github/skills/bug-fix-protocol && 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 "bug-fix-protocol" agent skill from https://github.com/CodeAlive-AI/ai-driven-development/tree/main/skills/bug-fix-protocol into .github/skills/bug-fix-protocol/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "bug-fix-protocol", 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 CodeAlive-AI/ai-driven-development --skill bug-fix-protocol -a opencodeOpenCode documents no install command of its own. Project install goes to .agents/skills/; add -g for ~/.config/opencode/skills/.
$ gh skill install CodeAlive-AI/ai-driven-development bug-fix-protocol --agent opencodeProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/CodeAlive-AI/ai-driven-development.git skills-src && mkdir -p .opencode/skills && cp -r skills-src/skills/bug-fix-protocol .opencode/skills/bug-fix-protocol && 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 "bug-fix-protocol" agent skill from https://github.com/CodeAlive-AI/ai-driven-development/tree/main/skills/bug-fix-protocol into .opencode/skills/bug-fix-protocol/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "bug-fix-protocol", 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
bug-fix-protocol- GitHub stars
- 155
- Token cost
- ~648 tokens
- SKILL.md length
- 334 words
- Files
- 2
- Skills in repo
- 22
- Repo updated
- First seen
- Licence
- MIT
At a glance
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.
- Works in 8 steps: Analyze and reproduce requirements.… → Write a failing test (red). Encode the… → Trace root cause. Walk the failing test… → …
- Fixing a production bug
- SKILL.md covers When to apply, The eight steps (summary), Output expectations and Reference
- Instructions only: no scripts, shell commands, URLs or credentials in SKILL.md
What it does
Bug Fix Protocol is an agent skill from 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. Use when fixing a production bug, investigating a regression, writing a post-mortem, or auditing a missed defect. Triggers on "fix this bug", "production bug", "regression test", "post-mortem", "test gap", "why did the tests miss this".
Its SKILL.md is about 650 tokens, which your agent loads only when the skill is triggered. The skill folder holds 1 other file (for example `PROTOCOL.md`).
It sits in Development, covering Debugging and Runbooks and postmortems. The repository describes itself as: Practices, protocols, and skills for AI-driven software development. Skills and safety hooks for Claude Code, Codex, OpenCode, Cursor, Antigravity, and any agent supporting the… The licence is MIT.
When your agent uses it
- Fixing a production bug
- Investigating a regression
- Writing a post-mortem
- Auditing a missed defect
Example prompts
- “fix this bug”
- “production bug”
- “regression test”
- “/bug-fix-protocol”
Workflow steps
8 steps, taken from the first numbered list in SKILL.md.
- Analyze and reproduce requirements. Understand exact actual vs expected behaviour; identify minimal repro path; ask the user before…
- Write a failing test (red). Encode the bug as a test that fails for the right reason. No code change yet.
- Trace root cause. Walk the failing test back through the system. Stop at the smallest place that, if changed, makes the test pass.
- Apply the minimal fix. Smallest possible change. No drive-by refactors.
- Verify green locally. Failing test now passes; no other tests regressed.
- Run the full suite + lints + types. Catch indirect regressions.
- Document the fix. Commit message and PR description name the symptom, the root cause, and the fix in one sentence each.
- Audit the testing system (the most important step). Ask: which layer should have caught this, and why didn't it? Then change that layer so…
What it can do on your machine
Read from SKILL.md and the folder at commit 25b7b1d. It shows what the files ask for, not the result of running them.
Tool permissions
Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.
From allowed-tools in the SKILL.md frontmatter.
Runs code
No scripts in the folder and no shell commands in SKILL.md.
From the folder's file list and the shell code blocks in SKILL.md.
Network
No URLs in SKILL.md.
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
Bug Fix Protocol loads about 648 tokens when it runs. Until then it costs about 103 tokens; SKILL.md has 334 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 passed
The automated check found no risky patterns in SKILL.md.
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 CodeAlive-AI/ai-driven-development at commit 25b7b1d, republished under its MIT licence (© CodeAlive-AI). 334 words, ~648 tokens.
Download SKILL.mdSave it as
.claude/skills/bug-fix-protocol/SKILL.md (or your agent's skills folder). This skill also uses 1 other file; get the full folder from GitHub.- name
- bug-fix-protocol
- description
- 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. Use when fixing a production bug, investigating a regression, writing a post-mortem, or auditing a missed defect. Triggers on "fix this bug", "production bug", "regression test", "post-mortem", "test gap", "why did the tests miss this".
Bug Fix Protocol
A bug fix is two fixes in one: fix the code, and fix the testing system that let the bug through. Skipping the second step means the same class of bug ships again.
The full protocol (philosophy, eight steps with examples, audit checklist, anti-patterns) lives in PROTOCOL.md. Read it before applying.
When to apply
Use this protocol whenever a defect reaches production, staging, or a customer environment. Do not use it for bugs caught locally during normal development — those are part of the writing process, not testing-system failures.
The eight steps (summary)
- Analyze and reproduce requirements. Understand exact actual vs expected behaviour; identify minimal repro path; ask the user before guessing on ambiguities.
- Write a failing test (red). Encode the bug as a test that fails for the right reason. No code change yet.
- Trace root cause. Walk the failing test back through the system. Stop at the smallest place that, if changed, makes the test pass.
- Apply the minimal fix. Smallest possible change. No drive-by refactors.
- Verify green locally. Failing test now passes; no other tests regressed.
- Run the full suite + lints + types. Catch indirect regressions.
- Document the fix. Commit message and PR description name the symptom, the root cause, and the fix in one sentence each.
- Audit the testing system (the most important step). Ask: which layer should have caught this, and why didn't it? Then change that layer so it would catch the next instance — new test type, new fixture, new lint rule, new property test, new contract assertion. A fix without step 8 is incomplete.
Output expectations
When applying the protocol, return:
- The repro test (red, then green).
- The minimal code fix.
- A one-paragraph step-8 audit naming the missed coverage layer and the change made to close the gap.
If step 8 produces "we couldn't have caught this," investigate further — that answer is almost always wrong, and accepting it is how the testing system stagnates.
Reference
Full text: PROTOCOL.md.
© CodeAlive-AI, 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 1 other file in skills/bug-fix-protocol of CodeAlive-AI/ai-driven-development.
- SKILL.md
- PROTOCOL.md
Open the folder on GitHubat commit 25b7b1d
Compare with similar skills
Bug Fix Protocol 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 |
|---|---|---|---|---|---|---|
| Bug Fix Protocol this skillCodeAlive-AI/ai-driven-development | 155 | — | ~648 | Automated safety check: Pass | MIT | |
| Service Debuggingc0x12c/ai-toolkit | 106 | — | ~981 | Automated safety check: Pass | None | |
| Debuggingnotque/vexjoy-agent | 435 | — | ~1.9k | Automated safety check: Notes | 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
Debugging
notque/vexjoy-agent
Debugging: guided diagnosis of application bugs, and post-mortem of failed agent sessions.
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 CodeAlive-AI/ai-driven-development
All 22 skills in this repoInvestigating Repository History
CodeAlive-AI/ai-driven-development
Investigate GitHub repository history before risky code changes using git blame/log, GitHub PRs, review comments, squash/rebase/cherry-pick/rename heuristics, and cited evidence.
Plugins Management
CodeAlive-AI/ai-driven-development
Create, publish, delete, and submit plugins for coding agents (Claude Code, OpenCode, Devin CLI/Desktop).
Semantic Scholar Deep
CodeAlive-AI/ai-driven-development
Deep research over the Semantic Scholar Graph API. An agent skill from CodeAlive-AI/ai-driven-development.
Windows QA Engineer
CodeAlive-AI/ai-driven-development
A skill your agent uses when testing Windows 11 desktop apps (WinForms/WPF/UWP) via UFO UIA/Win32 automation MCP.
Agentic Readiness
CodeAlive-AI/ai-driven-development
Audit and improve repositories for reliable agentic work across Codex and Codex App, Claude Code, and OpenCode.
Hooks Management
CodeAlive-AI/ai-driven-development
Manage hooks and automation for coding agents (Claude Code, Codex CLI, OpenCode, Devin CLI/Desktop).
Related
Categories
Questions about Bug Fix Protocol
What does Bug Fix Protocol do?
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. Bug Fix Protocol is an agent skill from 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.
When should I use Bug Fix Protocol?
Bug Fix Protocol fits situations like: fixing a production bug; investigating a regression; writing a post-mortem; auditing a missed defect.
How do I install Bug Fix Protocol in Claude Code?
Run `npx skills add CodeAlive-AI/ai-driven-development --skill bug-fix-protocol -a claude-code`. Or copy the skill folder (skills/bug-fix-protocol in CodeAlive-AI/ai-driven-development) into .claude/skills/bug-fix-protocol in your project. Claude Code loads it when a task matches its description.
How do I install Bug Fix Protocol in Codex?
Run `npx skills add CodeAlive-AI/ai-driven-development --skill bug-fix-protocol -a codex`. Or copy the skill folder (skills/bug-fix-protocol in CodeAlive-AI/ai-driven-development) into .agents/skills/bug-fix-protocol in your project. Codex loads it when a task matches its description.
Can I use Bug Fix Protocol 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 CodeAlive-AI/ai-driven-development --skill bug-fix-protocol -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/bug-fix-protocol, .gemini/skills/bug-fix-protocol, .github/skills/bug-fix-protocol and .opencode/skills/bug-fix-protocol in your project.
What does Bug Fix Protocol need to run?
SKILL.md names no scripts, command-line tools or credentials: Bug Fix Protocol is instructions for the agent only.
Does Bug Fix Protocol access the network?
SKILL.md contains no URLs. Any network use would come from the scripts or tools the agent runs. This is read from the text; nothing was executed.
Is Bug Fix Protocol safe to install?
Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.
What licence does Bug Fix Protocol use?
Bug Fix Protocol 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 Bug Fix Protocol use?
About 648 tokens (SKILL.md is roughly 2.6k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.
What are the alternatives to Bug Fix Protocol?
Skills that share tags, products or a category with Bug Fix Protocol: Service Debugging (c0x12c/ai-toolkit, 106 stars), Debugging (notque/vexjoy-agent, 435 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 Bug Fix Protocol?
CodeAlive-AI (a GitHub organization) maintains it in CodeAlive-AI/ai-driven-development, which has 155 GitHub stars. The repository holds 22 skills in this directory. The repository was last updated on October 6, 2026.
Source: CodeAlive-AI/ai-driven-development on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.