debug-cli
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.
- Installs
- 69
- Last 24h
- —
- Trending rank
- —
- Security
- Not audited
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/tailcallhq/forgecode --skill debug-cli- 01
Install
Run the command in your project. The CLI asks which agents to install for.
- 02
Describe the task
Ask your agent for something this skill covers. It loads debug-cli automatically when relevant.
- 03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.
SKILL.md
The instructions your agent reads when the skill is triggered.
CLI Debug Skill
This skill provides a systematic workflow for debugging and verifying changes to the forge CLI application.
Core Principles
- Always get latest docs first: Run
--helpto see current commands and options - Use
-pfor testing: Test forge by giving it tasks with the-pflag - Never commit: This is for debugging only - don't commit changes
- 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:
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:
# 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:
# 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:
# 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:
# 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
# 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
# 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
# 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
# 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
After Code Changes
- Build:
cargo build - Docs:
./target/debug/forge --help(verify documentation) - Test:
./target/debug/forge -p "relevant task" - Verify: Check output matches expectations
Debugging a Bug Report
- Clone:
./target/debug/forge conversation clone <source-id> - Build:
cargo build(with potential fixes) - Test:
./target/debug/forge --conversation-id <cloned-id> -p "reproduce" - Iterate: Repeat until verified
- Never commit during debugging - only after full verification
Quick Reference
# 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
--helpfirst: Get latest docs before testing - Use
-pfor testing: Don't test interactively, use prompts - Clone conversations: Never modify original bug conversations
- Never commit: This is for debugging only
- Dump creates files:
dumpautomatically creates timestamped files (no>needed) - HTML exports: Use
--htmlflag for human-readable conversation views - Use relative paths: Binary is at
./target/debug/forgefrom project root - Check exit codes: Use
echo $?to verify exit codes - Watch for warnings: Build warnings often indicate issues
FAQ
What does the debug-cli skill do?
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.
How do I install debug-cli?
Run npx skills add https://github.com/tailcallhq/forgecode --skill debug-cli in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/debug-cli/ (personal) or .claude/skills/debug-cli/ (project).
Which AI agents can use debug-cli?
Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.
Is debug-cli safe to install?
No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.
Who maintains debug-cli?
It is published by tailcallhq in tailcallhq/forgecode. It has 69 recorded installs.
More from tailcallhq/forgecode
resolve-conflicts
tailcallhq/forgecode
Use this skill immediately when the user mentions merge conflicts that need to be resolved. Do not attempt to resolve conflicts directly - invoke this skill first. This skill specializes in providing a structured framework for merging imports, tests, lock files (regeneration), configuration files, and handling deleted-but-modified files with backup and analysis.
create-plan
tailcallhq/forgecode
Open the skill to read its SKILL.md instructions.
execute-plan
tailcallhq/forgecode
Open the skill to read its SKILL.md instructions.
Popular code quality & workflow skills
grill-me
mattpocock/skills
A relentless interview to sharpen a plan or design.
improve-codebase-architecture
mattpocock/skills
Scan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick.
handoff
mattpocock/skills
Compact the current conversation into a handoff document for another agent to pick up.
domain-modeling
mattpocock/skills
Build and sharpen a project's domain model. Use when discussing codebase terminology, writing or editing a GLOSSARY.md, or recording or editing an ADR.
codebase-design
mattpocock/skills
Shared vocabulary for designing deep modules. Use when the user wants to design or improve a module's interface, find deepening opportunities, decide where a seam goes, make code more testable or AI-navigable, or when another skill needs the deep-module vocabulary.
diagnosing-bugs
mattpocock/skills
Diagnosis loop for hard bugs and performance regressions. Use when the user says "diagnose"/"debug this", or reports something broken/throwing/failing/slow.