hacs
Use when browsing, installing, version-pinning or downgrading, redownloading, or removing HACS packages, adding custom HACS repositories, or migrating to a custom integration through HA NOVA Relay.
markusleben · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add markusleben/ha-nova --skill hacs技能说明
name: hacs description: Use when browsing, installing, version-pinning or downgrading, redownloading, or removing HACS packages, adding custom HACS repositories, or migrating to a custom integration through HA NOVA Relay. license: MIT compatibility: Requires the ha-nova CLI (run 'ha-nova setup' first) and the HA NOVA Relay in Home Assistant (App, or standalone container on Container/Core). HACS 2.x must already be installed in Home Assistant.
HA NOVA HACS Lifecycle
Scope
HACS package lifecycle:
- inventory: registered repositories, installed versions, pending states
- custom repository registration and removal
- download/install (exact version, stable, or explicit prerelease), update, redownload, version pinning
- uninstall/removal with consumer discovery
- custom-integration migration coordination
Not in scope:
update.*entity flows — the plain "update this integration" path stays inha-nova:updates; this skill owns what the entity flow cannot do- integration config flows after install (
ha-nova:integration-setup) - installing HACS itself (HA documentation/UI)
- Lovelace dashboard editing (
ha-nova:dashboard)
Bootstrap (once per session)
Read and follow ../ha-nova/session-bootstrap.md.
Verify relay CLI: ha-nova relay health
If this fails: ha-nova setup
Then probe HACS once via hacs/info and classify the failure before
advertising any coverage: WS error unauthorized → the Relay upstream
credential lacks HA admin (HACS registers every command admin-only) —
remediation is switching that credential to an admin account, never an
install hint. unknown_command is ambiguous (missing, not loaded, or an
unsupported line that does not register the pinned commands): read the HACS
config entry via the API — entry absent → install guidance; entry present
but not_loaded/setup_error/setup_retry/migration_error →
load/restart/repair remediation; entry present and loaded → unsupported
schema, fail closed with the HACS-UI pointer.
Relay Contract
File-based relay requests only:
ha-nova relay ws --data-file <payload-file> --out <result-file>— allhacs/*commands, the WS-only frontend reads{"type":"lovelace/resources"}and{"type":"lovelace/config","url_path":<dashboard>}, and the preflight reads the uninstall/migration flow depends on:{"type":"config_entries/get"},{"type":"config/entity_registry/list"},{"type":"config/device_registry/list"}, and{"type":"search/related","item_type":"entity","item_id":<entity_id>}ha-nova relay core --method GET --path <path> --out <result-file>for HA REST reads (config entries, states)ha-nova relay core --method DELETE --path /api/config/config_entries/entry/<entry_id>— ONLY for a dependent config-entry deletion inside this skill's uninstall/migration flow, after its own typed confirmation--jq-file <filter-file>for non-trivial filters
Envelope parsing follows skills/ha-nova/relay-api.md → Standard Envelope;
WS results live under .data.
The pinned command map, repository-identity rules, error asymmetry, and
restart semantics live in hacs-commands.md — read it before the first
hacs/* call. Only commands from that map may be sent. Read hacs/info
first every session and apply its capability gate; on an unrecognized schema
or a set disabled_reason, fail closed with the HACS-UI pointer on an
unrecognized install. Never guess schemas, never edit .storage, never SSH.
Flow
Inventory
- Capability gate (
hacs/info), thenhacs/repositories/list— bounded: filter by requested category/name, render as a List Frame with counts and Progressive Detail; never dump the raw list. - Registration, downloaded files, and config entries are three distinct lifecycle objects — name them as such in every result (a registered repository is not installed; installed files are not a configured integration).
- Surface
hacs/repositories/removedmatches and unacknowledgedhacs/critical/listentries for installed packages as warnings.
Resolve
Resolve the target through list/hacs/repository/info in THIS session and
use only its id afterwards (identity rules in hacs-commands.md). On
ambiguity, ask one blocking question with the candidate full_names. Never
act on a name match alone.
Install / update / redownload / pin
- Read
hacs/repository/releases(andrelease_notesfor updates) before choosing. The list is DISCOVERY, not the complete chooser — it returns only the newest page (~30): a user-named tag/ref outside it can still be installed one-off; bind that exact ref in the preview and let the download validate it (a rejected ref fails the mutation loudly, which the read-back confirms). Durable-pin rules (2.0.5version_to_download): on a repository WITH releases, any non-nullselected_tagis honored — older tags outside the newest page pin durably (confirm with the post-pin read-back thatselected_tagis still set); pinning the CURRENT latest clears itself (HACS resets it) and is not a pin. On a repository WITHOUT releases, only the default branch pins durably — any other ref installs one-off with the default-branch fallback named in the preview. A PRERELEASE tag on a repository that ALSO has a stable release pins durably without any toggle (last_versionis set). Only a prerelease-ONLY repository needs beta visibility ON for a durable prerelease pin (the confirmedhacs/repository/betatoggle): with it off, such a repository has nolast_versionand its prereleases are absent frompublished_tags, so later downloads fall back to the default branch — without the toggle, that install is one-off, named as such. A repository with NO releases installs its default branch — first-class, not unsupported: name the branch and resolved commit in the preview and verify the installed ref on read-back. A user-pinned version (selected_tag) is never sil