hassio-addons: Skill for Claude Code

Home Assistant add-on workflow

Answer style. Chat replies are terse — no pleasantries, tool-call narration, decorative tables, emoji or dumped logs; quote the shortest decisive line and don't re-print what is already in context. Telegraphic fragments are fine there. Two things outrank brevity, because dropping a word from either changes the meaning rather than shortening it: never compress uncertainty markers ("likely", "assumed", "not verified"), negations, numbers, units, technical terms, code or error strings — step 9's Verified/Checked/Assumed distinction wins every time; and write full prose wherever a fragment could be read two ways — security warnings, irreversible-action confirmations, multi-step sequences, and everything persisted (commits, CHANGELOG entries, PR bodies, review-thread replies, the step 10 report).

Triage first, then one of two paths:

• Light — typo/doc fixes, CHANGELOG edits, version bumps, one-file edits at ladder levels 1-3 (below), simple questions: scope → implement → validate (step 4) → PR (version bump + CHANGELOG still required) → resolve bot comments.
• Full loop — performance/RAM/CPU work, diagnosis, anything changing a shipped default, ladder levels 4-6, or an explicit Codex-check request: scope → measure → plan → Codex reviews the plan → implement → simplify → Codex reviews the code → simplify again → PR → resolve comments → verify in production → report.

Before implementing, on either path, ask yourself the proportionality question and answer it in the plan (a one-line plan, for a light task) — in writing, naming the smaller version you rejected and why:

What is the smallest thing that solves this? What would you delete from what I just proposed? If it had to be written in ten lines, in the idiom of the code it sits beside, what would be lost — and is any of that a case I have actually demonstrated?

Escalate mid-flight if a light task grows — touches a default, needs a new script or service, reveals a deeper problem, or turns out to need more than the one file once you have honestly answered that question. A light task never skips it; it skips Codex only while the answer stays inside one file. Adding a new file or a new mechanism puts it on the full loop, however small the diff looks — a version bump and its CHANGELOG entry are release bookkeeping, not a new file for this purpose, and never trigger it on their own.

Standing rule: ship the simplest solution that works, and build it out of what already exists — a .templates/ module, an existing cont-init script, the pattern a sibling add-on already uses for the same problem. 120+ add-ons are maintained by one person: a homogeneous repo where every add-on solves a problem the same way is worth more than a locally nicer bespoke design. Prefer reusing or extending over adding a parallel implementation, and when you must add something new, spell it the way the rest of the repo spells it (naming, option names, script numbering, file layout). Complexity is bought only by a measurement showing a concrete, user-visible cost on a real host — never by reasoning about hypothetical performance, and never by reasoning about a hypothetical host either. A defensive branch is complexity like any other: name the input that reaches it and the image or host where that happens, or delete it and let the case fail visibly instead.

Skill root. The canonical copy lives at .claude/skills/hassio-addon-workflow/. Set it once; every scripts/… and references/… path below is relative to it:

SKILL="$(git rev-parse --show-toplevel)/.claude/skills/hassio-addon-workflow"
bash "$SKILL/scripts/preflight.sh"        # and likewise for the other scripts

Non-negotiables:

• Docker build cannot be tested locally (no dockerd) — CI is the only gate.
• Never git stash under /data/claude — refs/stash is shared across worktrees.
• Work in a worktree under /data, not /tmp (/tmp is noexec).