CLAUDE.md

1# CLAUDE.md
2 
3This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4 
5## Repository Overview
6 
7This is a best practices repository for Claude Code configuration, demonstrating patterns for skills, subagents, hooks, and commands. It serves as a reference implementation rather than an application codebase.
8 
9## Key Components
10 
11### Weather System (Example Workflow)
12A demonstration of two distinct skill patterns via the **Command → Agent → Skill** architecture:
13- `/weather-orchestrator` command (`.claude/commands/weather-orchestrator.md`): Entry point — asks user for C/F, invokes agent, then invokes SVG skill
14- `weather-agent` agent (`.claude/agents/weather-agent.md`): Fetches temperature using its preloaded `weather-fetcher` skill (agent skill pattern)
15- `weather-fetcher` skill (`.claude/skills/weather-fetcher/SKILL.md`): Preloaded into agent — instructions for fetching temperature from wttr.in API
16- `weather-svg-creator` skill (`.claude/skills/weather-svg-creator/SKILL.md`): Skill — creates SVG weather card, writes `orchestration-workflow/weather.svg` and `orchestration-workflow/output.md`
17 
18Two skill patterns: agent skills (preloaded via `skills:` field) vs skills (invoked via `Skill` tool). See `orchestration-workflow/orchestration-workflow.md` for the complete flow diagram.
19 
20### Skill Definition Structure
21Skills in `.claude/skills/<name>/SKILL.md` use YAML frontmatter:
22- `name`: Display name and `/slash-command` (defaults to directory name)
23- `description`: When to invoke (recommended for auto-discovery)
24- `argument-hint`: Autocomplete hint (e.g., `[issue-number]`)
25- `disable-model-invocation`: Set `true` to prevent automatic invocation
26- `user-invocable`: Set `false` to hide from `/` menu (background knowledge only)
27- `allowed-tools`: Tools allowed without permission prompts when skill is active
28- `model`: Model to use when skill is active
29- `context`: Set to `fork` to run in isolated subagent context
30- `agent`: Subagent type for `context: fork` (default: `general-purpose`)
31- `hooks`: Lifecycle hooks scoped to this skill
32 
33### Presentation System
34Any request to update, modify, or fix the presentation (`presentation/index.html`) must be handled by the `presentation-curator` agent (`.claude/agents/presentation-curator.md`). Always delegate presentation work to this agent via the Task tool — never edit the presentation directly.
35 
36The agent is **self-evolving**: after every execution, it updates its own skills to stay in sync with the presentation. It has three preloaded skills:
37- `vibe-to-agentic-framework`: The conceptual framework ("Vibe Coding → Agentic Engineering"), weight rationale, and journey narrative. Updated after every slide change.
38- `presentation-structure`: Slide format, weight system, navigation, section ranges. Updated when slides are added/removed/reordered.
39- `presentation-styling`: CSS classes, component patterns, syntax highlighting. Updated when new styling patterns are introduced.
40 
41### Hooks System
42Cross-platform sound notification system in `.claude/hooks/`:
43- `scripts/hooks.py`: Main handler for Claude Code hook events
44- `config/hooks-config.json`: Shared team configuration
45- `config/hooks-config.local.json`: Personal overrides (git-ignored)
46- `sounds/`: Audio files organized by hook event (generated via ElevenLabs TTS)
47 
48Hook events configured in `.claude/settings.json`: PreToolUse, PostToolUse, UserPromptSubmit, Notification, Stop, SubagentStart, SubagentStop, PreCompact, SessionStart, SessionEnd, Setup, PermissionRequest, TeammateIdle, TaskCompleted, ConfigChange.
49 
50Special handling: git commits trigger `pretooluse-git-committing` sound.
51 
52## Critical Patterns
53 
54### Subagent Orchestration
55Subagents **cannot** invoke other subagents via bash commands. Use the Task tool:
56```
57Task(subagent_type="agent-name", description="...", prompt="...", model="haiku")
58```
59 
60Be explicit about tool usage in subagent definitions. Avoid vague terms like "launch" that could be misinterpreted as bash commands.
61 
62### Subagent Definition Structure
63Subagents in `.claude/agents/*.md` use YAML frontmatter:
64- `name`: Subagent identifier
65- `description`: When to invoke (use "PROACTIVELY" for auto-invocation)
66- `tools`: Comma-separated allowlist of tools (inherits all if omitted). Supports `Task(agent_type)` syntax
67- `disallowedTools`: Tools to deny, removed from inherited or specified list
68- `model`: Model alias: `haiku`, `sonnet`, `opus`, or `inherit` (default: `inherit`)
69- `permissionMode`: Permission mode (e.g., `"acceptEdits"`, `"plan"`, `"bypassPermissions"`)
70- `maxTurns`: Maximum agentic turns before the subagent stops
71- `skills`: List of skill names to preload into agent context
72- `mcpServers`: MCP servers for this subagent (server names or inline configs)
73- `hooks`: Lifecycle hooks scoped to this subagent (`PreToolUse`, `PostToolUse`, `Stop`)
74- `memory`: Persistent memory scope — `user`, `project`, or `local` (see `reports/claude-agent-memory.md`)
75- `background`: Set to `true` to always run as a background task
76- `isolation`: Set to `"worktree"` to run in a temporary git worktree
77- `color`: CLI output color for visual distinction
78 
79### Configuration Hierarchy
801. `.claude/settings.local.json`: Personal settings (git-ignored)
812. `.claude/settings.json`: Team-shared settings
823. `hooks-config.local.json` overrides `hooks-config.json`
83 
84### Disable Hooks
85Set `"disableAllHooks": true` in `.claude/settings.local.json`, or disable individual hooks in `hooks-config.json`.
86 
87## Workflow Best Practices
88 
89From experience with this repository:
90 
91- Keep CLAUDE.md under 200 lines per file for reliable adherence
92- Use commands for workflows instead of standalone agents
93- Create feature-specific subagents with skills (progressive disclosure) rather than general-purpose agents
94- Perform manual `/compact` at ~50% context usage
95- Start with plan mode for complex tasks
96- Use human-gated task list workflow for multi-step tasks
97- Break subtasks small enough to complete in under 50% context
98 
99### Debugging Tips
100 
101- Use `/doctor` for diagnostics
102- Run long-running terminal commands as background tasks for better log visibility
103- Use browser automation MCPs (Claude in Chrome, Playwright, Chrome DevTools) for Claude to inspect console logs
104- Provide screenshots when reporting visual issues
105 
106## Documentation
107 
108- `docs/AGENTS.md`: Subagent orchestration troubleshooting
109- `orchestration-workflow/orchestration-workflow.md`: Weather system flow diagram
110- `docs/COMPARISION.md`: Commands vs Agents vs Skills invocation patterns
111 
112## Reports
113 
114- `reports/claude-in-chrome-v-chrome-devtools-mcp.md`: Browser automation MCP comparison (Playwright vs Chrome DevTools vs Claude in Chrome)
115- `best-practice/claude-memory.md`: CLAUDE.md loading behavior in monorepos (ancestor vs descendant loading)
116- `reports/claude-skills-for-larger-mono-repos.md`: Skills discovery and loading behavior in monorepos (static vs dynamic discovery)
117- `reports/claude-agent-memory.md`: Agent memory frontmatter — persistent memory scopes (user, project, local) for subagents
118- `reports/claude-advanced-tool-use.md`: Advanced tool use patterns — Programmatic Tool Calling (PTC), Tool Search, Tool Use Examples
119- `reports/claude-usage-and-rate-limits.md`: Usage commands (`/usage`, `/extra-usage`, `/cost`), rate limits, and pay-as-you-go overflow billing
120