The .claude Directory¶

The .claude/ directory is Claude Code's native project directory. Samuel uses it to store skills that extend AI capabilities.

Overview¶

While CLAUDE.md provides universal guardrails, .claude/ stores skills specific to YOUR project:

.claude/
├── skills/                # Agent Skills (language guides, frameworks, workflows)
│   ├── README.md
│   ├── typescript-guide/  # 21 language guide skills
│   │   ├── SKILL.md
│   │   └── references/
│   ├── react/             # 33 framework skills
│   │   ├── SKILL.md
│   │   └── references/
│   ├── create-prd/        # 23 workflow skills
│   │   └── SKILL.md
│   ├── auto/              # Autonomous loop skill
│   │   └── SKILL.md
│   └── ... (more skills)
├── auto/                  # Autonomous loop state (generated)
│   ├── prd.json           # Machine-readable task state
│   ├── progress.md       # Append-only learnings journal
│   ├── prompt.md          # Iteration prompt template
│   └── discovery-prompt.md # Discovery prompt (pilot mode)
└── settings.local.json    # Claude Code local settings

What's Inside¶

Skills¶

Skills are capability modules following the Agent Skills standard:

Per-Folder CLAUDE.md Files¶

Samuel creates stub CLAUDE.md files in existing project directories during samuel init. These are loaded automatically when AI works in that directory. Customize them with folder-specific instructions, conventions, and constraints.

Language Guide Skills¶

Auto-loaded based on file extensions you're working with (21 languages):

No manual selection needed - AI detects automatically.

Language Guides

Framework Skills¶

On-demand framework-specific patterns (33 framework skills across 11 language families):

How to load: Reference the framework or work in a project that uses it.

Framework Guides

Workflows¶

On-demand workflows for structured tasks:

How to invoke:

@.claude/skills/create-prd/SKILL.md

Workflows

Loading Protocol¶

AI follows this protocol when starting a session:

1. Load CLAUDE.md (always)
   ↓
2. Load per-folder CLAUDE.md (when working in a subdirectory)
   ↓
3. Auto-load language guide based on file extensions
   ↓
4. On-demand: Load workflow or framework skills as needed

Git Configuration¶

What to Commit¶

CLAUDE.md
AGENTS.md
.claude/skills/               # Language guides, frameworks, and workflows
Per-folder CLAUDE.md files     # Folder-specific instructions

What to Gitignore¶

# Claude Code local settings
.claude/settings.local.json

Best Practices¶

Do¶

• Customize per-folder CLAUDE.md files with specific instructions
• Create custom skills for recurring project tasks
• Use samuel skill create to scaffold new skills

Don't¶

• Manually edit language guide skills (they're templates, use samuel update)
• Over-organize the directory
• Put secrets or credentials in CLAUDE.md files

Related¶