review-claudemd_skill

Overview

This skill reviews recent Claude conversations to recommend concrete improvements for global (~/.claude/CLAUDE.md) and project-local (./CLAUDE.md) guidance. It automates extraction of recent chats, runs parallel analyzers, and synthesizes actionable changes to wording, patterns, and outdated items. The goal is clearer, enforceable instructions and project-tailored conventions.

How this skill works

The skill locates the project conversation folder under ~/.claude/projects, extracts the most recent 15–20 conversations into a scratch directory, and normalizes messages into text files. It launches parallel Sonnet subagents, each comparing conversation batches to both global and local CLAUDE.md files to identify violations, missing patterns, and obsolete guidance. Finally it aggregates agent outputs into a concise summary of violated instructions, suggested local and global additions, and potentially outdated items.

When to use it

• After a sprint or major chat activity to capture emergent issues
• When onboarding contributors to a project that uses Claude agents
• Before publishing or sharing a global CLAUDE.md update
• When conversation behavior diverges from documented expectations
• To perform regular maintenance of local and global guidance

Best practices

• Run the review on the 15–20 most recent conversations to focus on current patterns
• Exclude the current active conversation to avoid self-bias in findings
• Batch conversations by file size to balance agent workload
• Require subagents to output only bullet points for easier aggregation
• Use the summary to propose targeted rewrites, not entire rewrites

Example use cases

• Reinforce a system prompt rule that users repeatedly ignore (e.g., token budget or reply format)
• Add project-specific Q&A patterns discovered across multiple conversations
• Detect global items that are rarely followed and suggest stronger wording or removal
• Create a short changelog entry from the aggregated suggested edits to share with the team
• Automate periodic hygiene checks for CLAUDE.md files across projects