ha-esphome-package-author

HA ESPHome Package Author

Spec: spec/claude/ha-esphome-package-author/en.md (EN canonical) / spec/claude/ha-esphome-package-author/de.md (DE translation). Grounding spec: spec/ha/esphome-project-structure/en.md §Package architecture, §Parameterisation, §Deviating without forking, §Remote packages.

Owns one shared package per invocation: how it is cut, what its parameter interface is, and how a deviating device consumes it without forking it.

Why this is a skill, not an agent

• Mid-flow approval is the contract (decisive): where the concern boundary runs, which variables become the package's public interface, and whether a deviation is an !extend or a new parameter are judgement calls the operator confirms — and each one is a breaking change for existing consumers if it is wrong.
• Quick, targeted change in the current context: one file under common/ plus the consuming device files, iterated in conversation.
• Counter-dimension considered: reading every consumer of the package before writing is a bounded fan-out that could be isolated (agent bias), but the resulting interface decision must be discussed, not reported; skill wins.

When this skill activates

The user wants shared ESPHome configuration to become or stay one well-cut package — "das gehört ins gemeinsame Package", "make the board package take a parameter for the update interval", "box-02 needs the base package without captive_portal".

When NOT to activate

• the repository tree, the initial base/board packages → ha-esphome-fleet-scaffold
• a block that belongs to exactly one device → ha-esphome-config-augment
• a new device file → ha-esphome-config-scaffold
• a read-only verdict across the whole package architecture → ha-esphome-fleet-reviewer
• compiling, flashing, or rolling out → the ESPHome toolchain / operator

Hard rules

1. Read the grounding spec, the package, and every consumer first. A package edit reaches every device that includes it; generating one from memory is how a fleet breaks silently.
2. One concern per package. A board package, a base package, a feature package — never a grab bag, and never a near-duplicate that differs from an existing package in one key.
3. Two occurrences make a parameter. One deviation is an exception resolved with !extend / !remove on the component's config id; the second identical override is promoted into the package as a defaulted variable. !extend never targets a package key — package keys are documentation only.
4. Every variable a package reads that not every consumer sets carries a defaults: entry. Adding a variable without a default is a breaking change for existing consumers, and this skill states that in the report.
5. id: on anything overridable. A component a device might extend or remove gets an explicit id:; otherwise the merge concatenates and the device ends up with two components.
6. State the merge consequences before writing. Dictionaries merge key-by-key, component lists merge by id, other lists concatenate, and every other value is replaced by the later one — the last clause is the one that silently lets a device scalar win.
7. Credentials stay !env_var, and no !secret enters a package that is or could become remote. !env_var is undocumented API and cannot interpolate substitutions in its name; new variables get documented in the same run.
8. Remote packages are pinned or vendored. A tag or commit, never a moving branch without a deliberate, documented refresh; prefer vendoring into common/.
9. Keep nesting shallow (device → board → base) and pass parameters in through substitutions rather than letting a package reach back into a consumer's secrets.
10. One package per run. No fleet-wide refactoring batches; validation is reported, never silently skipped.