Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Built-in Prompts

In addition to tools and resources, espctl ships prompts — ready-made conversation starters your assistant can use to handle common situations. Prompts are for when “the right way to ask” is easier than describing it from scratch.

There are eight built-in prompts.

PromptArgument(s)What it does
setup-mcp-clientclient (one of claude-code, cursor, claude-desktop, codex, opencode)Step-by-step guide for setting up espctl in a specific AI tool, with the local espctl path filled in.
diagnose-build-errorerror_log (string)Walks through a build failure: what’s wrong, why, and how to fix it. Takes raw compiler output and returns a structured explanation.
diagnose-cmake-errorerror_log (string)Same idea as the previous one, but tuned for CMake-specific failures (target not found, generator expression invalid, missing find_package, etc.).
migrate-idf-versionfrom_version, to_versionWalks you through moving between IDF versions. Lists known breaking changes, deprecated APIs, and sdkconfig updates.
configure-project(none)Walks you through setting up a fresh project — chip, IDF version, components, optional features.
setup-ble-matter(none)Adds BLE + Matter components to your current project, including the necessary idf_component.yml entries and sdkconfig.defaults overrides.
convert-to-component(none)Turns a standalone ESP-IDF project into a reusable IDF component that other projects can depend on.
optimize-flash-size(none)Tips for shrinking firmware flash usage — log level changes, dead-code removal, partition table tuning, removing unused components.

How to use a prompt

The exact syntax depends on your AI tool. Plain English usually works:

Use the setup-mcp-client prompt for opencode.

…or, more explicitly:

Run the diagnose-build-error prompt with error_log set to the contents of build://log/0abf...e2.

Your AI tool asks espctl for the prompt, which returns a ready-made conversation that the AI tool then continues from. You don’t see the mechanics — to you, it just feels like your assistant picked up where the prompt left off.

Why prompts exist

Tools and resources cover what your assistant can do. Prompts cover how to ask in a way that gets consistent results. They’re especially useful for:

  • Getting started (setup-mcp-client, configure-project) — your assistant walks you through setup without you having to know what to ask first.
  • Recovering from failures (diagnose-build-error, diagnose-cmake-error) — your assistant gives you the same structured analysis every time, no matter how messy the underlying log.
  • Multi-step refactors (migrate-idf-version, convert-to-component) — the prompt encodes the expert knowledge so your assistant doesn’t have to figure it out from scratch.

Examples

“Help me set up Cursor”

Use the setup-mcp-client prompt for cursor.

Your assistant will:

  1. Read install://cursor to get a snippet pre-filled for your machine.
  2. Walk you through editing .cursor/mcp.json.
  3. Suggest verification steps.
  4. Offer to run doctor once you restart Cursor.

“My build failed, help”

Read build://log/latest, then run diagnose-build-error against it.

Your assistant will:

  1. Pull the log.
  2. Call parse_build_errors to extract structured error messages.
  3. Run the diagnose-build-error prompt with the structured output.
  4. Tell you: what failed, why, exactly which lines to change, and (if possible) a one-line patch suggestion.

“I’m migrating from v5.2 to v5.3”

Run migrate-idf-version from v5.2.2 to v5.3.1.

Your assistant returns a checklist: breaking changes, deprecated APIs you’re using, sdkconfig keys that moved or were removed, and component versions that need updating.

See also