OpenParable
Skip to content
← Back to skills

Review Claudemd

Agent Building
review-claudemd

Review 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.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
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:

  1. Instructions violated - existing rules that weren't followed (need stronger wording)
  2. Suggested additions - LOCAL - project-specific patterns
  3. Suggested additions - GLOBAL - patterns that apply everywhere
  4. Potentially outdated - items that may no longer be relevant

Present as tables or bullet points. Ask user if they want edits drafted.