Agent skill

Forge CLI Debug Workflow

by tailcallhq in tailcallhq/forgecode

Gives a systematic process for debugging the forge CLI: build in debug mode, check the latest help output, test with the non-interactive -p flag, and clone conversations before reproducing bugs.

Apache-2.0Auto-check passedDevelopment

Install Forge CLI Debug Workflow

skills CLI
$ npx skills add tailcallhq/forgecode --skill debug-cli -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install tailcallhq/forgecode debug-cli --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/tailcallhq/forgecode.git skills-src && mkdir -p .claude/skills && cp -r skills-src/.forge/skills/debug-cli .claude/skills/debug-cli && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
debug-cli
GitHub stars
7.6k
Used in
1 other repo
Token cost
~1.6k tokens
SKILL.md length
361 words
Files
3 (incl. scripts)
Skills in repo
14
Repo updated
First seen
Licence
Apache-2.0

At a glance

Gives a systematic process for debugging the forge CLI: build in debug mode, check the latest help output, test with the non-interactive -p flag, and clone conversations before reproducing bugs.

  • Works in 5 steps: Build the Application → Get Latest Documentation → Test with -p Flag → …
  • Debugging a reported issue in the forge CLI
  • SKILL.md covers Core Principles, Workflow, Common Testing Patterns and Integration with Development…, plus 2 more sections
  • Runs Shell scripts from its folder; calls cargo and jq

What it does

The skill treats checking --help as the first step of any debugging session, so command and option changes are seen before anything else runs. It always builds with plain cargo build rather than a release build, since release builds are slower and unnecessary for verification, and it never commits changes, because this workflow is for debugging only.

For a conversation-related bug, it uses forge conversation dump to export the conversation to a timestamped JSON file, and critically clones the source conversation with forge conversation clone before attempting to reproduce the bug, so the original evidence stays intact for multiple reproduction attempts or A/B testing of a fix. A bundled test_cli.sh script and its README support the common testing patterns described: testing new features, reproducing reported bugs, testing edge cases such as missing arguments, and debugging prompt optimization.

When your agent uses it

  • Debugging a reported issue in the forge CLI
  • Adding or testing a new forge CLI command or option
  • Reproducing a bug from a user's conversation dump without losing the original

Example prompts

  • “Reproduce the bug in conversation abc123 by cloning it first.”
  • “Build forge and verify the new --format flag shows up in --help.”
  • “Test what happens when the command subcommand is run with no arguments.”

Requirements

  • Rust and cargo
  • The forge CLI source checkout

Workflow steps

5 steps, taken from the step headings in SKILL.md.

  1. Build the Application
  2. Get Latest Documentation
  3. Test with -p Flag
  4. Debug with Conversation Dumps
  5. Clone Before Reproducing Bugs

What it can do on your machine

Read from SKILL.md and the folder at commit 92a5699. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    Ships 2 files in scripts/ (Shell), which the agent can run.

    Shell commands in SKILL.md call:

    • cargo
    • jq

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Forge CLI Debug Workflow loads about 1.6k tokens when it runs. Until then it costs about 63 tokens; SKILL.md has 361 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~63
When it runs · the whole SKILL.md, loaded when a task matches
~1.6k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); the scripts in this folder are not scanned.

SKILL.md

The full file from tailcallhq/forgecode at commit 92a5699, republished under its Apache-2.0 licence (© tailcallhq). 361 words, ~1,636 tokens.

Download SKILL.mdSave it as .claude/skills/debug-cli/SKILL.md (or your agent's skills folder). This skill also uses 2 other files; get the full folder from GitHub.
name
debug-cli
description
Use when users need to debug, modify, or extend the code-forge application's CLI commands, argument parsing, or CLI behavior. This includes adding new commands, fixing CLI bugs, updating command options, or troubleshooting CLI-related issues.

CLI Debug Skill

This skill provides a systematic workflow for debugging and verifying changes to the forge CLI application.

Core Principles

  1. Always get latest docs first: Run --help to see current commands and options
  2. Use -p for testing: Test forge by giving it tasks with the -p flag
  3. Never commit: This is for debugging only - don't commit changes
  4. Clone conversations: When debugging conversation bugs, clone the source conversation before reproducing

Workflow

1. Build the Application

Always build in debug mode after making changes:

bash
cargo build

Never use cargo build --release for debugging - it's significantly slower and unnecessary for verification.

2. Get Latest Documentation

Always start by checking the latest help to understand current commands and options:

bash
# Main help - do this first
./target/debug/forge --help

# Command-specific help
./target/debug/forge [COMMAND] --help

# Subcommand help
./target/debug/forge [COMMAND] [SUBCOMMAND] --help
3. Test with -p Flag

Use the -p flag to give forge a task to complete without interactive mode:

bash
# Test with a simple prompt
./target/debug/forge -p "create a hello world rust program"

# Test with specific functionality
./target/debug/forge -p "read the README.md file and summarize it"

# Test with complex tasks
./target/debug/forge -p "analyze the code structure and suggest improvements"
4. Debug with Conversation Dumps

When debugging prompts or conversation issues, use conversation dump to export conversations. The command automatically creates a timestamped file:

bash
# Dump conversation as JSON (creates: YYYY-MM-DD_HH-MM-SS-dump.json)
./target/debug/forge conversation dump <conversation-id>

# Export as HTML for human-readable format (creates: YYYY-MM-DD_HH-MM-SS-dump.html)
./target/debug/forge conversation dump --html <conversation-id>

# Use dumped JSON to reproduce issues
./target/debug/forge --conversation 2025-11-23_12-28-52-dump.json
5. Clone Before Reproducing Bugs

Critical: When a user provides a conversation with a bug, always clone it first:

bash
# Clone the conversation
./target/debug/forge conversation clone <source-conversation-id>

# This creates a new conversation ID - use that for testing
./target/debug/forge --conversation-id <new-cloned-id>

# Keep cloning the source until the fix is verified
# Never modify the original conversation

Why clone?

  • Preserves original bug evidence
  • Allows multiple reproduction attempts
  • Enables A/B testing of fixes
  • Keeps source conversation clean

Common Testing Patterns

Test New Features
bash
# Build and test new command
cargo build
./target/debug/forge --help  # Verify new command appears
./target/debug/forge new-command --help  # Check command docs
./target/debug/forge -p "test the new feature"
Reproduce Reported Bugs
bash
# 1. Dump the conversation (creates timestamped JSON file)
./target/debug/forge conversation dump <bug-conversation-id>

# 2. Clone it for testing (preserves original)
./target/debug/forge conversation clone <bug-conversation-id>

# 3. Reproduce with the cloned conversation
./target/debug/forge --conversation-id <cloned-id> -p "reproduce the issue"

# 4. After fix, verify with new clone
./target/debug/forge conversation clone <bug-conversation-id>
./target/debug/forge --conversation-id <new-clone-id> -p "verify fix"
Test Edge Cases
bash
# Test with missing arguments
./target/debug/forge command

# Test with invalid input
./target/debug/forge -p "invalid task with special chars: <>|&"

# Test with boundary values
./target/debug/forge -p "create a file with a very long name..."
Debug Prompt Optimization
bash
# 1. Dump conversation to analyze prompts (creates timestamped JSON)
./target/debug/forge conversation dump <id>

# 2. Review the conversation structure
cat 2025-11-23_12-28-52-dump.json | jq '.messages[] | {role, content}'

# 3. Export as HTML for easier reading
./target/debug/forge conversation dump --html <id>

# 4. Test modified prompts
./target/debug/forge -p "your optimized prompt here"

Integration with Development Workflow

Show full SKILL.md (143 more words)Show less
After Code Changes
  1. Build: cargo build
  2. Docs: ./target/debug/forge --help (verify documentation)
  3. Test: ./target/debug/forge -p "relevant task"
  4. Verify: Check output matches expectations
Debugging a Bug Report
  1. Clone: ./target/debug/forge conversation clone <source-id>
  2. Build: cargo build (with potential fixes)
  3. Test: ./target/debug/forge --conversation-id <cloned-id> -p "reproduce"
  4. Iterate: Repeat until verified
  5. Never commit during debugging - only after full verification

Quick Reference

bash
# Standard debug workflow
cargo build
./target/debug/forge --help  # Always check docs first
./target/debug/forge -p "your test task"

# Dump conversation (creates timestamped file)
./target/debug/forge conversation dump <id>
# Output: 2025-11-23_12-28-52-dump.json

# Export as HTML for review
./target/debug/forge conversation dump --html <id>
# Output: 2025-11-23_12-28-52-dump.html

# Use dumped conversation
./target/debug/forge --conversation 2025-11-23_12-28-52-dump.json

# Clone and test bug
./target/debug/forge conversation clone <source-id>
./target/debug/forge --conversation-id <cloned-id> -p "reproduce bug"

# Debug prompts with jq (use actual filename)
cat 2025-11-23_12-28-52-dump.json | jq '.messages[] | {role, content}'

# Test with verbose output
./target/debug/forge --verbose -p "test task"

Tips

  • Always --help first: Get latest docs before testing
  • Use -p for testing: Don't test interactively, use prompts
  • Clone conversations: Never modify original bug conversations
  • Never commit: This is for debugging only
  • Dump creates files: dump automatically creates timestamped files (no > needed)
  • HTML exports: Use --html flag for human-readable conversation views
  • Use relative paths: Binary is at ./target/debug/forge from project root
  • Check exit codes: Use echo $? to verify exit codes
  • Watch for warnings: Build warnings often indicate issues

© tailcallhq, Apache-2.0. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 2 other files (scripts) in .forge/skills/debug-cli of tailcallhq/forgecode.

  • SKILL.md
  • scripts/README.md
  • scripts/test_cli.sh

Open the folder on GitHubat commit 92a5699

Used in 1 other repository

We found 3 copies of this SKILL.md (exact, near-identical or edited) in other folders, from 1 other GitHub owner. This page covers the copy in tailcallhq/forgecode, which our catalogue first saw on October 7, 2026.

Compare with similar skills

Forge CLI Debug Workflow next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Forge CLI Debug Workflow compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Forge CLI Debug Workflow this skilltailcallhq/forgecode7.6k1 repos~1.6kAutomated safety check: PassApache-2.0
Issue Fixmono/SkiaSharp5.6k—~5.1kAutomated safety check: PassMIT
React Router Bug Fix Workflowremix-run/react-router57k—~1.3kAutomated safety check: PassMIT
OpenROAD Bug FixerThe-OpenROAD-Project/OpenROAD3.2k—~784Automated safety check: PassBSD-3-Clause
Extension Puppeteer Debuggingmengxi-ream/read-frog10k—~2kAutomated safety check: NotesGPL-3.0
Adk Setupgoogle/adk-python22k—~993Automated safety check: NotesApache-2.0

Similar skills

  • Issue Fix

    mono/SkiaSharp

    Fix bugs in SkiaSharp C bindings. An agent skill from mono/SkiaSharp.

    5.6k GitHub stars~5.1k tokensUpdated today
    DevelopmentAuto-check passed
  • React Router Bug Fix Workflow

    remix-run/react-router

    Fixes a React Router bug reported in a GitHub issue end to end: fetching the issue, validating the reproduction, writing a failing test and implementing the fix on a new branch.

    57k GitHub stars~1.3k tokensUpdated today
    DevelopmentAuto-check passed
  • OpenROAD Bug Fixer

    The-OpenROAD-Project/OpenROAD

    Fixes an OpenROAD bug from a GitHub issue or error code: finds the root cause, implements the fix, adds a regression test and prepares a signed-off commit.

    3.2k GitHub stars~784 tokensUpdated today
    DevelopmentAuto-check passed
  • Extension Puppeteer Debugging

    mengxi-ream/read-frog

    Debug the built Read Frog extension in real Chrome. An agent skill from mengxi-ream/read-frog.

    10k GitHub stars~2k tokensUpdated today
    DevelopmentAuto-check: notes
  • Adk Setup

    google/adk-python

    Official

    Sets up a local ADK Python development environment in a git clone of the open-source adk-python repository: a uv virtual environment, all dependency extras, pre-commit hooks, and a first unit-test…

    22k GitHub stars~993 tokensUpdated today
    DevelopmentAuto-check: notes
  • LinkedIn MCP Issue Investigator

    stickerdaniel/linkedin-mcp-server

    Investigates a reported LinkedIn-MCP issue by matching the reporter's tool call to the exact source file and tests, without applying a fix.

    3.8k GitHub stars~2k tokensUpdated today
    DevelopmentAuto-check passed

More from tailcallhq/forgecode

All 14 skills in this repo
  • Git Merge Conflict Resolver

    tailcallhq/forgecode

    Resolves Git merge conflicts with a plan-first workflow that keeps both sides' intent, regenerates lock files and backs up deleted-but-modified files.

    7.6k GitHub starsUsed in 1 repo~4.5k tokens
    Auto-check passed
  • FIXME Resolver

    tailcallhq/forgecode

    Finds every FIXME comment in a codebase, groups related ones across files into one task, implements the work they describe and removes the comments once it is done.

    7.6k GitHub stars~1.1k tokensUpdated today
    Auto-check passed
  • Reasoning Serialization Tests

    tailcallhq/forgecode

    Checks that ReasoningConfig fields are serialized into the right provider-specific JSON for OpenRouter, Anthropic, GitHub Copilot and Codex requests.

    7.6k GitHub stars~1k tokensUpdated today
    Auto-check passed
  • Implementation Plan Creator

    tailcallhq/forgecode

    Writes a structured Markdown implementation plan with checkbox tasks, verification criteria and risks, then checks it with a validation script; no code changes.

    7.6k GitHub starsUsed in 1 repo~1.1k tokens
    Auto-check passed
  • Release Notes Writer

    tailcallhq/forgecode

    Pulls a GitHub release and every linked pull request, then writes polished, factual release notes from the combined set of changes.

    7.6k GitHub stars~1.4k tokensUpdated today
    Auto-check passed
  • Skill Creation Guide

    tailcallhq/forgecode

    Guidance for creating and updating agent skills: what skills provide, keeping context lean, choosing how specific to be, and how SKILL.md and bundled resources are laid out.

    7.6k GitHub starsUsed in 1 repo~4.6k tokens
    Auto-check passed

Questions about Forge CLI Debug Workflow

What does Forge CLI Debug Workflow do?

Gives a systematic process for debugging the forge CLI: build in debug mode, check the latest help output, test with the non-interactive -p flag, and clone conversations before reproducing bugs. The skill treats checking --help as the first step of any debugging session, so command and option changes are seen before anything else runs. It always builds with plain cargo build rather than a release build, since release builds are slower and unnecessary for verification, and it never commits changes, because this workflow is for debugging only.

When should I use Forge CLI Debug Workflow?

Forge CLI Debug Workflow fits situations like: debugging a reported issue in the forge CLI; adding or testing a new forge CLI command or option; reproducing a bug from a user's conversation dump without losing the original.

How do I install Forge CLI Debug Workflow in Claude Code?

Run `npx skills add tailcallhq/forgecode --skill debug-cli -a claude-code`. Or copy the skill folder (.forge/skills/debug-cli in tailcallhq/forgecode) into .claude/skills/debug-cli in your project. Claude Code loads it when a task matches its description.

How do I install Forge CLI Debug Workflow in Codex?

Run `npx skills add tailcallhq/forgecode --skill debug-cli -a codex`. Or copy the skill folder (.forge/skills/debug-cli in tailcallhq/forgecode) into .agents/skills/debug-cli in your project. Codex loads it when a task matches its description.

Can I use Forge CLI Debug Workflow in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add tailcallhq/forgecode --skill debug-cli -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/debug-cli, .gemini/skills/debug-cli, .github/skills/debug-cli and .opencode/skills/debug-cli in your project.

What does Forge CLI Debug Workflow need to run?

Going by SKILL.md and its folder, Forge CLI Debug Workflow needs a shell for the scripts in its folder and the command-line tools its instructions call (cargo and jq). Our summary lists: Rust and cargo; The forge CLI source checkout.

Does Forge CLI Debug Workflow access the network?

SKILL.md contains no URLs. Any network use would come from the scripts or tools the agent runs. This is read from the text; nothing was executed.

Is Forge CLI Debug Workflow safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. The check reads SKILL.md only: the scripts in the folder are not scanned, so read them before running anything.

What licence does Forge CLI Debug Workflow use?

Forge CLI Debug Workflow is published under the Apache-2.0 licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Forge CLI Debug Workflow use?

About 1.6k tokens (SKILL.md is roughly 6.5k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to Forge CLI Debug Workflow?

Skills that share tags, products or a category with Forge CLI Debug Workflow: Issue Fix (mono/SkiaSharp, 5.6k stars), React Router Bug Fix Workflow (remix-run/react-router, 57k stars), OpenROAD Bug Fixer (The-OpenROAD-Project/OpenROAD, 3.2k stars) and Extension Puppeteer Debugging (mengxi-ream/read-frog, 10k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Forge CLI Debug Workflow?

tailcallhq (a GitHub organization) maintains it in tailcallhq/forgecode, which has 7,642 GitHub stars. The repository holds 14 skills in this directory. The repository was last updated on October 7, 2026.

Source: tailcallhq/forgecode on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.