Assignment steps#
In this assignment, you will add reusable skills and persistent agent instructions to an ESP-IDF project. You will then verify that the agent can use the project context and the Espressif Documentation MCP server.
Use an existing ESP-IDF project, such as the project created while completing the preliminary setup. These files are project-specific, so add or adapt them whenever you start another project.
Step 1: Add skills to your project#
Skills are reusable instruction sets for the agent: recipes it can follow for tasks such as creating a component, running validation, or generating documentation.
Run the following commands from your project root:
ESP-IDF
npx skills add pedrominatel/awesome-esp-ai@esp-idfESP-IDF components
npx skills add pedrominatel/awesome-esp-ai@esp-idf-componentsStep 2: Add AGENTS.md to your project#
AGENTS.md gives the agent persistent project instructions. Supported agents load it automatically, so you do not have to repeat the target SoC, ESP-IDF version, or coding conventions in every prompt.
Create AGENTS.md in your project root with at least the following:
# ESP-IDF Agent Instructions
This file is a reusable baseline for coding agents working in ESP-IDF application
and component repositories. Follow more specific instructions in the target
repository when they override this baseline.
## Discover the Project First
- Locate the ESP-IDF project root before running commands. A project root normally
contains a top-level `CMakeLists.txt` with a `project(...)` call.
- In repositories with multiple applications or test apps, identify the affected
project roots and run commands from each relevant root.
- Read the repository README, CI configuration, top-level `CMakeLists.txt`,
`sdkconfig.defaults*`, component manifests, partition tables, and existing build
scripts before choosing commands.
- Determine the required ESP-IDF version, supported targets, board assumptions,
and project-specific validation commands. Prefer repository and CI commands over
generic commands in this file.
- If no project is present, do not create a scaffold unless the user requested a
new project or the task clearly requires one.
- When a new project scaffold is required, use
`idf.py create-project <PROJECT_NAME>` instead of manually generating the
boilerplate files.
## Environment and Documentation
- Ensure the correct ESP-IDF environment is active before using `idf.py`.
- Prefer EIM CLI for installing and selecting ESP-IDF versions when the repository
does not prescribe another setup. Use these commands as needed:
- Verify EIM is available: `eim --version`
- List installed ESP-IDF versions, their absolute installation paths, and the
selected version: `eim list`
- Select an installed version: `eim select <ESP_IDF_VERSION>`
- Run with the selected version: `eim run "idf.py <command>"`
- Run with a specific version without changing the selection:
`eim run "idf.py <command>" <ESP_IDF_VERSION>`
- Verify a specific ESP-IDF environment before building:
`eim run "idf.py --version" <ESP_IDF_VERSION>`
- Install a missing version when authorized:
`eim install -i <ESP_IDF_VERSION>`
- Open the interactive installer when requested: `eim wizard`
- Use the installation path reported by `eim list` when a task needs `IDF_PATH`
or direct access to a matching ESP-IDF checkout. Do not guess installation
paths.
- If the environment is sourced directly, verify that `idf.py --version` matches
the version required by the project.
- Prefer `idf.py` workflows over invoking CMake or Ninja directly.
- Use ESP-IDF documentation and migration guides matching the project's version
and target. Do not rely on `latest` documentation for version-sensitive APIs.
## Standard Commands
- Reconfigure: `idf.py reconfigure`
- Build: `idf.py build`
- Select target: `idf.py set-target <TARGET>`
- Flash: `idf.py -p <PORT> flash`
- Monitor: `idf.py -p <PORT> monitor`
- Flash and monitor: `idf.py -p <PORT> flash monitor`
`idf.py set-target` already clears the build directory, moves the previous
`sdkconfig` to `sdkconfig.old`, and reconfigures the project. Ask the user before
running it because it replaces configuration and build state. Do not run a
redundant `idf.py fullclean` afterward. Use `fullclean` only when stale artifacts
are a demonstrated problem, and ask before deleting build state.
## Configuration and Generated Files
- Treat `sdkconfig` as generated configuration. Do not edit it directly unless the
user explicitly requests that exact file.
- Store intentional project defaults in `sdkconfig.defaults` and target-specific
overrides in files such as `sdkconfig.defaults.esp32c6`. Keep changes minimal,
then ask the user whether to run `idf.py reconfigure`.
- A target-specific defaults file is used only when the base
`sdkconfig.defaults` file also exists; create an empty base file when no common
defaults are needed.
- `Kconfig` and `Kconfig.projbuild` define configuration symbols, prompts,
dependencies, and defaults. They do not store the project's selected values.
- Use component `Kconfig` for component-local options. Use `Kconfig.projbuild`
only when an option must appear at project scope.
- Namespace new symbols, provide a prompt, a sensible default, and useful help
text. Put configurable hardware assignments such as GPIOs in Kconfig instead
of hardcoding them.
- After changing `Kconfig` or `Kconfig.projbuild`, ask the user whether to run
`idf.py reconfigure` before the next build or validation step.
- `idf.py build` normally detects Kconfig definition changes and invokes CMake
reconfiguration automatically. An explicit `idf.py reconfigure` remains useful
for validating configuration separately before a build.
- Changing a Kconfig default does not necessarily replace a value already stored
in `sdkconfig`. When the project's selected value must change, update the
appropriate `sdkconfig.defaults*` file and reconfigure with user approval.
- Never edit files under `build/` or `managed_components/`.
- Never edit `dependencies.lock` manually. Allow Component Manager to regenerate
it, and commit the resulting lock file when the application repository tracks
managed dependencies for reproducible builds.
## Components and Code Conventions
- Before implementing a dependency, search the ESP Component Registry and inspect
existing `idf_component.yml` manifests. Prefer adding a suitable managed
dependency over duplicating it locally.
- Add a managed dependency with
`idf.py add-dependency "namespace/component^<VERSION>"`. From the project root,
this updates the `main` component by default. Use `--component=<NAME>` for a
component under `components/` or `--path=<PATH>` for another component
directory.
- Prefer `idf.py create-component <name>` when creating a project-local component.
Keep public headers in `include/`, register sources with
`idf_component_register(...)`, and declare dependencies explicitly with
`REQUIRES` or `PRIV_REQUIRES`.
- Keep reusable functionality in components rather than a monolithic application.
A component intended for publication should be self-contained, documented,
licensed, versioned, and tested in one or more test applications.
- Keep the firmware entry point as `void app_main(void)`.
- Prefer ESP-IDF APIs and `ESP_LOGI/W/E` for application logging. Handle
`esp_err_t` results explicitly and avoid long blocking operations without
yielding where appropriate.
## Validation
- Match validation to the change and follow the repository's CI matrix:
- documentation-only changes: run relevant documentation checks
- Kconfig changes: ask whether to run `idf.py reconfigure`
- manifest or build-system changes: run `idf.py reconfigure`
- firmware changes: build every affected supported target that is practical
- component changes: build or test the component's relevant test applications
- Use host-based tests before hardware tests when both cover the behavior.
- Do not flash merely because a serial device is connected. Flash only when the
user requested it or explicitly authorized hardware validation.
- Before flashing, confirm the port, target, and that the device is safe to
overwrite. Never assume a port or monitor baud rate.
- When authorized hardware validation is required, use the project's documented
command, normally `idf.py -p <PORT> flash monitor`, and capture the relevant
runtime output.
- Report the exact commands, ESP-IDF version, target, and tests run. Summarize
configuration changes and clearly state anything not validated.
## Safety and Collaboration
- Keep changes narrowly scoped. If unrelated workspace changes appear, stop and
ask how to proceed.
- Ask before destructive actions such as `fullclean`, deleting files, erasing
flash, changing eFuses, or broadly regenerating configuration.
- Do not commit build outputs, transient logs, generated binaries, or
`managed_components/` unless the repository explicitly requires them.
- Never hardcode or commit SSIDs, passwords, API keys, certificates, private
keys, tokens, or device secrets. Use placeholders, configuration, environment
variables, or secure provisioning.
- Review partition size and OTA/rollback implications when changes affect
application size, partition tables, or update behavior.
## Specialized Guidance
When these files are present, use the relevant workflow:
- Firmware development: `skills/esp-idf/SKILL.md`
- Component creation and publication:
`skills/esp-idf-components/SKILL.md`
- ESP-IDF 5.x to 6.0 migration:
`skills/esp-idf-v6-migration/SKILL.md`Update this file as your project evolves. If you change the target SoC or add new conventions, keep AGENTS.md in sync: it is the single source of truth for the agent.
Step 3: Verify the setup#
- Open the configured project folder in Cursor or VS Code.
- Open the AI chat panel and ask:
Which ESP-IDF version and target does this project use?
Use the project files and Espressif documentation, and identify the sources
for your answer.- Confirm that the agent reads the project context and can use the Espressif Documentation MCP server. If the project does not yet specify a version or target, the agent should say so instead of guessing.
- Ask the agent to list the ESP-IDF skills available in the project and briefly describe when it would use each one.
You are now ready to use persistent rules, reusable skills, and current Espressif documentation in an ESP-IDF project.
Next step#
Lecture 1: What you should know about ESP-IDF to work effectively with AI agents