architecture/old/skills/update-claude-md/SKILL.md

name, description, model, context, user-invocable

name	description	model	context	user-invocable
update-claude-md	Update or create CLAUDE.md with current project context. Explores the project and ensures organization context is present. Use when updating project docs, adding CLAUDE.md, or when user says /update-claude-md.	haiku	fork	true

Update CLAUDE.md

@/.claude/skills/claude-md-writing/SKILL.md @/.claude/skills/repo-conventions/SKILL.md

Update or create CLAUDE.md for the current repository with proper organization context and current project state.

Process

1. Check for existing CLAUDE.md: Look for CLAUDE.md in repo root

2. If CLAUDE.md exists:

   • Read current content
   • Identify which sections exist
   • Note any custom content to preserve

3. Explore the project:

   • Scan directory structure
   • Identify language/framework (go.mod, package.json, Cargo.toml, etc.)
   • Find key patterns (look for common directories, config files)
   • Check for Makefile or build scripts

4. Check organization context:

   • Does it have the "Organization Context" section?
   • Does it link to ../architecture/manifesto.md?
   • Does it link to ../architecture/repos.md?
   • Does it link to ./vision.md?

5. Gather missing information:

   • If no one-line description: Ask user
   • If no architecture section: Infer from code or ask user

6. Update CLAUDE.md:

   Always ensure these sections exist:

   # [Project Name]
   
   [One-line description]
   
   ## Organization Context
   
   This repo is part of Flowmade. See:
   - [Organization manifesto](../architecture/manifesto.md) - who we are, what we believe
   - [Repository map](../architecture/repos.md) - how this fits in the bigger picture
   - [Vision](./vision.md) - what this specific product does
   
   ## Setup
   
   [From existing or ask user]
   
   ## Project Structure
   
   [Generate from actual directory scan]
   
   ## Development
   
   [From Makefile or existing]
   
   ## Architecture
   
   [From existing or infer from code patterns]
   

7. Preserve custom content:

   • Keep any additional sections the user added
   • Don't remove information, only add/update
   • If unsure, ask before removing

8. Show diff and confirm:

   • Show what will change
   • Ask user to confirm before writing

Section-Specific Guidance

Project Structure

Generate from actual directory scan:

# Scan top-level and key subdirectories
ls -la
ls pkg/ cmd/ internal/ src/ (as applicable)

Format as tree showing purpose:

## Project Structure

\`\`\`
project/
├── cmd/           # Entry points
├── pkg/           # Shared packages
│   ├── domain/    # Business logic
│   └── infra/     # Infrastructure
└── internal/      # Private packages
\`\`\`

Development Commands

Extract from Makefile if present:

grep -E "^[a-zA-Z_-]+:" Makefile | head -10

Or from package.json scripts, Cargo.toml, etc.

Architecture

Look for patterns:

• Event sourcing: Check for aggregates, events, projections
• Clean architecture: Check for domain, application, infrastructure layers
• API style: REST, gRPC, GraphQL

If unsure, ask: "What are the key architectural patterns in this project?"

Output Example

## Updating CLAUDE.md

### Current State
- Has description: ✓
- Has org context: ✗ (will add)
- Has setup: ✓
- Has structure: Outdated (will update)
- Has development: ✓
- Has architecture: ✗ (will add)

### Changes

+ Adding Organization Context section
~ Updating Project Structure (new directories found)
+ Adding Architecture section

### New Project Structure

\`\`\`
arcadia/
├── cmd/
├── pkg/
│   ├── aether/      # Event sourcing runtime
│   ├── iris/        # WASM UI framework
│   ├── adl/         # Domain language
│   └── ...
└── internal/
\`\`\`

Proceed with update? [y/n]

Guidelines

• Always add Organization Context if missing
• Preserve existing custom sections
• Update Project Structure from actual filesystem
• Don't guess at Architecture - ask if unclear
• Show changes before writing
• Reference claude-md-writing skill for best practices