Project: MyApp Skill | Agent Skills

Generate or update the project's CLAUDE.md file based on blueprint artifacts, PRDs, and project structure.

When to Use This Skill

| Use this skill when... | Use alternative when... | |------------------------|-------------------------| | Need to create/update CLAUDE.md for team instructions | Use /blueprint:rules for path-specific rules | | Want to add @imports to existing CLAUDE.md | Use /blueprint:generate-rules to create rules from PRDs | | Need to create CLAUDE.local.md for personal preferences | Editing individual rule files directly | | Converting inline content to lean @import structure | Just need to view current memory configuration |

CLAUDE.md vs Auto Memory

Claude Code has two complementary systems for project context. CLAUDE.md should contain team-shared instructions — not patterns Claude learns on its own.

| Belongs in CLAUDE.md | Belongs in Auto Memory (managed by Claude) | |----------------------|---------------------------------------------| | Team coding standards | Debugging insights and workarounds | | Build/test/lint commands | Personal workflow preferences | | Architecture decisions | Project-specific patterns learned over time | | Required conventions | File relationships and navigation shortcuts | | CI/CD workflows | Common mistakes and how to fix them |

Auto memory lives at ~/.claude/projects/<project>/memory/ and is managed automatically. Do not duplicate auto memory concerns into CLAUDE.md.

Memory Hierarchy (precedence low → high)

User-level rules: ~/.claude/rules/ — personal rules across all projects
CLAUDE.md (project): Team-shared project instructions (checked into git)
CLAUDE.local.md: Personal project-specific preferences (gitignored)
.claude/rules/: Modular, path-specific rules
Managed policy: Organization-wide instructions (enterprise, system paths)
Auto memory: Claude's own notes (~/.claude/projects/<project>/memory/)

@import Syntax

CLAUDE.md files support importing other markdown files to stay lean:

# Project: MyApp

@docs/architecture.md
@docs/conventions.md
@.claude/rules/testing.md

Paths are relative to the file containing the import
Recursive imports supported (max depth 5)
Imports are not evaluated inside code spans or code blocks
First-time external imports trigger an approval dialog

Use @import to reference existing documentation rather than duplicating content into CLAUDE.md.

Steps:

Check current state:
- Look for existing CLAUDE.md in project root
- Look for existing CLAUDE.local.md (personal preferences, gitignored)
- Read docs/blueprint/manifest.json for configuration
- Check for ~/.claude/rules/ (user-level rules)
- Determine claude_md_mode (single, modular, or both)

Determine action (use AskUserQuestion):

{If CLAUDE.md exists:}
question: "CLAUDE.md already exists. What would you like to do?"
options:
  - "Update with latest project info" → merge updates
  - "Regenerate completely" → overwrite (backup first)
  - "Add missing sections only" → append new content
  - "Add @imports for existing docs" → replace inline content with imports
  - "Convert to modular rules" → split into .claude/rules/
  - "Create CLAUDE.local.md" → personal preferences (gitignored)
  - "View current structure" → analyze and display

{If CLAUDE.md doesn't exist:}
question: "No CLAUDE.md found. How would you like to create it?"
options:
  - "Generate from project analysis" → auto-generate
  - "Generate from PRDs" → use blueprint PRDs
  - "Generate with @imports (lean)" → auto-generate using imports for existing docs
  - "Start with template" → use starter template
  - "Use modular rules instead" → skip CLAUDE.md, use rules/

Gather project context:
- Project structure: Detect language, framework, build tools
- PRDs: Read docs/prds/*.md for requirements
- Work overview: Current phase and progress
- Existing rules: Content from .claude/rules/ if present
- Git history: Recent patterns and conventions
- Dependencies: Package managers, key libraries

Generate CLAUDE.md sections:

Standard sections (focused on team-shared instructions):

# Project: {name}

## Overview
{Brief project description from PRDs or detection}

## Tech Stack
- Language: {detected}
- Framework: {detected}
- Build: {detected}
- Test: {detected}

## Development Workflow

### Getting Started
{Setup commands}

### Running Tests
{Test commands}

### Building
{Build commands}

## Architecture
{Key architectural decisions from PRDs — or use @import:}
@docs/prds/architecture-prd.md

## Conventions

### Code Style
{Detected or from PRDs}

### Commit Messages
{Conventional commits if detected}

### Testing Requirements
{From PRDs or rules}

## See Also
{If modular rules enabled:}
- `.claude/rules/` - Detailed rules by domain
- `docs/prds/` - Product requirements

Sections to omit (auto memory handles these automatically):

"Current Focus" — Claude tracks this in auto memory
"Key Files" — Claude learns file relationships automatically
Debugging tips — Claude records these in auto memory topic files

If modular rules mode = "both":

Keep CLAUDE.md as high-level overview

Reference .claude/rules/ for details:

## Detailed Rules
See `.claude/rules/` for domain-specific guidelines:
- `development.md` - Development workflow
- `testing.md` - Testing requirements
- `frontend/` - Frontend-specific rules
- `backend/` - Backend-specific rules

If modular rules mode = "modular":

Create minimal CLAUDE.md with @import references
Move detailed content to .claude/rules/

Example lean CLAUDE.md:

# Project: {name}

## Overview
{One-paragraph description}

@docs/prds/main.md

## Development
{Build, test, lint commands}

## Rules
See `.claude/rules/` for detailed guidelines.

6b. If "Create CLAUDE.local.md" selected:

Create CLAUDE.local.md in project root for personal preferences
Add CLAUDE.local.md to .gitignore if not already present

Template:

# Personal Preferences

## My Environment
- IDE: {detected or ask}
- Terminal: {detected or ask}

## My Workflow Preferences
- {Personal conventions not shared with team}

6c. If "Add @imports" selected:

Scan existing CLAUDE.md for sections with content that exists in other files
Replace duplicated content with @path/to/source.md imports
Preserve CLAUDE.md-only content inline
Show diff of changes before applying

Smart update (for existing CLAUDE.md):
- Parse existing sections
- Identify outdated content (compare with PRDs, structure)
- Offer section-by-section updates:
```
question: "Found outdated sections. Which would you like to update?"
options: [list of sections]
allowMultiSelect: true
```

Sync with modular rules:

If rules exist in .claude/rules/
Detect duplicated content

Offer to deduplicate:

question: "Found duplicate content between CLAUDE.md and rules/. How to resolve?"
options:
  - "Keep in CLAUDE.md, remove from rules"
  - "Keep in rules, reference from CLAUDE.md"
  - "Keep both (may cause confusion)"

Update manifest:
- Record CLAUDE.md generation/update
- Track which PRDs contributed
- Update timestamp

Update task registry:

Update the task registry entry in docs/blueprint/manifest.json:

jq --arg now "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
  '.task_registry["claude-md"].last_completed_at = $now |
   .task_registry["claude-md"].last_result = "success" |
   .task_registry["claude-md"].stats.runs_total = ((.task_registry["claude-md"].stats.runs_total // 0) + 1)' \
  docs/blueprint/manifest.json > tmp.json && mv tmp.json docs/blueprint/manifest.json

Report:

✅ CLAUDE.md updated!

{Created | Updated}: CLAUDE.md
{If created:} CLAUDE.local.md (personal preferences, gitignored)

Sections:
- Overview ✅
- Tech Stack ✅
- Development Workflow ✅
- Architecture ✅
- Conventions ✅

@imports used: {count, if any}
- @docs/prds/architecture.md
- @.claude/rules/testing.md

Sources used:
- PRDs: {list}
- Rules: {list}
- Project detection: {what was detected}

{If modular mode:}
Note: Detailed rules are in .claude/rules/
CLAUDE.md serves as overview and quick reference.

Note: "Current Focus" and "Key Files" are managed by Claude's
auto memory — no need to maintain these in CLAUDE.md.

Run `/blueprint-status` to see full configuration.

CLAUDE.md Best Practices:

Keep it concise (< 500 lines ideally)
Focus on team-shared instructions (standards, commands, architecture)
Use @import to reference existing docs instead of duplicating content
Use CLAUDE.local.md for personal preferences (auto-gitignored)
Reference .claude/rules/ for detailed, path-specific rules
Let auto memory handle "Current Focus", "Key Files", debugging tips
Update when PRDs change significantly

Prompt for next action (use AskUserQuestion):

question: "CLAUDE.md updated. What would you like to do next?"
options:
  - label: "Check blueprint status (Recommended)"
    description: "Run /blueprint:status to verify configuration"
  - label: "Manage modular rules"
    description: "Add or edit rules in .claude/rules/"
  - label: "Continue development"
    description: "Run /project:continue to work on next task"
  - label: "I'm done for now"
    description: "Exit - CLAUDE.md is saved"

Based on selection:

"Check blueprint status" → Run /blueprint:status
"Manage modular rules" → Run /blueprint:rules
"Continue development" → Run /project:continue
"I'm done" → Exit

Template Sections (customize per project type):

| Project Type | Key Sections | |--------------|--------------| | Python | Virtual env, pytest, type hints | | Node.js | Package manager, test runner, build | | Rust | Cargo, clippy, unsafe usage rules | | Monorepo | Workspace structure, shared deps | | API | Endpoints, auth, error handling | | Frontend | Components, state, styling |

Agent Skills: Project: MyApp

Install this agent skill to your local

Skill Files

When to Use This Skill

CLAUDE.md vs Auto Memory

Memory Hierarchy (precedence low → high)

@import Syntax