oma-debug — Claude Code skill: what it does, how to install
oma-debug — a skill for Claude Code and Codex isolates bugs, writes targeted fixes, and creates regression tests. Runs when tests fail, services crash, or code suffers from race conditions.
MIT ★ 1,472 updated 2026-11-12
/plugin marketplace add first-fluke/oh-my-agent
/plugin install oma-frontend@oh-my-agentWhat oma-debug does
Compatible with Claude Code and Codex. The skill follows a structured debugging cycle: gathers logs and reproduction steps, inspects source files, isolates the root cause, applies a minimal patch, adds a regression test, and runs verification checks. Guessing fixes is forbidden by its guardrails.
Once a bug is fixed, the agent searches the codebase for matching patterns to prevent identical failures elsewhere. It also writes incident summaries and root-cause analysis directly into .agents/results/bugs/. Running this skill requires functional test, lint, or typecheck commands configured in the repository.
What it helps with
- reproduce runtime crashes and test suite failures
- isolate root causes without expanding code scope
- write regression tests for newly fixed bugs
- document bug forensic records under
.agents/results/bugs/
Example prompts for the agent
- Investigate why
auth_spec.tsfails with an invalid token exception - Find the root cause of the race condition in
fetchDataand add a test - Fix the regression in order processing and record the diagnosis
How to install oma-debug
1Plugin marketplace
/plugin marketplace add first-fluke/oh-my-agent/plugin install oma-frontend@oh-my-agentThis installs the whole oma-frontend plugin with all its skills
2Skills CLI (Vercel)
npx skills add first-fluke/oh-my-agent --skill oma-debug -a claude-code3Manually: put the files in place
~/.claude/skills/oma-debug/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/oma-debug/
1Skills CLI (Vercel)
npx skills add first-fluke/oh-my-agent --skill oma-debug -a codex2Manually: put the files in place
.agents/skills/oma-debug/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add first-fluke/oh-my-agent --skill oma-debug -a cursor2Manually: put the files in place
.cursor/skills/oma-debug/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install first-fluke/oh-my-agent .claude-plugin/domains/frontend/skills/oma-debug2Manually: put the files in place
.github/skills/oma-debug/SKILL.md1Skills CLI (Vercel)
npx skills add first-fluke/oh-my-agent --skill oma-debug -a gemini-cli2Platform CLI
gemini skills install https://github.com/first-fluke/oh-my-agent --path .claude-plugin/domains/frontend/skills/oma-debugManually: put the files in place
.devin/skills/oma-debug/SKILL.mdThe legacy .windsurf/skills/ path still works
Claude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about oma-debug
How to install oma-debug in Claude Code?
Run npx skills add first-fluke/oh-my-agent --skill oma-debug -a claude-code in your terminal.
What does oma-debug do?
It isolates the root cause of reproducible bugs, writes minimal code fixes, verifies changes with regression tests, and logs findings to .agents/results/bugs/.
When should you avoid using oma-debug?
Do not use it for building new features or running general code reviews. The skill focuses solely on bug diagnostics and minimal defect correction.
Source text
SKILL.md · MIT
--- name: oma-debug description: Diagnose a reproducible failure, fix its cause, and verify the regression. Use for crashes, incorrect behavior, and failing tests. --- # Debug Agent - Bug Fixing Specialist ## Scheduling ### Goal Reproduce, diagnose, minimally fix, and regression-test bugs while preserving scope discipline and documenting root cause. ### Intent signature - User reports a bug, crash, traceback, exception, error message, performance issue, intermittent failure, or regression. - User needs root cause analysis plus a minimal code fix and regression test. ### When to use - User reports a bug with error messages - Something is broken and needs fixing - Performance issues or slowdowns - Intermittent failures or race conditions - Regression bugs ### When NOT to use - Building new features -> use Frontend/Backend/Mobile agents - General code review -> use QA Agent ### Expected inputs - Error message, failing behavior, reproduction steps, logs, test failure, or affected code path - Existing tests, stack traces, environment notes, and suspected regression boundary ### Expected outputs - Root cause explanation - Minimal fix scoped to the failing behavior - Regression test or explicit reason it cannot be added - Bug documentation under `.agents/results/bugs/` when appropriate ### Dependencies - `resources/execution-protocol.md`, examples, checklist, common patterns, and debugging checklist - Local codebase search and symbol/reference tools - Project test, lint, typecheck, and runtime commands ### Control-flow features - Branches by reproduction success, error class, suspected layer, and verification outcome - Reads logs/code/tests and writes code/tests/docs - Must search for similar patterns after fixing ## Structural Flow ### Entry 1. Capture the reported symptom and suspected scope. 2. Reproduce or establish the closest reliable failing signal. 3. Identify affected files, tests, and related patterns. ### Scenes 1. **PREPARE**: Gather symptoms, logs, reproduction path, and verification command. 2. **ACQUIRE**: Read failing code, tests, references, and similar patterns. 3. **REASON**: Isolate root cause and reject unsupported hypotheses. 4. **ACT**: Apply minimal fix and regression test. 5. **VERIFY**: Re-run failing and related checks. 6. **FINALIZE**: Document root cause, fix, test, and residual risk. ### Transitions - If reproduction fails, use logs/tests to establish a weaker but explicit diagnostic signal. - If the first fix fails verification, return to root-cause analysis. - If similar patterns exist, inspect and patch only affected cases. - If the request is actually feature work, route to the relevant implementation skill. ### Failure and recovery - If environment is missing, document the blocker and provide the closest static diagnosis. - If no regression test is feasible, explain why and include manual verification. - If fix scope grows, stop and call out the broader design issue. ### Exit - Success: bug is fixed, regression coverage exists, and checks pass. - Partial success: root cause or verification blocker is explicit. ## Logical Operations ### Actions | Action | SSL primitive | Evidence | |--------|---------------|----------| | Reproduce failure | `CALL_TOOL` | Test/runtime/log command | | Search affected code | `READ` | Code, tests, symbols, references | | Compare similar patterns | `COMPARE` | Pattern search | | Infer root cause | `INFER` | Diagnostic reasoning | | Write minimal fix | `WRITE` | Code patch | | Write regression test | `WRITE` | Test patch | | Verify behavior | `VALIDATE` | Tests/checks | | Report result | `NOTIFY` | Root-cause summary | ### Tools and instruments - Project test, lint, typecheck, runtime, and logging commands - Configured code-intelligence symbol/reference/pattern search with native fallback - Debugging checklist and bug report template ### Canonical workflow path Use the configured code-intelligence provider to locate files and inspect symbols or content. For Serena, use `find_file`, `search_for_pattern`, `get_symbols_overview`, and `find_symbol`. Native search is limited to the provider exclusions and non-code paths permitted by the project's search policy. Then run the smallest reproduction command first, establish the causal mechanism, and follow `resources/execution-protocol.md` for the diagnosis record when an OMA workflow is active. Add the regression test and re-run the failing check plus related tests. ### Resource scope | Scope | Resource target | |-------|-----------------| | `CODEBASE` | Failing source, tests, and related patterns | | `LOCAL_FS` | Bug reports and result artifacts | | `PROCESS` | Reproduction and verification commands | | `MEMORY` | Hypotheses, root-cause notes, verification evidence | ### Preconditions - A bug signal, symptom, or failing behavior is available. - Relevant code and verification path can be inspected or the blocker is stated. ### Effects and side effects - Mutates source/tests only as needed for the fix. - May create bug documentation under `.agents/results/bugs/`. ### Guardrails 1. Reproduce first, then diagnose - never guess at fixes 2. Identify root cause, not just symptoms 3. Minimal fix: change only what's necessary 4. Every fix gets a regression test 5. Search for similar patterns elsewhere after fixing 6. Document in `.agents/results/bugs/` ### Code intelligence Use the configured provider to locate the failing function, find callers, and search similar error patterns. Native search and scoped reads are supported fallbacks; see the shared capability contract. ## References - Local code tools: `../_shared/core/code-intelligence.md` (code search/navigation) - Execution steps (follow for the selected task): `resources/execution-protocol.md` - Checklist (pre-submit self-verification): `resources/checklist.md` - Error recovery: `resources/error-playbook.md` - Bug report template: `resources/bug-report-template.md` - Common patterns: `resources/common-patterns.md` - Debugging checklist (investigation guide, used during Steps 1-2): `resources/debugging-checklist.md` - Context loading: `../_shared/core/context-loading.md` - Context budget: `../_shared/core/context-budget.md` - Lessons learned: `../_shared/core/lessons-learned.md` (matching prior failure or requested retrospective) - Observability handoff: `../oma-observability/SKILL.md` §Integrations — traces/logs by `trace_id`, 6-dim forensics
© First Fluke · MIT · first-fluke/oh-my-agent