refresh-claude

name	refresh-claude
description	Review recent changes and update CLAUDE.md to keep it relevant for future sessions. Use after significant changes or periodically to maintain context.
tools	Read, Grep, Glob, Edit, Write, Bash
user-invocable	true

Refresh CLAUDE.md

You are refreshing the project's CLAUDE.md file to ensure it stays relevant and useful for future Claude Code sessions.

Purpose

CLAUDE.md serves as persistent context between sessions. When a project evolves, CLAUDE.md should evolve too. This skill:

1. Reviews recent changes to the codebase
2. Identifies new patterns, conventions, or important context
3. Updates CLAUDE.md to reflect current state
4. Removes outdated information

Process

Step 1: Analyze Recent Changes

# Recent commits
git log --oneline -20

# Changed files
git diff --stat HEAD~10..HEAD

# New files
git diff --name-status HEAD~10..HEAD | grep "^A"

Look for:

• New features or modules
• New dependencies or tools
• Changed conventions or patterns
• New commands or scripts
• Architecture changes

Step 2: Review Current CLAUDE.md

Read the existing CLAUDE.md and identify:

• Outdated information
• Missing new features/tools
• Incorrect commands or paths
• Stale conventions

Step 3: Scan the Codebase

Check for patterns not reflected in CLAUDE.md:

# Check for new test patterns
ls -la **/test* **/*test* **/*spec* 2>/dev/null | head -20

# Check for new config files
ls -la *.config.* .* 2>/dev/null | head -20

# Check package.json/pyproject.toml/etc for new scripts
cat package.json 2>/dev/null | jq '.scripts' || true

Step 4: Update CLAUDE.md

Make targeted updates:

DO update:

• New commands (dev, test, build, lint)
• New project structure (directories, key files)
• New conventions discovered in code
• Important architectural decisions
• New dependencies that affect how to work with the code

DON'T add:

• Implementation details that change frequently
• Obvious things (e.g., "this is a JavaScript project" for a .js repo)
• Temporary workarounds
• Personal preferences not enforced by tooling

Step 5: Verify Changes

After updating, verify:

• Commands still work
• Paths are correct
• No duplicate sections
• Concise and scannable

Output Format

## CLAUDE.md Refresh Summary

### Changes Made
- Added: [what was added]
- Updated: [what was updated]
- Removed: [what was removed]

### Context Discovered
- [New pattern or convention found]
- [New tool or command found]

### Recommendations
- [Suggestions for project improvements]

Guidelines

Keep It Concise

CLAUDE.md should be scannable. Every line should earn its place.

❌ "This project uses React, which is a JavaScript library for building user interfaces..."
✓ "React 18 with TypeScript. See src/components/ for patterns."

Focus on What's Actionable

Include information Claude needs to work effectively:

✓ Commands to run
✓ Key file locations
✓ Conventions to follow
✓ Things to avoid

Avoid Duplication

Don't repeat what's in:

• README.md (user-facing docs)
• Code comments (implementation details)
• Config files (tooling handles it)

Keep It Fresh

Remove information that's:

• No longer accurate
• Covered by tooling (linters, formatters)
• Too detailed for context

Example Updates

Adding a New Command

## Commands
+ npm run e2e        # Run end-to-end tests

Adding a Convention

## Conventions
+ API routes follow REST conventions in `src/api/`
+ Use `zod` for runtime validation at API boundaries

Removing Outdated Info

- ## Legacy
- The old auth system in `src/auth-old/` is deprecated.

When to Run

• After adding major features
• After significant refactoring
• After adding new tools or dependencies
• Periodically (weekly/monthly) on active projects
• Before onboarding new team members