Skip to main content
skill CX Codex

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

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add first-fluke/oh-my-agent
/plugin install oma-frontend@oh-my-agent
Open on GitHub

What 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.ts fails with an invalid token exception
  • Find the root cause of the race condition in fetchData and 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-agent

This 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-code

3Manually: put the files in place

~/.claude/skills/oma-debug/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/oma-debug/

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

Similar skills

All skills for Testing and QA →

From the same set69

The whole set →
oma-docs Verifies documentation links, syncs docs against Git diffs, and flags translation drift. Runs through the oma docs CLI or falls back to manual markdown parsing. CX Codex +1 ★ 1,472repo stars oma-scm oma-scm — a skill that gives an agent a safe process for commits, branches, merges and conflict resolution. Use it when repository history matters and a careless force-push is not an option. CX Codex +1 ★ 1,472repo stars oma-skill-creation oma-skill-creation is a Claude Code skill for building and refining OMA skills in SSL-lite format for Claude Code and Codex. It runs during authoring, routing reviews, and contract validation. CX Codex +1 ★ 1,472repo stars oma-mobile oma-mobile — a mobile-focused skill: it builds screens and widgets in Flutter or React Native, wires camera, GPS, push and offline handling, then runs the checks. CX Codex +1 ★ 1,472repo stars oma-qa The oma-qa skill for Claude Code and Codex reviews changes for security, performance, accessibility, and correctness. It checks a diff, runs relevant tools, and reports reproducible findings with fixes. CX Codex +1 ★ 1,472repo stars oma-search oma-search — a skill for Claude Code and Codex that routes queries across external documentation, web search, and remote code. It picks the matching retrieval channel and returns answers backed by citations. CX Codex +1 ★ 1,472repo stars oma-pm oma-pm is a Claude Code skill that turns product requirements into a prioritized task plan with dependencies and acceptance criteria. It prepares the plan before work is handed to specialist agents. CX Codex +1 ★ 1,472repo stars oma-brainstorm oma-brainstorm — a skill for exploring intent, constraints, and alternative approaches before planning or coding. Use it when you have an idea but the path forward is unclear. CX Codex +1 ★ 1,472repo stars

Project sponsors

Companies that keep this analytics open