ESPHome Encyclopedia

ESPHome configuration/component documentation-first workflow for ESPHome-specific questions, YAML/config authoring, config review, component selection, subst...

Security Scan

The skill's code, instructions, and required resources are consistent with a docs-first ESPHome helper: it only fetches official esphome.io pages and stores local caches/notes, and it requests no credentials or unusual system access.

Purpose & Capability

Name/description match the actual behavior: the scripts and SKILL.md implement a docs-first workflow, local cache layout, and workspace initialization. The included scripts (cache_doc.py and init_workspace.py) are directly related to caching official ESPHome docs and creating the .ESPHome-Encyclopedia workspace.

Instruction Scope

SKILL.md instructs the agent to consult and cache official docs and to inspect/configure ESPHome YAML and dashboards. This is appropriate for an ESPHome config helper, but it implies the agent may read workspace files (the .ESPHome-Encyclopedia tree) and any user-provided configs; ensure the agent is only given files you want it to see and that secrets are not stored in the cache or notes.

Install Mechanism

No install spec; scripts are included in the bundle and nothing is downloaded or executed at install time. The cache script does perform network fetches at runtime but restricts requests to https://esphome.io (see ALLOWED_NETLOCS) rather than arbitrary URLs.

Credentials

The skill requests no environment variables, credentials, or config paths. The only filesystem footprint is the .ESPHome-Encyclopedia workspace the skill creates/uses; users should avoid storing secrets (passwords, API keys, tokens) in those workspace files.

Persistence & Privilege

always is false and the skill does not attempt to modify system-wide agent settings. The provided init script creates a self-contained workspace under the user's current directory; this is a limited, proportionate level of persistence.

Assessment

This skill appears to do exactly what it says: fetch and cache official ESPHome docs and help with ESPHome YAML/config work. It does not request credentials and only fetches from esphome.io. Before installing or running: (1) avoid putting credentials or sensitive tokens into the .ESPHome-Encyclopedia notes or inventory files (the skill encourages storing 'access' and 'dashboard' notes which could be sensitive), (2) only provide the agent with the specific device/config files needed for a task (don't let it read arbitrary system files), and (3) review any cached files you create to ensure they don't contain secrets. If you need higher assurance, inspect the two scripts (cache_doc.py and init_workspace.py) yourself — they are short, constrained, and only allow https://esphome.io requests by design.

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.