gh-hirefrank-hirefrank-marketplace-plugins-claude-skills-analyzer/commands/skills-troubleshoot.md

description

description
Troubleshoot common issues with skills analysis setup and execution

Skills Analysis Troubleshooting

I'll help you diagnose and fix common issues with the Claude Skills Analyzer.

🔍 Quick Diagnostics

Let me check your current setup and identify any issues:

Directory Structure Check

First, let me verify your project has the required directories:

Expected structure:
├── data-exports/
│   ├── claude/           # Claude export files
│   └── chatgpt/          # ChatGPT export files  
├── reports/              # Analysis outputs
└── generated-skills/     # Generated skill packages

Data Files Check

Looking for these required files:

Claude exports (data-exports/claude/):

• conversations.json - Required
• projects.json - Optional but helpful
• users.json - Optional

ChatGPT exports (data-exports/chatgpt/):

• conversations.json - Required
• user.json - Optional
• shared_conversations.json - Optional

🚨 Common Issues & Solutions

Issue: "No conversation files detected"

Causes:

• Files in wrong directories
• Incorrect file names
• Empty or corrupted JSON files

Solutions:

1. Check file locations: Ensure JSON files are in correct data-exports/ subdirectories
2. Verify file names: Must match exactly (case-sensitive)
3. Validate JSON: Open files in text editor to check they're valid JSON
4. Check file sizes: Empty files (0 bytes) won't work

Issue: "Analysis produces no patterns"

Causes:

• Too few conversations (need 20+ minimum)
• Conversations too short or simple
• No recurring patterns in usage

Solutions:

1. Accumulate more data: Export again after more AI usage
2. Lower thresholds: Adjust frequency requirements in analysis
3. Check conversation quality: Need substantial back-and-forth interactions
4. Try different timeframes: Use older exports if available

Issue: "Plugin command not found"

Causes:

• Plugin not properly installed
• Claude Code needs restart
• Marketplace not added correctly

Solutions:

1. Verify installation:

   /plugin list
   

2. Restart Claude Code: Close and reopen
3. Reinstall plugin:

   /plugin uninstall claude-skills-analyzer@hirefrank
   /plugin install claude-skills-analyzer@hirefrank
   

Issue: "JSON parsing errors"

Causes:

• Incomplete export downloads
• File corruption during transfer
• Unsupported export format versions

Solutions:

1. Re-download exports: Get fresh copies from AI platforms
2. Check file integrity: Verify files open properly in text editor
3. Try smaller batches: Export smaller date ranges if available

Issue: "Skills generation fails"

Causes:

• Insufficient write permissions
• Conflicting files in output directories
• Pattern analysis errors

Solutions:

1. Check permissions: Ensure you can write to project directory
2. Clear output directories: Remove old reports/ and generated-skills/ content
3. Try incremental analysis: Start with Option A (report only)

🔧 Manual Diagnostics

Check Your Export Files

# Navigate to your data directory
cd data-exports

# Check file sizes (should be >1KB)
ls -la claude/
ls -la chatgpt/

# Preview file contents (first few lines)
head -5 claude/conversations.json
head -5 chatgpt/conversations.json

Validate JSON Structure

# Check if files are valid JSON (on systems with jq)
jq . claude/conversations.json > /dev/null && echo "Claude JSON valid"
jq . chatgpt/conversations.json > /dev/null && echo "ChatGPT JSON valid"

📊 Data Requirements

Minimum Requirements

• 20+ conversations total across platforms
• Average 3+ exchanges per conversation
• Variety of topics/tasks represented
• JSON files >1KB in size

Optimal Requirements

• 50+ conversations for meaningful patterns
• Mix of short and long conversations
• Regular usage patterns over time
• Both platforms represented (if you use both)

🎯 Quick Fixes

Create Missing Directories

mkdir -p data-exports/claude data-exports/chatgpt reports generated-skills

Test Plugin Installation

# Check if plugin is available
/help | grep analyze-skills

# List installed plugins
/plugin list | grep claude-skills-analyzer

Reset and Retry

# Clear any partial outputs
rm -rf reports/* generated-skills/*

# Re-run analysis with fresh start
/analyze-skills

📞 Getting Additional Help

For Setup Issues

• Review /skills-setup for complete setup guide
• Check plugin README at plugins/claude-skills-analyzer/README.md
• Verify you have the latest plugin version

For Analysis Issues

• Try Option A (Analysis Report Only) first
• Review conversation export quality
• Consider smaller dataset for initial testing

For Technical Issues

• Check GitHub Issues
• Report bugs with error messages and setup details
• Join discussions for community support

💡 Pro Troubleshooting Tips

1. Start small: Test with a small, known-good dataset first
2. Check permissions: Ensure you can read/write in the project directory
3. Update regularly: Keep the plugin updated to latest version
4. Document patterns: Note what types of conversations work best
5. Incremental approach: Use existing analysis logs for efficiency

🔄 Still Having Issues?

If problems persist:

1. Gather diagnostics:

   • Plugin version (/plugin list)
   • Error messages (exact text)
   • File sizes and locations
   • Claude Code version

2. Try minimal test:

   • Create new directory
   • Add just 1-2 export files
   • Run analysis with Option A

3. Get support:

   • Open GitHub issue with full details
   • Include anonymized error logs
   • Describe expected vs actual behavior

Let me know what specific issue you're experiencing and I'll provide targeted help!