Claude Setup Skill

Patterns and templates for creating optimized CLAUDE.md files that integrate project.md and brand.md context.

Workflow Integration

project.md (what) → brand.md (identity) → CLAUDE.md (how)

CLAUDE.md should:

• •Reference project.md for project overview
• •Reference brand.md for design guidelines
• •Focus on TECHNICAL configuration for Claude

Core Principles

1. Context-Aware Generation

• •Read project.md for project identity and goals
• •Read brand.md for design and voice guidelines
• •Focus CLAUDE.md on technical commands and patterns

2. Signal Over Noise

• •Only document non-obvious information
• •Avoid restating what's clear from code
• •Focus on gotchas, patterns, and decisions

3. Token Budget Awareness

4. Structured Sections

Use XML-style tags for parseability:

• •<ARCHITECTURE> - Technical architecture decisions
• •<CONVENTIONS> - Project-specific code patterns
• •<TOOLS> - MCP servers and preferences
• •<TESTING> - Test framework and patterns
• •<COMMANDS> - Quick reference table
• •<BRAND> - Quick reference from brand.md
• •<GOTCHAS> - Proven solutions to problems

CLAUDE.md Structure

# [Project Name]

[One-line description - from project.md or detected]

## Quick Reference

| Command | Description |
|---------|-------------|
| `[cmd]` | [purpose]   |

For project overview, see [project.md](project.md).
For brand guidelines, see [brand.md](brand.md).

<ARCHITECTURE>
## Architecture

[Technical architecture - patterns, layers, data flow]
[Reference project.md for project goals and features]
</ARCHITECTURE>

<CONVENTIONS>
## Conventions

### Naming
- [File naming pattern]
- [Class/function naming]

### Code Organization
- [Feature vs layer structure]
- [Import ordering]
</CONVENTIONS>

<TESTING>
## Testing

- **Framework**: [PHPUnit/Jest/Pest/etc.]
- **Run**: `[command]`
- **Coverage**: `[command]`

### Patterns
- [Test organization]
- [Mocking approach]
</TESTING>

<TOOLS>
## Available Tools

### Research
- `WebSearch` - Documentation lookup
- `mcp__context7__query-docs` - Framework docs

### Development
- `mcp__github__*` - Issue/PR management
- `Bash` - Build and test commands

### Tool Preferences
- [When to use which tool]
</TOOLS>

<BRAND>
## Design Guidelines

Reference: See [brand.md](brand.md) for full guidelines.

**Quick Reference:**
- Archetype: [From brand.md]
- Primary: [HEX from brand.md]
- Font: [From brand.md]
- Voice: [Key attributes from brand.md]
</BRAND>

<GOTCHAS>
## Gotchas

### [Issue Name]
**Problem**: [Description]
**Solution**: [Fix with file reference]
</GOTCHAS>

Context Integration

From project.md

Extract and use:

• •Project name: For CLAUDE.md header
• •Description: For one-line summary
• •Target audience: To calibrate technical detail level
• •Core features: To prioritize what to document

From brand.md

Extract and reference:

• •Archetype: For voice calibration in generated content
• •Primary color: For quick design reference
• •Font: For typography reference
• •Voice attributes: For documentation tone

In CLAUDE.md

• •Add references to project.md and brand.md
• •Include quick reference <BRAND> section
• •Don't duplicate full content from either file

Stack-Specific Patterns

See reference files for detailed templates:

• •references/stack-patterns.md - Laravel, Flutter, Vue patterns
• •references/claude-md-templates.md - Complete templates
• •references/rules-templates.md - Path-specific rules
• •references/mcp-catalog.md - MCP server and LSP recommendations

Smart Merge Strategy

When updating existing CLAUDE.md:

1. •Check context files - Read project.md and brand.md first
2. •Identify custom sections - Content not from templates
3. •Preserve custom content - Never delete user additions
4. •Add missing sections - Insert template sections that don't exist
5. •Add references - Link to project.md and brand.md
6. •Show diff - Always preview changes before applying

Quality Checklist

Before finalizing CLAUDE.md:

• • References project.md (if exists)
• • References brand.md (if exists)
• • Commands are copy-paste ready and tested
• • No obvious/redundant information
• • Architecture section explains WHY not just WHAT
• • Gotchas have concrete solutions
• • Token count within budget
• • All file paths verified
• • MCP tools documented if available
• • Uses XML section tags

Anti-Patterns to Avoid

1. •Duplicating project.md - Reference it, don't copy
2. •Duplicating brand.md - Reference it, don't copy
3. •Generic advice - "Write clean code" adds no value
4. •Obvious info - "This is a Laravel app" when composer.json exists
5. •Verbose explanations - One line per concept when possible
6. •Outdated commands - Verify all commands work
7. •No structure - Always use XML sections