prompt-coach

Prompt Coach - Claude Code Usage Analytics Skill

A Claude Code skill that analyzes your session logs to provide insights about your coding patterns, token usage, productivity, and prompt quality.

What This Does

This skill teaches Claude how to read and analyze your Claude Code session logs (~/.claude/projects/*.jsonl) to help you:

• ✍️ Improve prompt quality - Learn if your prompts are clear and effective
• 🎯 See real examples - Analyze actual vague prompts from your logs with before/after improvements
• 💰 Calculate time savings - Understand the cost of unclear prompts (time + iterations)
• 📋 Get actionable templates - Receive specific prompt templates for common tasks
• 🛠️ Optimize tool usage - Discover underutilized powerful tools
• ⚡ Boost efficiency - Understand how many iterations you need per task
• 🕐 Find peak hours - Know when you're most productive
• 🔥 Identify code hotspots - See which files you edit most
• 🔄 Reduce context switching - Measure project switching overhead
• 🐛 Learn from errors - Understand common problems and recovery patterns

Installation

Quick Install (Recommended)

Run the install script:

cd ~/code/claude-code-prompt-coach-skill
./install.sh

The script will:

• ✅ Create ~/.claude/skills/ if needed
• ✅ Check for existing installations
• ✅ Copy the skill to the correct location
• ✅ Verify installation
• ✅ Show next steps

Restart Claude Code and you're done!

Manual Install

Copy the skill directory to your Claude skills folder:

cp -r ~/code/claude-code-prompt-coach-skill ~/.claude/skills/prompt-coach

For Development (Symlink)

Create a symlink to the skill directory:

ln -s ~/code/claude-code-prompt-coach-skill ~/.claude/skills/prompt-coach

Now you can edit Skill.md and changes take effect on next Claude Code restart.

Usage

IMPORTANT: This skill analyzes logs from THIS machine only. It can only access Claude Code session logs stored locally in ~/.claude/projects/.

Option 1: Analyze All Projects

Just ask Claude natural questions about your usage across all projects:

"How much have I spent on tokens this month?"
"Analyze my prompt quality from last week"
"Which tools do I use most?"
"Show me my productivity patterns"
"What files do I edit most often?"
"When am I most efficient?"

Claude will automatically read all your session logs and provide detailed analysis.

Option 2: List Projects First, Then Pick One

If you want to see what projects have logs and choose one:

"List all projects with Claude Code logs"
"Show me which projects I've worked on"
"What projects do I have session logs for?"

Claude will show you all available projects with details (sessions count, date range, size), and you can pick which one to analyze.

Option 3: Analyze a Specific Project

If you know the project path, analyze just that project:

"Analyze my prompt quality for the project under ~/code/youtube/transcript/mcp"

"Analyze my prompt quality for /Users/username/code/my-app and save it as report.md"

"Show me token usage for the project in ~/code/experiments"

"What tools do I use most in the ~/code/my-app project?"

This analyzes only the logs for that specific project, giving you focused insights.

Example Output

Token Usage Analysis

📊 Token Usage Analysis (Last 30 Days)

Input tokens:        450,000 ($1.35)
Output tokens:       125,000 ($1.88)
Cache writes:        200,000 ($0.75)
Cache reads:       1,500,000 ($0.45)
                    ─────────────────
Total cost:                   $4.43
Cache savings:                $4.05

Cache efficiency: 75% hit rate

💡 Tip: Your cache hit rate is excellent! You're saving ~$4/month
by keeping focused sessions.

Prompt Quality Analysis

📝 Prompt Quality Analysis (Last 14 Days)

Total prompts: 145
Needed clarification: 51 (35%)
Average prompt score: 5.2/10 (Good, room for improvement)

🚩 Most Common Missing Elements:
1. File paths: Missing in 61 prompts (42%)
2. Error details: Missing in 34 prompts (23%)
3. Success criteria: Missing in 43 prompts (30%)
4. Specific approach: Missing in 28 prompts (19%)

🔴 Real Examples from Your Logs:

**Example 1: Missing File Context**
❌ Your prompt: "fix the bug"
🤔 Claude asked: "Which file has the bug? What's the error message or symptom?"
✅ Better prompt: "fix the authentication bug in src/auth/login.ts where JWT validation fails with 401 error"
📉 Cost: +2 minutes, +1 iteration

**Example 2: Vague Action Words**
❌ Your prompt: "optimize the component"
🤔 Claude asked: "Which component? What performance issue? What's the target?"
✅ Better prompt: "optimize UserList component in src/components/UserList.tsx by adding React.memo to reduce unnecessary re-renders when parent updates"
📉 Cost: +3 minutes, +1 iteration

**Example 3: Missing Approach**
❌ Your prompt: "add caching"
🤔 Claude asked: "Where should caching be added? What caching strategy? (Redis, memory, file-based?)"
✅ Better prompt: "add Redis caching to the API responses in src/api/client.ts with 5-minute TTL, similar to how we cache user data"
📉 Cost: +4 minutes, +2 iterations

📉 Impact Analysis:
- 51 prompts needed clarification
- Average time lost per clarification: 2.8 minutes
- Total time lost to vague prompts: ~2.4 hours
- **Potential time savings: ~1.2 hours by improving top 25 vague prompts**

🎯 Your Top 3 Improvements (Maximum Impact):

**1. Always Include File Paths (42% of clarifications)**
   Template: "[action] in [file path] [details]"
   💰 Impact: Would eliminate ~21 clarifications (~1 hour saved)

**2. Provide Error Details When Debugging (23% of clarifications)**
   Template: "fix [error message] in [file] - expected [X], getting [Y]"
   💰 Impact: Would eliminate ~12 clarifications (~25 min saved)

**3. Define Success Criteria for Vague Actions (30% of clarifications)**
   Instead of: "optimize", "improve", "make better"
   Use: "[action] to achieve [specific measurable outcome]"
   💰 Impact: Would eliminate ~15 clarifications (~40 min saved)

💡 Quick Win: Apply these templates to your next 10 prompts and watch your clarification rate drop!

💪 You're doing well! Your prompts are 65% effective. Focus on these 3 improvements and you'll hit 85%+ effectiveness, saving ~1-2 hours per week.

Tool Usage Patterns

🛠️ Tool Usage Patterns (Last 30 Days)

Most used tools:
1. Read         ████████████████████ 450 uses
2. Edit         ████████████         220 uses
3. Bash         ███████              150 uses
4. Grep         ██                    34 uses

💡 Insights:

✅ Good: You use Read heavily - shows careful code review
⚠️  Opportunity: Low Grep usage (34 uses vs 450 Reads)
   → Try Grep for searching across multiple files
   → It's much faster than reading each file

Available Analysis Types

1. Token Usage & Cost Tracking - Detailed breakdown with current pricing
2. Enhanced Prompt Quality Analysis ⭐ NEW! - Advanced analysis that:
   • Detects vague prompt patterns (missing file paths, error details, success criteria)
   • Shows real examples from YOUR logs with what Claude had to ask
   • Provides before/after improvements for actual prompts you wrote
   • Calculates time/iteration cost of unclear prompts
   • Gives actionable templates ranked by impact
   • Identifies most common missing elements in your prompts
3. Tool Usage Patterns - Which tools you use most/least
4. Session Efficiency - Average iterations per task
5. Productivity Time Patterns - Best hours and days to code
6. File Modification Heatmap - Most frequently edited files
7. Error & Recovery Analysis - Common errors and how long they take to fix
8. Project Switching Analysis - Context switching costs

How It Works

The skill provides Claude with:

• Official Claude prompt engineering best practices from Anthropic's documentation
• Knowledge of where logs are stored (~/.claude/projects/)
• Understanding of the JSONL log format
• A scoring system for prompt quality (Clarity, Specificity, Actionability, Scope)
• Patterns to look for (tool usage, tokens, timestamps, etc.)
• Instructions on how to calculate metrics
• Templates for presenting insights

Claude then uses its built-in tools (Read, Bash, Grep) to:

1. Find and read your log files
2. Parse the JSON data
3. Score your prompts against official best practices
4. Calculate metrics
5. Generate personalized, actionable insights

No external dependencies, no installations, no data leaving your machine.

Prompt Engineering Knowledge

The skill is trained on official Claude prompt engineering guidelines, including:

The Golden Rule

"Show your prompt to a colleague with minimal context. If they're confused, Claude will likely be too."

Prompt Engineering Hierarchy (What Works Best)

1. ⭐ Be Clear and Direct - Most effective
2. Use Examples (Multishot) - Show desired output
3. Let Claude Think - Chain of thought reasoning
4. Use XML Tags - Structure for clarity
5. Give Claude a Role - Set context
6. Prefill Responses - Guide output format
7. Chain Complex Prompts - Break into steps

When analyzing your prompts, the skill evaluates them against these techniques and provides specific recommendations for improvement.

Skill Design: Prompt Engineering in Action

The Skill.md file itself is a masterclass in prompt engineering, practicing what it preaches. Here's how it's constructed:

Core Techniques Applied

1. Clear Role Definition (System Prompts)

• Establishes Claude as "an AI-native engineering expert and prompt engineering specialist"
• Defines domain expertise upfront (lines 9-15)
• Sets clear expectations for behavior and knowledge

2. Hierarchical Structure & Organization

• Markdown headers create clear information hierarchy
• Numbered step-by-step instructions for each analysis task
• Visual indicators (emojis, ASC

---

Content truncated.