SKILL.md
Task
Generate or update a CLAUDE.md for the project at $1 (relative path under packages/<domain>/).
Process
- Read the project source to understand its internals:
- main/.c, main/.h — all source files, pin defines, task structure - main/CMakeLists.txt — REQUIRES list - sdkconfig.defaults — target, features, stack sizes - justfile — build/flash/monitor recipes and their exact names - README.md — existing description - WIRING.md — hardware details - Kconfig.projbuild — configurable options - components/ — local components - idfcomponent.yml or managedcomponents/ — external dependencies
- Generate CLAUDE.md following the template below
Template
Model after the best existing examples: audiobook-player/CLAUDE.md (181 lines) and xbox-switch-bridge/CLAUDE.md (125 lines).
# CLAUDE.md
This file provides guidance to Claude Code when working with this project.
## Project Overview
<What this project does, target hardware, current status.>
## Build Commands
### Using justfile
just build # Build firmware (containerized) just flash # Flash to device just monitor # Serial monitor just develop # Build + flash + monitor just clean # Remove build artifacts
<Include ALL recipes from the project's justfile with descriptions.>
## Critical Hardware Notes
### GPIO Pin Constraints
<Board-specific pin reservations, strapping pins, bus contention issues.>
<Only include if there ARE constraints — omit for simple projects.>
### Power Considerations
<Only if non-trivial: battery, deep sleep, current requirements.>
## Architecture
<How the firmware is structured: main loop vs FreeRTOS tasks, state machine, communication flow.>
<Include component/module descriptions for multi-file projects.>
## Common Development Tasks
### <Task 1>
<Steps for the most common development workflow.>
### Troubleshooting
<Only include if there are non-obvious failure modes.>Style Rules
- Target 80-150 lines — enough detail for Claude to work effectively, not a tutorial
- Build commands must be accurate — read the actual justfile, don't guess recipe names
- Pin constraints only when real — omit the section for simple projects
- Architecture section scales with complexity — 2 lines for a single-file project, a component table for complex ones
- No generic ESP-IDF advice — only project-specific information
- Include credential handling if the project uses WiFi/API keys (where to create credentials.h, what values to set)