Review Claudemd
Agent Buildingreview-claudemdReview Claudemd is an Agent Skill for agent building published in the ykdojo/claude-code-tips repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Review recent conversations to find improvements for CLAUDE.md files.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/ykdojo/claude-code-tips/blob/HEAD/skills/review-claudemd/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/review-claudemd, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
Review CLAUDE.md from conversation history
Analyze recent conversations to improve both global (~/.claude/CLAUDE.md) and local (project) CLAUDE.md files.
Step 1: Find conversation history
The project's conversation history is in ~/.claude/projects/. The folder name is the project path with slashes replaced by dashes.
# Find the project folder (replace / with -)
PROJECT_PATH=$(pwd | sed 's|/|-|g' | sed 's|^-||')
CONVO_DIR=~/.claude/projects/-${PROJECT_PATH}
ls -lt "$CONVO_DIR"/*.jsonl | head -20
Step 2: Extract recent conversations
Extract the 15-20 most recent conversations (excluding the current one) to a temp directory:
SCRATCH=/tmp/claudemd-review-$(date +%s)
mkdir -p "$SCRATCH"
for f in $(ls -t "$CONVO_DIR"/*.jsonl | head -20); do
basename=$(basename "$f" .jsonl)
# Skip current conversation if known
cat "$f" | jq -r '
if .type == "user" then
"USER: " + (.message.content // "")
elif .type == "assistant" then
"ASSISTANT: " + ((.message.content // []) | map(select(.type == "text") | .text) | join("\n"))
else
empty
end
' 2>/dev/null | grep -v "^ASSISTANT: $" > "$SCRATCH/${basename}.txt"
done
ls -lhS "$SCRATCH"
Step 3: Spin up subagents
Launch parallel subagents to analyze conversations. Each agent should read:
- Global CLAUDE.md:
~/.claude/CLAUDE.md - Local CLAUDE.md:
./CLAUDE.md(if exists) - Batch of conversation files
Give each agent this prompt template:
Read:
1. Global CLAUDE.md: ~/.claude/CLAUDE.md
2. Local CLAUDE.md: [project]/CLAUDE.md
3. Conversations: [list of files]
Analyze the conversations against BOTH CLAUDE.md files. Find:
1. Instructions that exist but were violated (need reinforcement or rewording)
2. Patterns that should be added to LOCAL CLAUDE.md (project-specific)
3. Patterns that should be added to GLOBAL CLAUDE.md (applies everywhere)
4. Anything in either file that seems outdated or unnecessary
Be specific. Output bullet points only.
Batch conversations by size:
- Large (>100KB): 1-2 per agent
- Medium (10-100KB): 3-5 per agent
- Small (<10KB): 5-10 per agent
Step 4: Aggregate findings
Combine results from all agents into a summary with these sections:
- Instructions violated - existing rules that weren't followed (need stronger wording)
- Suggested additions - LOCAL - project-specific patterns
- Suggested additions - GLOBAL - patterns that apply everywhere
- Potentially outdated - items that may no longer be relevant
Present as tables or bullet points. Ask user if they want edits drafted.