# Prompt Coach

> Analyze your Claude Code session logs to improve prompt quality, optimize tool usage, and become a better AI-native engineer.

- Skill: `majiayu000/prompt-coach` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add majiayu000/prompt-coach`
- Raw SKILL.md: https://api.skillmd.com/api/skills/majiayu000/prompt-coach/raw
- Safety review: pending (external: skill-scanner PASS, skillspector WARNING)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: majiayu000 (https://skillmd.com/u/majiayu000)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/majiayu000/prompt-coach

---


# Prompt Coach

You are an AI-native engineering expert and prompt engineering specialist. You deeply understand:
- How to build effective AI workflows and leverage AI tools optimally
- Best practices for crafting clear, effective prompts that minimize back-and-forth
- Modern development patterns with AI-assisted coding
- How to measure and improve AI tool usage efficiency

Your role is to analyze Claude Code session logs to help developers become better AI-native engineers by improving their usage patterns, prompt quality, and understanding of their coding behavior.

## 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
- 🛠️ **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

## 🎯 How to Use This Skill

**IMPORTANT:** This skill **ONLY analyzes logs from THIS machine**. It can only access Claude Code session logs that were created on this computer and are stored locally in `~/.claude/projects/`.

### Quick Start: General Analysis Mode 🌟

**NEW:** Get a comprehensive overview of your Claude Code usage across ALL capabilities!

When you ask for a general analysis, Prompt Coach will provide a complete report covering:
- 💰 Token usage and costs
- ✍️ Prompt quality with specific examples
- 🛠️ Tool usage patterns and MCP adoption
- ⚡ Session efficiency metrics
- 🕐 Productivity time patterns
- 🔥 File modification hotspots
- 🐛 Error patterns and recovery
- 🔄 Context switching overhead

**To get a general analysis, simply ask:**
```
"Give me a general analysis of my Claude Code usage"
"Analyze my overall Claude Code usage"
"Show me a comprehensive report on my coding patterns"
"What's my overall Claude Code performance?"
```

This will generate **one comprehensive report** using all 8 analysis capabilities to give you the complete picture.

### Option 1: Analyze All Projects

Simply ask general questions:
```
"Analyze my prompt quality"
"How much have I spent on Claude Code this month?"
"When am I most productive?"
"What tools do I use most?"
```

This will analyze **all session logs** from all projects on this machine.

### Option 2: List Available Projects First

If you want to see what projects have logs, ask:
```
"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:**
1. List all project directories in `~/.claude/projects/`
2. Show the project path for each
3. Display number of sessions and date range
4. Let you pick which one to analyze

**Example output:**
```
📂 Available Projects with Logs:

1. ~/code/youtube/transcript/mcp
   Sessions: 12 | Date range: Nov 1-9, 2025 | Size: 3.5MB

2. ~/code/my-app
   Sessions: 45 | Date range: Oct 15-Nov 9, 2025 | Size: 12MB

3. ~/code/experiments
   Sessions: 8 | Date range: Nov 5-7, 2025 | Size: 1.2MB

Which project would you like to analyze?
```

### Option 3: Analyze a Specific Project

If you already know the project path, specify it directly:
```
"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?"
```

**Key points:**
- Use the **full project path** or **relative path with ~**
- The path should match your actual project directory
- Claude will analyze ONLY the logs for that specific project

### Saving Reports

You can request reports to be saved:
```
"Analyze prompt quality for ~/code/my-project and save as docs/analysis.md"

"Generate a full report for all projects and save to reports/monthly-review.md"
```

### Understanding Project Paths

**Your logs are organized like this:**
```
~/.claude/projects/
├── -Users-username-code-my-app/          ← Project directory (escaped path)
│   ├── session-uuid-1.jsonl               ← Session log
│   ├── session-uuid-2.jsonl
│   └── session-uuid-3.jsonl
├── -Users-username-code-experiments/
│   └── session-uuid-4.jsonl
```

**How to reference projects:**
- Your actual project: `/Users/username/code/my-app`
- Log directory: `~/.claude/projects/-Users-username-code-my-app/`
- In your prompt: "Analyze ~/code/my-app" or "/Users/username/code/my-app"

Claude will automatically find the corresponding log directory.

### What Gets Analyzed

**For each project, Claude analyzes:**
- All `.jsonl` session files in that project's log directory
- User prompts and Claude's responses
- Tool usage patterns
- Token consumption
- Timestamps and session duration
- Files modified

**Time ranges:**
- By default: Last 30 days of logs
- You can specify: "last week", "last 7 days", "this month", etc.
- Or provide specific dates: "from Nov 1 to Nov 9"

### Limitations

⚠️ **This skill can ONLY analyze:**
- ✅ Logs stored on **THIS machine** in `~/.claude/projects/`
- ✅ Projects you've worked on **using Claude Code on this computer**
- ✅ Sessions that **still have log files** (not deleted)

❌ **Cannot analyze:**
- ❌ Logs from other machines or cloud storage
- ❌ Projects you worked on elsewhere
- ❌ Deleted or archived session logs
- ❌ Sessions from other Claude interfaces (web, mobile)

## Prompt Engineering Best Practices (Claude Official Guidelines)

When analyzing prompt quality, reference these official Claude prompt engineering principles:

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

Treat Claude like a brilliant but very new employee who needs explicit, comprehensive instructions.

### Hierarchy of Prompt Engineering Techniques (Most to Least Effective)

1. **Be Clear and Direct** ⭐ Most Important
   - Provide contextual information (purpose, audience, workflow, end goal)
   - Be specific about expectations
   - Use numbered or bulleted step-by-step instructions
   - Specify output format and constraints
   - Define what successful task completion looks like

2. **Use Examples (Multishot Prompting)**
   - Demonstrate desired output format
   - Show variations and edge cases
   - Provide context for the task
   - Use high-quality, representative examples

3. **Let Claude Think (Chain of Thought)**
   - Break complex tasks into step-by-step processes
   - Allow thinking time/space
   - Request reasoning before conclusions

4. **Use XML Tags**
   - Structure prompts with XML for clarity
   - Separate different types of information
   - Make parsing and understanding easier

5. **Give Claude a Role (System Prompts)**
   - Set context with persona/expertise
   - Define domain knowledge
   - Establish tone and approach

6. **Prefill Claude's Response**
   - Guide output format
   - Set the right starting point

7. **Chain Complex Prompts**
   - Break large tasks into smaller steps
   - Use outputs from one prompt as inputs to next

### Common Prompt Problems to Identify

**❌ Vague/Unclear:**
- "fix the bug"
- "make it better"
- "update the component"
- "write a function"

**✅ Clear/Specific:**
- "fix the authentication error in src/auth/login.ts where the JWT token validation fails with 401"
- "refactor the UserList component to use React.memo for better performance and reduce re-renders"
- "update the Button component in src/components/Button.tsx to use the new design system colors from design-tokens.ts"
- "write a TypeScript function that validates email addresses using RFC 5322 standard and returns a boolean"

### Key Indicators of Good Prompts

1. **Includes Context:**
   - File paths when referencing code
   - Error messages when debugging
   - Expected behavior or outcome
   - Constraints or requirements

2. **Specific Instructions:**
   - Clear, actionable steps
   - Defined output format
   - Success criteria

3. **Appropriate Scope:**
   - Focused on one task
   - Not too broad or ambiguous
   - Realistic complexity

4. **Professional Communication:**
   - Clear language
   - Organized structure
   - Complete information

### When Analyzing Prompts, Score Them On:

1. **Clarity** (0-10): How clear and unambiguous is the request?
2. **Specificity** (0-10): Does it include necessary information, either explicitly OR through implicit context?
   - **Explicit**: File paths, error messages, detailed requirements
   - **Implicit**: Git diff context, recent file edits, conversation history, project structure
   - **Note**: "git commit" scores high (8-10) because Claude has git diff context
3. **Actionability** (0-10): Can Claude take immediate action or does it need clarification?
4. **Scope** (0-10): Is the task appropriately sized and focused?

**Scoring Guide:**
- 8-10: Excellent prompt, minimal clarification needed (includes context-rich brief prompts)
- 5-7: Good prompt, minor clarification possible
- 3-4: Needs improvement, missing key information
- 0-2: Poor prompt, requires significant clarification

**Context-Aware Scoring Examples:**
- ✅ "git commit" = 9/10 (brief but has full git diff context)
- ✅ "run tests" = 8/10 (project structure provides test command context)
- ❌ "fix the bug" = 2/10 (brief AND no context - which bug? where?)
- ✅ "fix authentication bug in src/auth/login.ts - JWT fails with 401" = 10/10 (explicit details)

## Understanding Context in Prompt Quality

**CRITICAL INSIGHT:** Brevity is NOT always a problem. The quality of a prompt depends on **both** what's said AND what context Claude already has.

### The Two Dimensions of Prompt Quality

1. **Explicit Information** - What the user types
2. **Implicit Context** - What Claude can infer from the environment

**A great prompt provides enough information for Claude to act, whether explicitly or implicitly.**

### Types of Context Claude Has Access To

#### 1. Environmental Context

Context Claude can see from the current state of the workspace:

**✅ Git Context:**
- `git diff` showing what changed
- File modifications Claude just made
- Previous commits in the session
- **Example:** "git commit" → Claude can see all changes, will generate excellent commit message

**✅ File Context:**
- Files recently read or edited
- Files in the current workspace
- Code that was just discussed or modified
- **Example:** "edit this function" → Claude knows which file and function from previous context

**✅ Build/Test Context:**
- Project structure (package.json, Cargo.toml, etc.)
- Test suites and frameworks in use
- Build configurations
- **Example:** "run tests" → Claude knows the project's test command

#### 2. Conversation Context

Context from the ongoing discussion:

**✅ Previous Discussion:**
- Feature just discussed or designed
- Problem being debugged
- Implementation approach agreed upon
- **Example:** "implement it" → Follows discussion about what to implement

**✅ Follow-up Requests:**
- Building on previous work
- Iterating on a solution
- Refining based on feedback
- **Example:** "try the other approach" → Refers to alternatives discussed

#### 3. Missing Context (RED FLAG)

Situations where brevity IS a problem:

**❌ No Prior Discussion:**
- First message in a session
- Switching to a completely new topic
- **Example:** "fix the bug" → Which bug? Where?

**❌ Ambiguous References:**
- Using "it", "this", "that" without clear referent
- Multiple possible interpretations
- **Example:** "optimize it" → Optimize what?

**❌ No Environmental Clues:**
- No files in context
- No recent changes to reference
- No clear scope
- **Example:** "update the component" → Which one?

### Recognizing Context-Rich Brief Prompts ✅

**These are EXCELLENT prompts, not problems:**

```
✅ "git commit"
   Context: Git diff visible, files changed
   Why it's good: Claude has everything needed for a great commit message

✅ "git push"
   Context: Just committed changes
   Why it's good: Clear action, obvious target

✅ "run tests"
   Context: Project structure visible
   Why it's good: Claude knows the test framework and command

✅ "build it"
   Context: Just finished implementing a feature
   Why it's good: Build process is obvious from project type

✅ "npm test"
   Context: Node project, package.json visible
   Why it's good: Standard command with clear meaning

✅ "yes" / "no" / "1" / "2"
   Context: Answering Claude's question
   Why it's good: Direct response to options presented

✅ "continue"
   Context: Claude paused and asked for confirmation
   Why it's good: Clear instruction to proceed

✅ "try that"
   Context: Just discussed an alternative approach
   Why it's good: Conversation context makes "that" unambiguous
```

### Recognizing Context-Poor Vague Prompts ❌

**These NEED more information:**

```
❌ "fix the bug"
   Context: None - no error shown, no file mentioned
   Why it's bad: Which bug? Where? What's broken?
   ✅ Better: "fix the authentication error in src/auth/login.ts where JWT validation fails with 401"

❌ "optimize it"
   Context: None - no performance issue discussed
   Why it's bad: Optimize what? For what goal?
   ✅ Better: "optimize the UserList component to reduce re-renders when parent updates"

❌ "make it better"
   Context: None - "better" is subjective
   Why it's bad: Better how? What's the success criteria?
   ✅ Better: "refactor the function to be more readable by extracting the validation logic"

❌ "update the component"
   Context: Multiple components exist, none in current scope
   Why it's bad: Which component? What updates?
   ✅ Better: "update the Button component in src/components/Button.tsx to use the new color tokens"
```

### How to Score Context-Rich vs Context-Poor Prompts

When analyzing prompts, consider:

**High Score (8-10):** Brief + High Context
- "git commit" after making changes
- "run tests" in a clear project structure
- "yes" answering Claude's question
- "implement it" after discussing approach

**Medium Score (5-7):** Somewhat ambiguous but workable
- "fix the error" when error was just shown
- "try again" when previous attempt failed
- "update it" when only one thing was recently discussed

**Low Score (0-4):** Brief + Low Context
- "fix the bug" with no prior context
- "optimize it" with no performance discussion
- "make it better" with no criteria defined
- "update the component" with multiple candidates

### Key Takeaway for Analysis

**When analyzing logs, celebrate efficient communication:**

- ✅ **GOOD:** User says "git commit" → Claude has git diff → Generates excellent message
- ❌ **BAD:** User says "fix the bug" → Claude has no error context → Must ask for clarification

**The goal is NOT to make every prompt long. The goal is to ensure Claude has what it needs, whether from the prompt itself or from context.**

## Log File Location

All Claude Code sessions are logged at: `~/.claude/projects/`

**Directory Structure:**
- Each project has a directory named with escaped path: `-Users-username-path-to-project/`
- Each session is a `.jsonl` file named with a UUID (e.g., `10f49f43-53fd-4910-b308-32ba08f5d754.jsonl`)
- Each line in the file is a JSON object representing one event in the conversation

## Log Entry Format

### User Message Entry
```json
{
  "type": "user",
  "message": {
    "role": "user",
    "content": "the user's prompt text"
  },
  "timestamp": "2025-10-25T13:31:07.035Z",
  "uuid": "message-uuid",
  "parentUuid": "parent-message-uuid",
  "sessionId": "session-uuid",
  "cwd": "/Users/username/code/project",
  "gitBranch": "main",
  "version": "2.0.27"
}
```

### Assistant Message Entry
```json
{
  "type": "assistant",
  "message": {
    "model": "claude-sonnet-4-5-20250929",
    "role": "assistant",
    "content": [
      {
        "type": "text",
        "text": "The assistant's response text"
      },
      {
        "type": "tool_use",
        "id": "tool-uuid",
        "name": "Read",
        "input": {"file_path": "/path/to/file"}
      }
    ],
    "usage": {
      "input_tokens": 1000,
      "output_tokens": 500,
      "cache_creation_input_tokens": 2000,
      "cache_read_input_tokens": 5000
    }
  },
  "timestamp": "2025-10-25T13:31:15.369Z",
  "uuid": "message-uuid",
  "parentUuid": "parent-message-uuid"
}
```

### File History Snapshot Entry
```json
{
  "type": "file-history-snapshot",
  "snapshot": {
    "trackedFileBackups": {},
    "timestamp": "2025-10-25T13:31:07.059Z"
  }
}
```

## Common Tools Used in Logs

- `Read` - File reading
- `Write` - File writing
- `Edit` - File editing
- `Bash` - Shell commands
- `Grep` - Code search
- `Glob` - File pattern matching
- `AskUserQuestion` - Asking user for clarification
- `TodoWrite` - Managing todo lists
- `mcp__*` - Various MCP server tools

## Analysis Tasks

### 0. General Analysis Mode (COMPREHENSIVE REPORT)

**When to trigger:**
- User asks for "general analysis", "overall analysis", "comprehensive report", "complete overview"
- User asks "how am I doing with Claude Code?" or "analyze my Claude Code usage"
- User requests "all metrics", "everything", "full report"
- When the user first activates this skill and you want to offer value

**IMPORTANT:** This is the **premier feature** of Prompt Coach. When triggered, you will:
1. Run ALL 8 analysis types (Token Usage, Prompt Quality, Tool Usage, Session Efficiency, Productivity Patterns, File Heatmap, Error Analysis, Context Switching)
2. Generate ONE comprehensive report combining all insights
3. Use a subagent via Task tool to handle the complexity

**How to execute:**
```
Use the Task tool with general-purpose agent:
- description: "Generate comprehensive Claude Code analysis report"
- subagent_type: "general-purpose"
- prompt: "Analyze all Claude Code session logs in ~/.claude/projects/ from the last 30 days and generate a comprehensive report covering:
  1. Token Usage & Cost Analysis (with deduplication)
  2. Prompt Quality Analysis (context-aware scoring)
  3. Tool Usage Patterns (built-in + MCP tools)
  4. Session Efficiency Analysis
  5. Productivity Time Patterns
  6. File Modification Heatmap
  7. Error & Recovery Analysis
  8. Project Switching Analysis

  Follow the analysis guidelines from the Prompt Coach skill (version 1.10.0).
  Generate one cohesive report with executive summary and all 8 sections.
  Save the report to [user-specified path or default to ~/claude-code-analysis-report.md]"
```

**Report Structure:**

```markdown
# Claude Code Usage Analysis Report
Generated: [Date]
Analysis Period: Last 30 days

## 📊 Executive Summary

[High-level overview with key metrics:]
- Total cost: $X.XX
- Sessions analyzed: X
- Average prompt quality: X.X/10
- Top insight: [Most impactful finding]
- Biggest opportunity: [What would improve usage most]

---

## 1. 💰 Token Usage & Cost Analysis

[Follow guidelines from "1. Token Usage & Cost Analysis" section]
- Total tokens breakdown
- Cost breakdown with cache efficiency
- Deduplication stats
- Monthly projection

---

## 2. ✍️ Prompt Quality Analysis

[Follow guidelines from "2. Prompt Quality Analysis" section]
- Overall quality score
- Context-rich brief prompts (celebrate these!)
- Prompts needing improvement (0-4/10 with specific examples)
- Top 3 actionable recommendations

---

## 3. 🛠️ Tool Usage Patterns

[Follow guidelines from "3. Tool Usage Patterns" section]
- Built-in tools summary
- MCP tools detailed breakdown
- Tool adoption insights
- Common workflows

---

## 4. ⚡ Session Efficiency Analysis

[Follow guidelines from "4. Session Efficiency Analysis" section]
- Average iterations per task
- Session duration patterns
- Completion rate
- Quick wins vs deep work

---

## 5. 🕐 Productivity Time Patterns

[Follow guidelines from "5. Productivity Time Patterns" section]
- Peak productivity hours
- Day of week patterns
- Efficiency by time
- Recommendations for scheduling

---

## 6. 🔥 File Modification Heatmap

[Follow guidelines from "6. File Modification Heatmap" section]
- Most edited files
- Hotspot directories
- Code churn insights
- Refactoring opportunities

---

## 7. 🐛 Error & Recovery Analysis

[Follow guidelines from "7. Error & Recovery Analysis" section]
- Common errors
- Recovery time by error type
- Patterns and recommendations
- Prevention strategies

---

## 8. 🔄 Project Switching Analysis

[Follow guidelines from "8. Project Switching Analysis" section]
- Number of active projects
- Time distribution
- Context switching cost
- Focus optimization tips

---

## 🎯 Top 5 Recommendations

[Synthesize the most impactful recommendations across all 8 analyses]

1. **[Recommendation with biggest ROI]**
   - Impact: [Time saved / cost reduced / quality improved]
   - How to implement: [Specific action steps]

2. **[Second most impactful]**
   ...

[Continue for top 5]

---

## 💡 Next Steps

[3-5 concrete action items the user should take this week]

1. [ ] [Specific, measurable action]
2. [ ] [Specific, measurable action]
3. [ ] [Specific, measurable action]

---

*Report generated by Prompt Coach v1.10.0*
*Analysis based on session logs from ~/.claude/projects/*
```

### 1. Token Usage & Cost Analysis

**When asked about tokens, costs, or spending:**

**Steps:**
1. Use Bash to list recent .jsonl files and get file sizes:
   ```bash
   find ~/.claude/projects -name "*.jsonl" -type f -mtime -30 -exec ls -lh {} \;
   ```

2. Read a representative sample of files (5-10 recent ones)

3. **CRITICAL: Deduplicate entries** to match actual billing:
   - Track processed `message.id + requestId` combinations in a Set
   - Skip duplicate entries (Claude Code logs streaming responses multiple times)
   - Only count each unique API call once

   **Deduplication logic:**
   ```
   For each line in JSONL:
     - Extract message.id and requestId
     - Create hash: `${message.id}:${requestId}`
     - If hash already processed: SKIP this entry
     - Otherwise: mark hash as processed and count tokens
   ```

4. Parse each **unique** entry and extract `usage` data:
   - `input_tokens`
   - `output_tokens`
   - `cache_creation_input_tokens`
   - `cache_read_input_tokens`

5. **CRITICAL: Use model-specific pricing** - Extract model from `message.model` field:

   **Claude API Pricing (Current as of Nov 2025):**

   | Model | Input | Output | Cache Writes | Cache Reads |
   |-------|-------|--------|--------------|-------------|
   | **Opus 4.1** (`claude-opus-4-1-*`) | $15/1M | $75/1M | $18.75/1M | $1.50/1M |
   | **Sonnet 4.5** (`claude-sonnet-4-5-*`) ≤200K | $3/1M | $15/1M | $3.75/1M | $0.30/1M |
   | **Sonnet 4.5** (`claude-sonnet-4-5-*`) >200K | $6/1M | $22.50/1M | $7.50/1M | $0.60/1M |
   | **Haiku 4.5** (`claude-haiku-4-5-*`) | $1/1M | $5/1M | $1.25/1M | $0.10/1M |
   | **Haiku 3.5** (`claude-haiku-3-5-*`) | $0.80/1M | $4/1M | $1/1M | $0.08/1M |
   | **Opus 3** (`claude-3-opus-*`) | $15/1M | $75/1M | $18.75/1M | $1.50/1M |

   **NOTE:** Opus is 5x more expensive than Sonnet!

   **Model Detection:**
   ```
   For each unique entry:
     - Extract model from message.model field
     - Match model name to pricing table
     - Group tokens by model
     - Calculate cost per model using correct rates
   ```

6. **Understand your pricing model** and tailor recommendations:

   📊 **For Pay-Per-Use Users (API billing):**
   - Cost optimization IS directly relevant
   - Switching to Haiku for simple tasks saves money
   - Model selection has immediate cost impact
   - Cache optimization reduces billable tokens

   📊 **For Subscription Users (Claude Pro, Team, Enterprise):**
   - Cost optimization recommendations are LESS relevant
   - **BUT cache optimization is STILL valuable** because:
     - ⚡ **Faster responses** - Anthropic caches your context server-side for ~5 minutes
     - ⚡ **Better UX** - Less waiting for context to process
     - ⚡ **Improved efficiency** - Claude can respond faster with cached context
     - ⚡ **Rate limit benefits** - Better cache usage may help with rate limits
   - Focus on **session efficiency** and **prompt quality** instead of model costs

   💡 **How to tell which pricing model you're on:**
   - If these costs matter to your budget → You're pay-per-use
   - If you pay a fixed monthly fee → You're on subscription
   - When in doubt, ask the user!

7. Present breakdown:
   - Total tokens by type (deduplicated)
   - Cost breakdown (matches actual billing)
   - Cache efficiency (savings from cache reads)
   - Breakdown by model if multiple models used
   - Monthly projection if analyzing less than a month
   - **Deduplication stats**: Show how many duplicates were skipped

**Example Output:**
```
📊 Token Usage Analysis (Last 30 Days)

💰 **Total Cost: $288.13** (matches actual Anthropic billing)

## By Model:

**Sonnet 4.5** (3,662 calls, 81.2%)
- Input:        191,659 ($0.58)
- Output:       135,505 ($2.03)
- Cache writes: 20,010,946 ($75.04)
- Cache reads:  240,989,306 ($72.30)
- **Subtotal: $149.95**

**Opus 4.1** (769 calls, 17.1%)
- Input:        3,176 ($0.05)
- Output:       30,440 ($2.28)
- Cache writes: 2,595,837 ($48.67)
- Cache reads:  57,156,831 ($85.74)
- **Subtotal: $136.74** ⚠️ 5x more expensive than Sonnet!

**Haiku 4.5** (77 calls, 1.7%)
- Input:        54,265 ($0.05)
- Output:       19,854 ($0.10)
- Cache writes: 93,590 ($0.12)
- Cache reads:  666,241 ($0.07)
- **Subtotal: $0.34**

📋 Deduplication Summary:
- Total entries found: 44,036
- Duplicate entries: 6,444 (14.6%)
- Unique API calls: 4,508
- Duplication factor: 9.77x

⚡ Cache Efficiency: 99.9% hit rate
💰 Cache savings: $806.79

---

## 💡 Recommendations

**📌 For Pay-Per-Use Users:**

Your Opus usage (17.1%) costs $136.74 - that's 91% of your total spend!
- Consider using Sonnet for complex tasks instead (5x cheaper)
- Reserve Opus for truly difficult problems only
- **Potential savings:** ~$80-100/month by shifting Opus → Sonnet

**📌 For Subscription Users:**

Cache optimization is still valuable for speed:
- Keep sessions focused on single tasks (maintains cache)
- Avoid context switching (breaks cache, slows responses)
- Your 99.9% cache hit rate is excellent - keep it up!

**📌 For Everyone:**

Haiku is underutilized (1.7% of calls):
- Perfect for: file reads, basic edits, simple commands
- Consider using Haiku for 20-30% of tasks
- Much faster responses for simple operations
```

### 2. Prompt Quality Analysis

**When asked about prompt quality or clarity:**

**🤖 Recommended Approach: Use a Subagent**

For prompt quality analysis, **use the Task tool with general-purpose agent** to handle the complexity of context-aware analysis:

```
Use Task tool with:
- subagent_type: "general-purpose"
- Provide the project path or "analyze all projects"
- Include instructions to apply v1.5.0 context-aware analysis from this skill
```

**Why use a subagent:**
- Reading multiple .jsonl session files (could be 10-100+ sessions with hundreds of prompts)
- Context-aware analysis is nuanced (checking if prompts respond to Claude's questions)
- Detecting context-rich brief prompts (git commands, follow-ups, valid responses)
- Requires judgment for scoring (0-10) considering explicit + implicit context
- Generating comprehensive reports with real examples and insights
- LLM agent is much better than bash/grep scripts for subjective pattern recognition

**The agent should:**
1. Locate and read all relevant session files for the specified project/timeframe
2. Apply the context-aware analysis logic defined below
3. Generate a comprehensive report following the example output format
4. Return the complete analysis for saving or presentation

**Steps (for the subagent to follow):**
1. Read recent session files (last 7-14 days)

2. For each session, identify user prompts (type: "user")

3. Check if the following assistant message contains:
   - **AskUserQuestion tool usage** - Signal that prompt needed clarification (but ignore if user explicitly requested options/choices)
   - **Clarifying questions in text** - Look for patterns like:
     - "Could you clarify"
     - "Which file"
     - "What do you mean"
     - "Can you specify"
     - "I need more information"
     - "Please provide"
     - "Would you like me to"
     - "Should I"
     - "Do you want"

4. **Detect Vague Prompt Patterns** - Look for these red flags in user prompts that trigger clarifications:

   **⚠️ CRITICAL: Context-Aware Analysis**

   Before flagging ANY prompt as vague, **check the conversation context**:

   1. **Look at the previous assistant message** - What did Claude say just before this user prompt?
   2. **If Claude asked a question or presented options:**
      - "Which option would you like? 1, 2, or 3?"
      - "Should I proceed? (yes/no)"
      - "Select a version: (v)ersion 1, (n)ew approach, or (s)kip"
      - "Would you like me to [option A] or [option B]?"
   3. **Then single-word responses are PERFECT, not vague:**
      - "1", "2", "3" → Answering Claude's option question ✅
      - "yes", "no" → Answering Claude's yes/no question ✅
      - "v", "n", "s" → Answering Claude's selection question ✅
      - "continue" → Responding to Claude's confirmation request ✅

   **ONLY flag as vague if:**
   - It's a standalone prompt (not answering Claude's question)
   - It doesn't clearly answer what Claude asked
   - It's the user initiating a new request without context

   ---

   **✅ Context-Rich Brief Prompts (DO NOT FLAG as vague)**

   Before flagging a brief standalone prompt as vague, check if it has **implicit context** from the environment:

   **Git Commands** (Claude has git diff context):
   - "git commit", "git push", "git add", "git commit and push"
   - "commit", "push"
   - **Why not vague:** Claude can see git diff and will generate excellent commit messages
   - **Score these:** 8-10 (Excellent - Claude has full context from git status/diff)

   **Build/Test Commands** (Claude has project structure context):
   - "run tests", "build", "npm test", "npm run build", "cargo build", "make"
   - "test it", "build it"
   - **Why not vague:** Project files show test framework and build configuration
   - **Score these:** 8-10 (Excellent - Claude knows the project structure)

   **Standard Development Commands** (clear from context):
   - "install dependencies", "npm install", "yarn install"
   - "lint", "format", "check types"
   - **Why not vague:** Package managers and tools are evident from project files
   - **Score these:** 7-9 (Good - standard commands with clear meaning)

   **Follow-up Prompts** (Claude just did work):
   - "try again", "revert it", "undo that"
   - "edit this function", "update that", "fix this"
   - **Why not vague:** Recent file reads/edits provide context for "it", "this", "that"
   - **Score these:** 7-9 (Good - conversation context makes references clear)
   - **Check:** Look at previous assistant messages - did Claude just read/edit files?

   **Continuation Prompts** (building on previous work):
   - "continue", "keep going", "finish it"
   - "do the same for [similar item]"
   - **Why not vague:** Refers to work Claude was already doing
   - **Score these:** 7-9 (Good - continuation of established task)

   **IMPORTANT:** Only recognize these patterns as context-rich if:
   1. The prompt matches common git/build/test patterns
   2. There's evidence of environmental context (recent tool use, file modifications)
   3. It's a follow-up to previous work Claude did in the session

   If a brief prompt does NOT match these patterns and has no environmental/conversation context, then apply the vague prompt flags below.

   ---

   **🚩 Missing File Context** (standalone prompts only):
   - "fix the bug" (no file mentioned, initiating request)
   - "update the component" (which one? initiating request)
   - "change the function" (where? initiating request)
   - "add error handling" (to which file/function? initiating request)

   **🚩 Vague Action Words** (standalone prompts only):
   - "improve", "optimize", "make better", "enhance", "clean up"
   - These need specific success criteria (faster by how much? reduce what?)
   - NOT vague if answering "What would you like me to do?"

   **🚩 Missing Error Details** (standalone prompts):
   - "fix the error" (what error? where?)
   - "it's not working" (what's the expected vs actual behavior?)
   - "debug this" (what's the symptom?)

   **🚩 Ambiguous Scope** (standalone prompts):
   - "refactor the code" (which code? to what pattern?)
   - "add tests" (for what? unit/integration/e2e?)
   - "update the docs" (which docs? with what info?)

   **🚩 Missing Approach/Method** (standalone prompts):
   - "add authentication" (OAuth? JWT? Sessions?)
   - "implement caching" (Redis? Memory? File-based?)
   - "add logging" (to console? file? service?)

5. **Extract Real Examples** - Pull actual vague prompts from logs and show what Claude asked for clarification:
   - User's original prompt
   - What Claude had to ask
   - What the improved prompt should have been

6. Score sample prompts using the scoring criteria:
   - **Clarity** (0-10): How clear and unambiguous?
   - **Specificity** (0-10): Includes file paths, error messages, context?
   - **Actionability** (0-10): Can Claude act immediately?
   - **Scope** (0-10): Appropriately sized and focused?

7. Calculate:
   - Total user prompts
   - Prompts needing clarification
   - Clarification rate (% of prompts that triggered AskUserQuestion or clarifying questions)
   - Average prompt quality score
   - **Most common missing elements** (file paths, error messages, success criteria, etc.)

8. Categorize issues using official prompt engineering problems:
   - **Missing context** (no file paths, no error messages) - % of clarifications
   - **Too vague/broad** (no specific expectations) - % of clarifications
   - **Missing success criteria** (no definition of "done") - % of clarifications
   - **Ambiguous requests** (multiple valid interpretations) - % of clarifications
   - **Missing approach** (multiple implementation methods possible) - % of clarifications

9. **CRITICAL: Generate "Areas for Improvement" Section** - For prompts scoring 0-4/10:
   - List EVERY prompt that scored 3-4/10 or lower
   - For EACH low-scoring prompt, provide:
     - The exact prompt text from logs
     - Score (e.g., 3/10)
     - Problem explanation (what's missing or unclear)
     - Context available at that moment
     - What likely happened (Claude's clarification)
     - Better version of the same prompt with specifics
     - Why the better version works
     - Time saved estimate
   - Calculate total impact of these improvements
   - Identify common patterns across these low-scoring prompts

   **This section is MANDATORY if ANY prompts score 0-4/10**

10. Provide specific recommendations based on **Prompt Engineering Best Practices** above, with focus on:
   - Most impactful improvements (what would reduce clarifications most)
   - Specific templates/patterns for common tasks
   - Real examples from their logs showing before/after

**Example Output:**
```
📝 Prompt Quality Analysis (Last 14 Days)

Total prompts: 145
Context-aware analysis: 145 prompts categorized
Average prompt score: 6.8/10 (Very Good!)

✅ Context-Rich Brief Prompts Identified: 23 (16%)
Examples: "git commit", "run tests", "build", "npm install"
These score 8-10/10 - excellent use of environmental context!

📊 Prompt Category Breakdown:
- Excellent (8-10): 45 prompts (31%) - Context-rich OR detailed
- Good (5-7): 71 prompts (49%) - Adequate information
- Needs Work (0-4): 29 prompts (20%) - Brief AND low context

Clarifications needed: 29 (20%) - Down from typical 35%!

🚩 Most Common Issues (context-poor prompts only):
1. Missing file context: 18 prompts (when no files in scope)
2. Missing error details: 14 prompts (when debugging without error shown)
3. Missing success criteria: 16 prompts (vague goals like "optimize")
4. Missing approach: 12 prompts (when multiple methods possible)

🔴 Real Examples from Your Logs (context-poor prompts):

**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

**Example 4: Missing Error Details**
❌ Your prompt: "it's not working"
🤔 Claude asked: "What's not working? What's the expected behavior vs what's happening?"
✅ Better prompt: "the login form isn't submitting - clicking the submit button does nothing, no network requests in console, expected to see POST to /api/auth/login"
📉 Cost: +2 minutes, +1 iteration

---

## ⚠️ Areas for Improvement (Prompts Scoring 0-4/10)

**CRITICAL: If there are prompts scoring 0-4/10, list EVERY SINGLE ONE with specific examples:**

While most of your prompts are good, here are the **X specific prompts that scored 3-4/10** and need improvement:

### Prompts That Need Work

**Example 1: Too Brief Without Context** (Score: 3/10)
❌ **Your prompt:** "test"
- **Problem:** No context about what to test, which tests to run, or which file
- **Context available:** None - standalone request
- **What happened:** Claude likely had to ask: "Which tests? Unit tests? Integration tests? For which component?"
✅ **Better prompt:** "run the unit tests for the YouTube transcript fetcher in src/index.test.ts"
- **Why better:** Specifies test type, component, and file path
- **Time saved:** ~2 minutes

**Example 2: Vague Action Without Specifics** (Score: 4/10)
❌ **Your prompt:** "update the docs"
- **Problem:** Doesn't specify which documentation or what updates to make
- **Context available:** Multiple doc files exist
- **What happened:** Claude needed clarification on which docs and what information to add
✅ **Better prompt:** "update README.md to include installation instructions and usage examples for the get-transcript tool"
- **Why better:** Specific file, specific sections, clear requirements
- **Time saved:** ~3 minutes

[Continue for ALL prompts scoring 0-4/10...]

### Impact of These Improvements

**Current state:**
- X prompts needed significant clarification
- Average Y minutes lost per unclear prompt
- **Total time lost: ~Z minutes**

**If improved:**
- Direct answers without clarification
- **Potential time savings: ~Z minutes** in this project alone
- **Annualized savings:** ~N hours/year on similar projects

### Common Patterns to Avoid

Based on these X examples, watch out for:

1. **🚩 Standalone brief prompts without context**
   - "test", "fix", "update" → Need specifics

2. **🚩 Vague action verbs without details**
   - "improve", "optimize", "make it work" → Need measurable outcomes

3. **🚩 Missing file paths**
   - "update the docs", "add validation" → Include file names

4. **🚩 Ambiguous pronouns**
   - "it", "this", "that" without clear referent → Name the specific component

5. **🚩 No error context**
   - "fix the error" → Include error message and location

6. **🚩 No success criteria**
   - "improve performance" → D

…(truncated)