mcpbeat Sign in

Debug CLI Skill for Claude

by Microck

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.

2k tokens
context cost
the whole folder, loaded on every use
2
files
instructions only
0
copies elsewhere
how many repositories repackaged it
320
stars on the repo
on the repository, not the skill itself

Install

one command, takes just this skill from the repository 
npx skills add https://github.com/Microck/ordinary-claude-skills --skill debug-cli

What comes with it

667 bytes besides the instruction
metadata.json

The instruction itself

18 sections, as written by the author

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 --help to see current commands and options
  • Use -p for testing: Test forge by giving it tasks with the -p flag
  • 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 --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

Other skills for the same job

different authors, same section of the catalogue
MCP Builder
by anthropics
vendor ×13

Guide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).

30k tokens scripts
Changelog Generator
by frostant
×9

Automatically creates user-facing changelogs from git commits by analyzing commit history, categorizing changes, and transforming technical commits into clear, customer-friendly release notes. Turns hours of manual changelog writing into minutes of automated generation.

774 tokens
Finishing A Development Branch
by ZhanlinCui
×7

Use when implementation is complete, all tests pass, and you need to decide how to integrate the work - guides completion of development work by presenting structured options for merge, PR, or cleanup

1k tokens
MCP Builder
by JayZeeDesign
×7

Guide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).

37k tokens scripts
Vercel React Native Skills
by vercel-labs
vendor ×6

React Native and Expo best practices for building performant mobile apps. Use when building React Native components, optimizing list performance, implementing animations, or working with native modules. Triggers on tasks involving React Native, Expo, mobile performance, or native platform APIs.

39k tokens
Vercel React Best Practices
by ratacat
×5

React and Next.js performance optimization guidelines from Vercel Engineering. This skill should be used when writing, reviewing, or refactoring React/Next.js code to ensure optimal performance patterns. Triggers on tasks involving React components, Next.js pages, data fetching, bundle optimization, or performance improvements.

34k tokens
Next Best Practices
by vercel-labs
vendor ×4

Next.js best practices - file conventions, RSC boundaries, data patterns, async APIs, metadata, error handling, route handlers, image/font optimization, bundling

20k tokens
Using Git Worktrees
by ZhanlinCui
×4

Use when starting feature work that needs isolation from current workspace or before executing implementation plans - creates isolated git worktrees with smart directory selection and safety verification

1k tokens

How to use it

Copy the folder

Take microck/debug-cli from the repository into ~/.claude/skills for personal use, or into .claude/skills inside a project.

Check the name does not clash

The agent identifies a skill by the name field in its header. Two skills with the same name cannot sit side by side — one of them will be ignored.