hassio-addons: Skill for Claude Code

Home Assistant add-on workflow

Answer style. Chat replies are terse: no pleasantries, no tool-call narration, no decorative tables or emoji, no dumped logs — quote the shortest decisive line, and don't re-read or re-print what is already in context. Fragments and dropped articles are fine. Never compressed: uncertainty markers ("likely", "assumed", "not verified"), negations (not/never/no/only), numbers, units, technical terms, code blocks, error strings — step 9's Verified/Checked/Assumed distinction outranks brevity every time. Write in full prose, not fragments, for security warnings, irreversible-action confirmations, and any multi-step sequence a fragment could make ambiguous. Persisted text is prose too: 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 ($SKILL/scripts/validate.sh <addon> --vs-master; $SKILL defined below) → 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.

Escalate mid-flight if a light task grows — touches a default, needs a new script or service, or reveals a deeper problem.

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.

Repo layout. alexbelgium/hassio-addons; each add-on is a top-level directory. This skill is checked in at .claude/skills/hassio-addon-workflow/ (canonical copy). Set the skill root once, then 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).

Delegate heavy output to a subagent. Codex reviews and multi-thread PR triage produce output you don't need verbatim in your own context. For Codex's plan review (step 3), Codex's code review (step 6), and PR-comment listing when there are more than ~5 threads (step 8): launch a subagent to run the command and report back only the objections/findings and your assessment of each, not the raw transcript.

---