How to use the CLI Debug Workflow agent skill (debug-cli)

What the debug-cli skill makes the agent do

An agent skill is a folder with a SKILL.md file that the agent reads when a request matches the skill's description. The debug-cli skill matches requests about debugging, modifying or extending the forge CLI's commands, argument parsing or CLI behavior.

Once active, the skill tells the agent to follow a set of core principles: check the latest --help output before testing, test by giving forge tasks with the -p flag, never commit changes during debugging, and clone a source conversation before reproducing a conversation bug.

• Build in debug mode with cargo build (the skill says not to use --release for debugging).
• Read ./target/debug/forge --help and the help for specific commands and subcommands.
• Run test tasks with ./target/debug/forge -p "...".
• Dump conversations to JSON or HTML, or clone them, so the original is never modified.
• Run scripts/test_cli.sh as a smoke test.

Install the debug-cli skill

Download the skill ZIP from this page and unzip it. To make the skill available to Claude Code for your user account, place the debug-cli folder in ~/.claude/skills/. To make it available only inside one project, place it in that project's .claude/skills/ folder.

In the Claude apps, you can instead upload the skill under Settings → Capabilities → Skills.

• Personal install: ~/.claude/skills/debug-cli/
• Project install: <your-project>/.claude/skills/debug-cli/
• Claude apps: Settings → Capabilities → Skills, then upload the skill.

Trigger the skill with natural requests

You do not need a special command to start the skill. Describe the CLI work in plain language and the agent will load the skill when your request matches its description. The description covers adding new commands, fixing CLI bugs, updating command options and troubleshooting CLI-related issues.

Mention the forge repository and the bug or change so the agent knows which project and conversation to work with. Include a conversation ID if one exists.

• "Add a --dry-run option to the forge export command and check its help output."
• "Reproduce the bug in conversation <id> without changing the original."
• "Run the CLI smoke test after my argument parsing change."
• "Why does forge show the wrong help text for the new subcommand?"

Example workflows

For a reported bug in a saved conversation, the skill's workflow is to clone the conversation first, build, then reproduce against the clone. Cloning gives you a new conversation ID, so the original stays intact and you can repeat the test or verify a fix on a fresh clone.

To inspect prompts, the skill dumps a conversation to JSON and can pipe it through jq. The source's example filters messages to show role and content. jq is optional and only used in that example.

• Clone: ./target/debug/forge conversation clone <source-conversation-id>
• Reproduce: ./target/debug/forge --conversation-id <new-cloned-id> -p "reproduce the issue"
• Dump JSON: ./target/debug/forge conversation dump <id> (creates a timestamped .json file)
• Dump HTML: ./target/debug/forge conversation dump --html <id> (creates a timestamped .html file)

What you need before running it

The skill assumes a local checkout of the forge repository with a Rust toolchain that includes cargo, and a built ./target/debug/forge binary. Run commands from the project root because the skill uses relative paths. Bash is needed for scripts/test_cli.sh.

forge also needs its own working configuration and any model or API credentials to run -p tasks. The skill files do not specify what those are, so check the forge project's own setup.

• Rust toolchain with cargo
• A local forge repository checkout with a built ./target/debug/forge
• Bash (for scripts/test_cli.sh)
• jq (optional, used in one prompt-debugging example)
• Working forge configuration and any credentials forge needs for -p tasks

Safety notes: scripts and network access

This skill runs scripts and uses the network. scripts/test_cli.sh builds the CLI with cargo build and then runs the forge binary with several help and conversation-list commands. Read the script before running it on a machine or checkout you do not know well. The skill files do not review side effects beyond what the script shows.

The skill also says never to commit changes. Keep that rule in mind when the agent edits code, and review diffs yourself before any commit.

• Read scripts/test_cli.sh before running it.
• Run it in a checkout you control, not on an unfamiliar machine.
• Running -p tasks may call models or APIs, depending on your forge configuration.

Tips for getting good results

The skill works best when the agent can follow its order: build, check help, test, then clone for bug work. Ask for the build and help check explicitly after each change, because the skill treats them as the first steps. When a test looks wrong, ask the agent to check exit codes with echo $? and to look at build warnings, which the skill notes often point to real issues.

• Say which conversation ID or command you are working on.
• Ask for --verbose output when you need more detail from a -p run.
• Dumped files land in the current directory with timestamped names, so you do not need shell redirection.