Mmcp.market

debugging skill

by code-yeongyu·code-yeongyu/oh-my-openagent·70k stars

Runs a hypothesis-driven debugging loop across any language or binary, escalating to orthogonal oracle angles and locking the fix with a failing test. Use for crashes, silent failures, hangs, wrong responses, memory leaks, async misbehavior, or reverse engineering.

A100/100content scan

Is the debugging skill safe?

Clean: nothing in its files matched our rules. We read 25 files in the folder on 2026-09-28.

No findings.

Install the debugging skill

A skill is a folder. Copy it into your agent's skills folder and the agent loads it when the task matches its description. 

git clone --depth 1 https://github.com/code-yeongyu/oh-my-openagent.git /tmp/oh-my-openagent
mkdir -p ~/.claude/skills
cp -r /tmp/oh-my-openagent/packages/shared-skills/skills/debugging ~/.claude/skills/debugging
available in every project

In the Claude apps, zip the folder and upload it from the Skills settings. The folder on GitHub

The instructions your agent would load

SKILL.md as published, without the frontmatter. Read it on GitHub

Debugging

You are a hypothesis-driven debugger. Two disciplines apply regardless of language, runtime, or whether you have source:

  1. Runtime truth beats code reading. Every claim about why the bug happens must come from observed state — never from a plausible story spun from reading code.
  2. Leave no trace. Debugging creates artifacts. Every artifact is journaled and removed before you call the task done.

The rest of this file is a map. The knowledge is in references/. This file cannot teach you how to debug — it can only tell you which reference will, for your exact situation.

🚨 READ THE REFERENCES. THIS IS NOT OPTIONAL.

This skill is intentionally small. Ninety percent of what you need to know lives in references/. If you skim this file and start working without opening the references, you will reattach a debugger the wrong way, miss a silent-failure pattern you've never seen before, waste an hour on a source-map gotcha, or invent a worse version of a tool that already solves your problem.

Every reference below is mandatory when its scenario applies. "I know this language" is not an exemption. The references exist because every runtime and every specialist tool has at least one gotcha that silently wastes hours, and you will not know which gotcha until you read the file.

The gate rule: before you run a command from a given reference's domain, you must have read that reference in this session. Re-reading across sessions is cheap. Guessing is expensive.

Runtime Setup — MANDATORY READING BEFORE ATTACHING

The methodology is language-agnostic. The commands to launch, attach, breakpoint, and inspect are not. Open the matching reference before Phase 0. Not during. Not after.

If you cannot honestly say you just opened the reference for your runtime, open it now.

🚨 Native binary vs bundled binary — check before committing: file ./target calls them both Mach-O / ELF. The 30-second discriminator is du -h ./target (50 MB+ suspect bundled) plus strings -n 12 ./target | rg -iE 'bun|nodemodules|webpack|esbuild|deno|pkg/lib|electron|pyinstaller|nexe|NODESEA_FUSE|tauri'. If hits → bundled-js-binary.md. If clean → native-binary.md.

Specialist Tools — ACTIVELY USE WHEN THE SCENARIO FITS

These are not "optional extras". They are the correct tool in their domain, and anything else is slower and less reliable. If the bug fits the domain, you MUST use the tool. Read the reference first to know how.

Failing to use these tools in their domain is a process failure, not a stylistic choice. If the bug is in a browser and you did Phase 8 without Playwright, you are doing it wrong. If the bug is in a stripped binary and you read hex with xxd, you are doing it wrong. The references tell you how. Read them.

The Phase Loop — READ THE REFERENCE FOR THE PHASE YOU ARE ENTERING

Each phase has exactly one reference. Read it as you enter the phase — not in advance, not from memory. The references are self-contained and short.

Phase references are short by design. Reading one takes a minute. Skipping one costs an hour.

Cross-cutting methodology references

These are not phases — read them when the situation calls for them:

Non-Negotiable Safety Invariants

  1. Runtime state is the only source of truth. A hypothesis without an observed value is a guess. Do not fix guesses.
  2. Every debug artifact is journaled before it is created. Journal-then-modify, not modify-then-remember-maybe.
  3. Never ship a fix without its reproduction. The failing case captured BEFORE the fix, the same case passing after it, or the fix is unverified. Where the repository keeps tests for this behavior, that case is the regression test.
  4. Never declare done on type-check/compile alone. Types catch declaration bugs. Only running the actual user scenario catches the actual user bug.
  5. Never ask the user a question that runtime evidence can already answer. Escalation is for genuine ambiguity.
  6. Never silently swallow errors while debugging. If the system swallows errors, that is often the bug itself. Make them loud temporarily; restore at cleanup.
  7. Never git commit from inside this skill. Commits belong to /git-master after the user confirms the fix.
  8. Never attach without having read the runtime reference. The gate rule.

What to Do Right Now

  1. Read the user's bug description.
  2. Identify the runtime.
  3. Open references/runtimes/.md. Read it.
  4. Identify which specialist tools apply. Open each matching references/tools/.md.** Read them.
  5. Open references/methodology/00-setup.md and start Phase 0.
  6. Follow the phase loop. Read each methodology reference as you enter the phase.

The references are the skill. This file is an index.

More skills from code-yeongyu/oh-my-openagent

  • Aast-grepSearches and rewrites code by AST shape across 25 languages. Use when the target is a syntax pattern (every call/class/import shaped like X, a codemod, a YAML rule) rather than literal text; for plain strings, comments, or filenames, use rg.
  • AbrowserDrives a real browser through the omowright library from the js eval kernel: sites the user is already signed into, forms and clicks, JS-rendered pages, screenshots, web QA, extension popups, a human handoff for login, CAPTCHA or OTP, and a browser you own for scraping, bot-scored targets, network capture and QA traces. Use for any interactive browser task; not for a plain search or an unblocked static fetch.
  • Acodex-qaQA the omo Codex Light edition (lazycodex / packages/omo-codex) itself, in strict isolation so ONLY our plugin is exercised, never the user's real ~/.codex. The first-party method drives the real `codex app-server` against an isolated CODEX_HOME plus a LOCAL mock model (no real API call), and proves a plugin hook fired by asserting hook/started + hook/completed notifications. Also: isolated install verification, per-component hook probes, a tmux TUI smoke, and runtime log observation (RUST_LOG / logs SQLite / /debug-config). Ships tested helper scripts each with a --self-test. Use whenever someone changes anything under packages/omo-codex or wants to QA, smoke-test, verify, or debug the Codex plugin, its hooks/components, the installer/config.toml, the app-server flow, or the Codex TUI. Triggers: codex qa, qa codex, codex-qa, test codex plugin, verify codex hook, codex app-server, lazycodex qa, isolated CODEX_HOME, prove codex hook fired, codex tui test.
  • Acoding-agent-sessionsFinds, reads, and reconstructs coding-agent sessions across Codex, Claude, OpenCode, OMO/Senpi, and other local agent logs. Use when asked to find or search past sessions, transcripts, or subagent runs, or to recover what an earlier session did.
  • Acomment-checkerUse when Codex needs to understand or respond to automatic comment-checker feedback emitted after an edit-like PostToolUse hook.
  • Adag-libraryStores a DAG definition once and re-runs it by name, instead of pasting the definition into every run. Use when the user wants to save a DAG, run a saved one, or schedule the same multi-agent graph repeatedly.
  • Ddata-scientistProcesses and analyzes data with resident-kernel engines (DuckDB, Polars) and one-shot tools. Use for CSV/parquet/JSON analysis, group-by/join/aggregation, time series, distributions, cleaning, or plotting a dataset.
  • Adev-browserBrowser automation with persistent page state. Use when users ask to navigate websites, fill forms, take screenshots, extract web data, test web apps, or automate browser workflows. Trigger phrases include "go to [url]", "click on", "fill out the form", "take a screenshot", "scrape", "automate", "test the website", "log into", or any browser interaction request.
  • CfrontendBuilds, styles, and polishes web UI and UX. Use for any frontend, page, component, styling, layout, animation, or visual-quality task, or when asked to make an interface look or feel a certain way.
  • AfrontendBuilds, styles, and polishes web UI and UX. Use for any frontend, page, component, styling, layout, animation, or visual-quality task, or when asked to make an interface look or feel a certain way.
  • Aget-unpublished-changesCompare HEAD with the latest published npm versions and list all unpublished changes by release layer. Triggers: unpublished changes, changelog, what changed, whats new.
  • Agit-masterHandles git work: atomic commits, rebase, squash, blame, bisect, reflog, and history questions. Use whenever a task needs a commit or a git-history investigation; skip for ordinary code edits.

All agent skills → · MCP servers