How do I install the Debug Loop skill?

Run npx skillmds@latest add hoangsonww/debug-loop-2 in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

What does the Debug Loop skill do?

Systematic debugging playbook for the Forge agentic loop (src/core/loop.ts and src/agents/executor.ts). Use when a task is stuck, looping, or producing wrong tool calls. It is listed under Productivity on SkillMD.

Is Debug Loop safe to use?

This skill has not completed SkillMD's automated safety review yet. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Debug Loop?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Debug Loop free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Debug Loop?

hoangsonww (@hoangsonww) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Debug Loop by hoangsonww — Agent Skill

Name: Debug Loop
Author: hoangsonww

File contents

/debug-loop — debug the agentic loop

The loop is the single most expensive place to be wrong. Before you change anything, instrument.

1. Reproduce deterministically

Run with FORGE_LOG_LEVEL=debug ./bin/forge.js <command>.
Capture a session id. Events are in ~/.config/forge/events/<session>.ndjson.
If the bug only repro's against a real provider, pin to a single model and disable the router's fallback: FORGE_MODEL=... FORGE_ROUTER_FALLBACK=0.

2. Read the event stream, not the terminal

Each turn emits: turn.start, model.call, tool.call, tool.result, validation.result, turn.end. If any stage is missing or out of order, that is your bug. Grep the ndjson before staring at code.

3. Check the usual suspects, in order

Mode caps (src/core/mode-policy.ts) — is the agent hitting the turn/token cap and being cut off? The event will say so.
Validation gate (src/core/validation.ts) — is the gate rejecting a valid step? Look at validation.result.reason.
Tool registry — is the tool the model asked for actually registered? tool.call with class: not_found means no.
Permissions — is the call being silently denied? tool.result.denied=true in the stream.
State machine (src/persistence/tasks.ts) — is an illegal transition being attempted?

4. Add a failing test before the fix

Unit-test the smallest failing path with callModel mocked.
If the bug is in the loop itself, test/unit/executor-loop.test.ts is the template.

5. Fix, then verify

Run /verify. If the test you added doesn't turn green, you fixed the wrong thing.

Frequently asked questions

Debug Loop