ESPHome Encyclopedia#

Overview#

Use a docs-first workflow for ESPHome work. Prefer the official ESPHome component documentation index at https://esphome.io/components/, consult cached local copies under .ESPHome-Encyclopedia/ before re-fetching, and record useful official-doc excerpts plus environment-specific operational learnings so future work gets faster and safer.

This skill is for the ESPHome config/component layer: node YAML, dashboard/node operations, and ESPHome-specific component semantics. It should not trigger for generic YAML editing, generic Home Assistant work, or general embedded programming unless ESPHome is truly the thing being discussed.

Workflow#

1. Classify the task
   • Decide whether the task is an ESPHome question, YAML authoring task, config review, component-selection task, troubleshooting task, or live dashboard/node task.
   • Use this skill when the task materially depends on ESPHome syntax, component semantics, supported options, build/runtime behavior, dashboard behavior, or node operations.
   • Do not use this skill for generic YAML editing, generic microcontroller work, generic Home Assistant automation, or Arduino/C++ questions unless the ESPHome layer is actually in play.
2. Check local cache first
   • Use .ESPHome-Encyclopedia/ as the local knowledge/cache root.
   • Check these locations first when relevant:
     • .ESPHome-Encyclopedia/docs/esphome.io/...
     • .ESPHome-Encyclopedia/notes/devices/...
     • .ESPHome-Encyclopedia/notes/components/...
     • .ESPHome-Encyclopedia/notes/patterns/...
     • .ESPHome-Encyclopedia/inventory/...
   • If a cached page or note already answers the question well enough, use it.
3. Consult official ESPHome docs before answering or touching configs/nodes
   • Before answering direct or indirect ESPHome questions that depend on YAML syntax, component behavior, version-sensitive options, dashboard behavior, OTA/update expectations, or pin/component constraints, consult the official docs unless the answer is already well-supported by the local cache.
   • When working on ESPHome YAML, look up the docs for the exact individual components/sections in play instead of relying only on general ESPHome knowledge. If a config touches sensor, binary_sensor, switch, light, output, display, climate, cover, wifi, api, ota, logger, web_server, packages, substitutions, or board/platform sections, check those exact component pages so the latest supported options and nesting are used.
   • Before performing direct ESPHome configuration or dashboard/node work, consult the relevant docs first when:
     • exact option names or nesting matter
     • component behavior is easy to misremember
     • the action could affect device availability, flashing, Wi-Fi reachability, sensors, relays, pins, or OTA updates
   • Do not improvise fragile ESPHome YAML from memory when the docs are easy to check.
4. Cache consulted docs locally
   • When you consult an ESPHome docs page, save a normalized cache copy under .ESPHome-Encyclopedia/docs/esphome.io/....
   • Mirror the official path structure as much as practical.
   • Cache only pages actually consulted; do not try to mirror the whole docs site eagerly.
   • Use scripts/cache_doc.py when appropriate.
5. Separate official documentation from local observations
   • Store official-doc-derived material under .ESPHome-Encyclopedia/docs/....
   • Store environment-specific operational knowledge under:
     • .ESPHome-Encyclopedia/notes/devices/
     • .ESPHome-Encyclopedia/notes/components/
     • .ESPHome-Encyclopedia/notes/patterns/
     • .ESPHome-Encyclopedia/inventory/
   • Distinguish clearly between:
     • official documented behavior
     • observed local configuration/state
     • inferred best-practice guidance
6. Record useful local learnings
   • After useful live work, save durable notes such as:
     • device names and roles
     • dashboard access paths
     • repeated YAML patterns
     • board/framework gotchas
     • pin mappings and hardware quirks
     • OTA/build trouble patterns
     • safe/unsafe operational boundaries for the environment
   • Prefer concise durable notes over re-learning the same ESPHome details later.

Live Work Rules#

• Treat official docs lookup as the default preflight for non-trivial ESPHome work.
• Prefer read/inspect first when entering an ESPHome dashboard, config set, or node you have not recently reviewed.
• Treat pin changes, framework changes, package/substitution refactors, OTA/update actions, and anything that could make a node unreachable as higher-sensitivity areas.
• When uncertainty remains after checking cache + docs, say so and avoid bluffing.
• When answering a question, mention when useful whether the answer comes from cached official docs, a fresh official docs lookup, or live observed environment state.

Data Root#

Use this workspace-local root for cache and notes:

• .ESPHome-Encyclopedia/

Expected structure:

• .ESPHome-Encyclopedia/docs/esphome.io/...
• .ESPHome-Encyclopedia/notes/devices/...
• .ESPHome-Encyclopedia/notes/components/...
• .ESPHome-Encyclopedia/notes/patterns/...
• .ESPHome-Encyclopedia/inventory/...

Use scripts/init_workspace.py to create or repair the expected directory structure.

Note Destinations#

• Device-specific observations → .ESPHome-Encyclopedia/notes/devices/<device-name>.md
• Component-specific observations → .ESPHome-Encyclopedia/notes/components/<component-name>.md
• Reusable ESPHome patterns/gotchas → .ESPHome-Encyclopedia/notes/patterns/<topic>.md
• Environment-wide dashboard/access inventories → .ESPHome-Encyclopedia/inventory/*.md
• Cached official docs → .ESPHome-Encyclopedia/docs/esphome.io/...

Secrets / Sensitive Data#

• Do not store plaintext credentials, API keys, session tokens, private URLs, recovery codes, or other secrets in the encyclopedia notes/inventory tree.
• If a note needs to mention access details, keep it high-level and redact or omit secret material.
• Treat these workspace notes as operational memory, not as a secrets vault.

Resources#

• scripts/init_workspace.py — create or repair the .ESPHome-Encyclopedia/ directory tree.
• scripts/cache_doc.py — fetch and cache an official ESPHome docs page under .ESPHome-Encyclopedia/docs/....
• references/workflow.md — detailed operating workflow and evidence-handling rules.
• references/cache-layout.md — canonical .ESPHome-Encyclopedia/ directory structure.
• references/topic-map.md — useful ESPHome topic groupings for faster official-doc lookup.

Good Outcomes#

• Answer an ESPHome question using cached or freshly checked official docs instead of guesswork.
• Inspect a live ESPHome dashboard/config set after checking the relevant docs and record any new local device/config knowledge.
• Build a growing local ESPHome knowledge cache that makes later work faster, safer, and more grounded.
• Turn one-off ESPHome discoveries into durable notes so future work does not rediscover them from scratch.

Avoid#

• Answering ESPHome-specific questions purely from memory when docs are easy to consult.
• Treating local observed node behavior as if it were guaranteed official documented behavior.
• Dumping large amounts of low-value docs into the workspace without a reason.
• Writing device-specific observations into the official-doc cache tree.
• Making device-impacting config or OTA changes before checking the relevant docs when exact behavior matters.