Skip to content
Back to search

claude-code-prompt-coach-skill

Prompt Coach - Claude Code Usage Analytics Skill

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/hancengiz--claude-code-prompt-coach-skill/badge.svg)](/listings/hancengiz--claude-code-prompt-coach-skill)

HTML

<a href="/listings/hancengiz--claude-code-prompt-coach-skill"><img src="/api/listings/hancengiz--claude-code-prompt-coach-skill/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 462 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Prompt Coach - Claude Code Usage Analytics Skill
  2. A Claude Code skill that analyzes your session logs to provide insights about your coding patterns, token usage, productivity, and prompt quality.
  3. https://www.cengizhan.com/p/claude-code-prompt-coach-skill-to
  4. ## What This Does
  5. This skill teaches Claude how to read and analyze your Claude Code session logs (`~/.claude/projects/*.jsonl`) to help you:
  6. - ✍️ **Improve prompt quality** - Learn if your prompts are clear and effective
  7. - 🎯 **See real examples** - Analyze actual vague prompts from your logs with before/after improvements
  8. - 💰 **Calculate time savings** - Understand the cost of unclear prompts (time + iterations)
  9. - 📋 **Get actionable templates** - Receive specific prompt templates for common tasks
  10. - 🛠️ **Optimize tool usage** - Discover underutilized powerful tools
  11. - ⚡ **Boost efficiency** - Understand how many iterations you need per task
  12. - 🕐 **Find peak hours** - Know when you're most productive
  13. - 🔥 **Identify code hotspots** - See which files you edit most
  14. - 🔄 **Reduce context switching** - Measure project switching overhead
  15. - 🐛 **Learn from errors** - Understand common problems and recovery patterns
  16. ## Installation
  17. ### Quick Install (Recommended)
  18. Run the install script:
  19. ```bash
  20. cd ~/code/claude-code-prompt-coach-skill
  21. ./install.sh
  22. ```
  23. The script will:
  24. - ✅ Create `~/.claude/skills/` if needed
  25. - ✅ Check for existing installations
  26. - ✅ Copy the skill to the correct location
  27. - ✅ Verify installation
  28. - ✅ Show next steps
  29. Restart Claude Code and you're done!
  30. ### Manual Install
  31. Copy the skill directory to your Claude skills folder:
  32. ```bash
  33. cp -r ~/code/claude-code-prompt-coach-skill ~/.claude/skills/prompt-coach
  34. ```
  35. ### For Development (Symlink)
  36. Create a symlink to the skill directory:
  37. ```bash
  38. ln -s ~/code/claude-code-prompt-coach-skill ~/.claude/skills/prompt-coach
  39. ```
  40. Now you can edit `Skill.md` and changes take effect on next Claude Code restart.
  41. ## Usage
  42. **IMPORTANT:** This skill analyzes logs from **THIS machine only**. It can only access Claude Code session logs stored locally in `~/.claude/projects/`.
  43. ### Option 1: Analyze All Projects
  44. Just ask Claude natural questions about your usage across all projects:
  45. ```
  46. "How much have I spent on tokens this month?"
  47. "Analyze my prompt quality from last week"
  48. "Which tools do I use most?"
  49. "Show me my productivity patterns"
  50. "What files do I edit most often?"
  51. "When am I most efficient?"
  52. ```
  53. Claude will automatically read all your session logs and provide detailed analysis.
  54. ### Option 2: List Projects First, Then Pick One
  55. If you want to see what projects have logs and choose one:
  56. ```
  57. "List all projects with Claude Code logs"
  58. "Show me which projects I've worked on"
  59. "What projects do I have session logs for?"
  60. ```
  61. Claude will show you all available projects with details (sessions count, date range, size), and you can pick which one to analyze.
  62. ### Option 3: Analyze a Specific Project
  63. If you know the project path, analyze just that project:
  64. ```
  65. "Analyze my prompt quality for the project under ~/code/youtube/transcript/mcp"
  66. "Analyze my prompt quality for /Users/username/code/my-app and save it as report.md"
  67. "Show me token usage for the project in ~/code/experiments"
  68. "What tools do I use most in the ~/code/my-app project?"
  69. ```
  70. This analyzes **only the logs for that specific project**, giving you focused insights.
  71. ## Example Output
  72. ### Token Usage Analysis
  73. ```
  74. 📊 Token Usage Analysis (Last 30 Days)
  75. Input tokens: 450,000 ($1.35)
  76. Output tokens: 125,000 ($1.88)
  77. Cache writes: 200,000 ($0.75)
  78. Cache reads: 1,500,000 ($0.45)
  79. ─────────────────
  80. Total cost: $4.43
  81. Cache savings: $4.05
  82. Cache efficiency: 75% hit rate
  83. 💡 Tip: Your cache hit rate is excellent! You're saving ~$4/month
  84. by keeping focused sessions.
  85. ```
  86. ### Prompt Quality Analysis
  87. ```
  88. 📝 Prompt Quality Analysis (Last 14 Days)
  89. Total prompts: 145
  90. Needed clarification: 51 (35%)
  91. Average prompt score: 5.2/10 (Good, room for improvement)
  92. 🚩 Most Common Missing Elements:
  93. 1. File paths: Missing in 61 prompts (42%)
  94. 2. Error details: Missing in 34 prompts (23%)
  95. 3. Success criteria: Missing in 43 prompts (30%)
  96. 4. Specific approach: Missing in 28 prompts (19%)
  97. 🔴 Real Examples from Your Logs:
  98. **Example 1: Missing File Context**
  99. ❌ Your prompt: "fix the bug"
  100. 🤔 Claude asked: "Which file has the bug? What's the error message or symptom?"
  101. ✅ Better prompt: "fix the authentication bug in src/auth/login.ts where JWT validation fails with 401 error"
  102. 📉 Cost: +2 minutes, +1 iteration
  103. **Example 2: Vague Action Words**
  104. ❌ Your prompt: "optimize the component"
  105. 🤔 Claude asked: "Which component? What performance issue? What's the target?"
  106. ✅ Better prompt: "optimize UserList component in src/components/UserList.tsx by adding React.memo to reduce unnecessary re-renders when parent updates"
  107. 📉 Cost: +3 minutes, +1 iteration
  108. **Example 3: Missing Approach**
  109. ❌ Your prompt: "add caching"
  110. 🤔 Claude asked: "Where should caching be added? What caching strategy? (Redis, memory, file-based?)"
  111. ✅ 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"
  112. 📉 Cost: +4 minutes, +2 iterations
  113. 📉 Impact Analysis:
  114. - 51 prompts needed clarification
  115. - Average time lost per clarification: 2.8 minutes
  116. - Total time lost to vague prompts: ~2.4 hours
  117. - **Potential time savings: ~1.2 hours by improving top 25 vague prompts**
  118. 🎯 Your Top 3 Improvements (Maximum Impact):
  119. **1. Always Include File Paths (42% of clarifications)**
  120. Template: "[action] in [file path] [details]"
  121. 💰 Impact: Would eliminate ~21 clarifications (~1 hour saved)
  122. **2. Provide Error Details When Debugging (23% of clarifications)**
  123. Template: "fix [error message] in [file] - expected [X], getting [Y]"
  124. 💰 Impact: Would eliminate ~12 clarifications (~25 min saved)
  125. **3. Define Success Criteria for Vague Actions (30% of clarifications)**
  126. Instead of: "optimize", "improve", "make better"
  127. Use: "[action] to achieve [specific measurable outcome]"
  128. 💰 Impact: Would eliminate ~15 clarifications (~40 min saved)
  129. 💡 Quick Win: Apply these templates to your next 10 prompts and watch your clarification rate drop!
  130. 💪 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.
  131. ```
  132. ### Tool Usage Patterns
  133. ```
  134. 🛠️ Tool Usage Patterns (Last 30 Days)
  135. Most used tools:
  136. 1. Read ████████████████████ 450 uses
  137. 2. Edit ████████████ 220 uses
  138. 3. Bash ███████ 150 uses
  139. 4. Grep ██ 34 uses
  140. 💡 Insights:
  141. ✅ Good: You use Read heavily - shows careful code review
  142. ⚠️ Opportunity: Low Grep usage (34 uses vs 450 Reads)
  143. → Try Grep for searching across multiple files
  144. → It's much faster than reading each file
  145. ```
  146. ## Available Analysis Types
  147. 1. **Token Usage & Cost Tracking** - Detailed breakdown with current pricing
  148. 2. **Enhanced Prompt Quality Analysis** ⭐ NEW! - Advanced analysis that:
  149. - Detects vague prompt patterns (missing file paths, error details, success criteria)
  150. - Shows real examples from YOUR logs with what Claude had to ask
  151. - Provides before/after improvements for actual prompts you wrote
  152. - Calculates time/iteration cost of unclear prompts
  153. - Gives actionable templates ranked by impact
  154. - Identifies most common missing elements in your prompts
  155. 3. **Tool Usage Patterns** - Which tools you use most/least
  156. 4. **Session Efficiency** - Average iterations per task
  157. 5. **Productivity Time Patterns** - Best hours and days to code
  158. 6. **File Modification Heatmap** - Most frequently edited files
  159. 7. **Error & Recovery Analysis** - Common errors and how long they take to fix
  160. 8. **Project Switching Analysis** - Context switching costs
  161. ## How It Works
  162. The skill provides Claude with:
  163. - **Official Claude prompt engineering best practices** from Anthropic's documentation
  164. - Knowledge of where logs are stored (`~/.claude/projects/`)
  165. - Understanding of the JSONL log format
  166. - A scoring system for prompt quality (Clarity, Specificity, Actionability, Scope)
  167. - Patterns to look for (tool usage, tokens, timestamps, etc.)
  168. - Instructions on how to calculate metrics
  169. - Templates for presenting insights
  170. Claude then uses its built-in tools (Read, Bash, Grep) to:
  171. 1. Find and read your log files
  172. 2. Parse the JSON data
  173. 3. Score your prompts against official best practices
  174. 4. Calculate metrics
  175. 5. Generate personalized, actionable insights
  176. **No external dependencies, no installations, no data leaving your machine.**
  177. ## Prompt Engineering Knowledge
  178. The skill is trained on official Claude prompt engineering guidelines, including:
  179. ### The Golden Rule
  180. **"Show your prompt to a colleague with minimal context. If they're confused, Claude will likely be too."**
  181. ### Prompt Engineering Hierarchy (What Works Best)
  182. 1. ⭐ **Be Clear and Direct** - Most effective
  183. 2. **Use Examples (Multishot)** - Show desired output
  184. 3. **Let Claude Think** - Chain of thought reasoning
  185. 4. **Use XML Tags** - Structure for clarity
  186. 5. **Give Claude a Role** - Set context
  187. 6. **Prefill Responses** - Guide output format
  188. 7. **Chain Complex Prompts** - Break into steps
  189. When analyzing your prompts, the skill evaluates them against these techniques and provides specific recommendations for improvement.
  190. ## Skill Design: Prompt Engineering in Action
  191. The `Skill.md` file itself is a masterclass in prompt engineering, practicing what it preaches. Here's how it's constructed:
  192. ### Core Techniques Applied
  193. **1. Clear Role Definition (System Prompts)**
  194. - Establishes Claude as "an AI-native engineering expert and prompt engineering specialist"
  195. - Defines domain expertise upfront (lines 9-15)
  196. - Sets clear expectations for behavior and knowledge
  197. **2. Hierarchical Structure & Organization**
  198. - Markdown headers create clear information hierarchy
  199. - Numbered step-by-step instructions for each analysis task
  200. - Visual indicators (emojis, ASCII art) for quick pattern recognition
  201. - Logical flow from general concepts to specific implementations
  202. **3. Extensive Examples (Multishot Prompting)**
  203. - Full example outputs for every analysis type (Token Usage, Prompt Quality, etc.)
  204. - Before/after comparisons showing good vs. bad prompts
  205. - Real-world scenarios with context-aware scoring
  206. - Template patterns for reusable prompt structures
  207. **4. Step-by-Step Instructions (Chain of Thought)**
  208. - Each analysis task includes 5-10 explicit steps
  209. - Sequential reasoning from data collection to insight generation
  210. - Clear decision trees (e.g., context-aware analysis logic)
  211. - Systematic approach to subjective evaluation
  212. **5. Specificity & Actionability**
  213. - Exact file paths: `~/.claude/projects/*.jsonl`
  214. - Precise JSON field names: `usage.input_tokens`, `message.content`
  215. - Current pricing data: $3 per 1M input tokens
  216. - Specific patterns to detect: "Could you clarify", "Which file"
  217. - Concrete scoring criteria: Clarity (0-10), Specificity (0-10)
  218. **6. Success Criteria Definition**
  219. - Explicit scoring guidelines with ranges (8-10 = Excellent, 5-7 = Good, etc.)
  220. - Examples of what scores mean in practice
  221. - Clear metrics for evaluation (clarification rate, iteration count)
  222. - Quantified outcomes (time saved, efficiency improvements)
  223. **7. Edge Cases & Error Handling**
  224. - Explicit limitations section (what CAN'T be analyzed)
  225. - Context-aware analysis with conditional logic
  226. - Privacy considerations and parsing safeguards
  227. - Handling of ambiguous or brief prompts with environmental context
  228. **8. Templates & Reusable Patterns**
  229. - Prompt templates: `"[action] in [file path] [details]"`
  230. - Error reporting template: `"fix [error message] in [file] - expected [X], getting [Y]"`
  231. - Success criteria template: `"[action] to achieve [specific measurable outcome]"`
  232. - Analysis output format templates for consistency
  233. **9. Comparative Analysis (Good vs Bad)**
  234. - Systematic contrasts between effective and ineffective approaches
  235. - Context-rich brief prompts (✅ "git commit") vs context-poor vague prompts (❌ "fix the bug")
  236. - Visual markers (✅/❌) for instant clarity
  237. - Explanations of why each example works or fails
  238. **10. Meta-Instructions & Critical Insights**
  239. - "Understanding Context in Prompt Quality" section teaches analysis methodology
  240. - Two dimensions of quality: explicit information + implicit context
  241. - Recognition patterns for different types of context (git, file, conversation)
  242. - Nuanced guidance on when brevity is good vs. when it's problematic
  243. ### Why This Design Works
  244. The skill file follows the **same hierarchy** it teaches (lines 160-197 in Skill.md):
  245. 1. ⭐ **Clear and Direct** - Every instruction is explicit and unambiguous
  246. 2. **Examples** - Demonstrates desired outputs with real-world scenarios
  247. 3. **Chain of Thought** - Breaks complex analysis into step-by-step processes
  248. 4. **Structure** - XML-like markers and markdown for organization
  249. 5. **Role Definition** - Sets expertise context upfront
  250. 6. **Templates** - Provides reusable patterns
  251. 7. **Chaining** - Sequences of steps for complex tasks
  252. ### Design Principles Used
  253. - **No Ambiguity**: Every term is defined, every pattern is specified
  254. - **Actionable Instructions**: Claude knows exactly what to do at each step
  255. - **Context-Aware**: Recognizes when brevity is efficient vs. when it's vague
  256. - **Example-Rich**: Shows don't tell - extensive demonstrations of desired behavior
  257. - **Self-Referential**: The skill itself models excellent prompt engineering
  258. This meta-design approach ensures that Claude not only *knows* prompt engineering best practices but actively *demonstrates* them when teaching users about their own prompts.
  259. ## Privacy
  260. - ✅ All data stays local on your machine
  261. - ✅ No external services called
  262. - ✅ No tracking or analytics
  263. - ✅ You control the skill file
  264. ## Customization
  265. Want to add your own analysis types? Just edit `Skill.md` and add:
  266. ```markdown
  267. ### 9. Your Custom Analysis
  268. **When asked about [your topic]:**
  269. **Steps:**
  270. 1. Read session files
  271. 2. Look for [pattern]
  272. 3. Calculate [metric]
  273. 4. Present [insights]
  274. ```
  275. ## Example Queries
  276. ### General Analysis (All Projects)
  277. **Costs:**
  278. - "How much have I spent this month?"
  279. - "What's my cache efficiency?"
  280. - "Show me costs by model"
  281. **Productivity:**
  282. - "When am I most productive?"
  283. - "How efficient are my sessions?"
  284. - "Show me my coding patterns from last week"
  285. **Code Patterns:**
  286. - "Which files do I edit most?"
  287. - "Show me my file modification heatmap"
  288. **Learning:**
  289. - "Am I writing good prompts?"
  290. - "Analyze my prompt quality and show me real examples of vague prompts I wrote"
  291. - "What are the most common things missing from my prompts?"
  292. - "Show me before/after examples of how to improve my prompts"
  293. - "How much time am I losing to unclear prompts?"
  294. - "Give me templates for better prompts based on my usage patterns"
  295. - "Which tools should I use more?"
  296. - "What are my common errors?"
  297. ### Project Discovery
  298. - "List all projects with Claude Code logs"
  299. - "Show me which projects I've worked on"
  300. - "What projects do I have session logs for?"
  301. - "Which project have I spent the most time on this week?"
  302. ### Project-Specific Analysis
  303. - "Analyze my prompt quality for the project under ~/code/youtube/transcript/mcp"
  304. - "Show me token usage for the project in ~/code/my-app"
  305. - "What tools do I use most in the ~/code/experiments project?"
  306. - "How efficient are my sessions for /Users/username/code/my-project?"
  307. - "Which files do I edit most in the ~/code/dotfiles project?"
  308. - "Analyze my prompt quality for ~/code/my-app and save it as reports/prompt-analysis.md"
  309. ## Troubleshooting
  310. **Skill not working?**
  311. 1. Verify installation:
  312. ```bash
  313. ls -la ~/.claude/skills/prompt-coach/Skill.md
  314. ```
  315. 2. Restart Claude Code completely
  316. 3. Try being explicit:
  317. ```
  318. "Use the Prompt Coach skill to analyze my prompt quality"
  319. ```
  320. **Need more detail?**
  321. Ask follow-up questions:
  322. ```
  323. "Show me specific examples of vague prompts I wrote"
  324. "Break down my token usage by project"
  325. "Which Tuesdays was I most productive?"
  326. ```
  327. ## Requirements
  328. - Claude Code CLI (any recent version)
  329. - Session logs in `~/.claude/projects/` (automatically created by Claude Code)
  330. ## License
  331. MIT
  332. ## Contributing
  333. Found a useful analysis pattern? Edit the skill and share!
  334. Ideas for new analysis types:
  335. - Git commit patterns
  336. - Language/framework usage
  337. - Collaboration patterns (if analyzing team logs)
  338. - Learning curve tracking over time
  339. - Custom benchmarks against your own history
  340. ## Credits
  341. Built for developers who want to optimize their Claude Code usage and improve their coding workflows.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.