# Read

> Use when listing or reading Home Assistant automation and script configs through HA NOVA Relay. For analysis or review, use ha-nova:review instead.

- **Type:** Skill
- **Install:** `agentstack add skill-markusleben-ha-nova-read`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [markusleben](https://agentstack.voostack.com/s/markusleben)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [markusleben](https://github.com/markusleben)
- **Source:** https://github.com/markusleben/ha-nova/tree/main/skills/read
- **Website:** https://github.com/markusleben/ha-nova

## Install

```sh
agentstack add skill-markusleben-ha-nova-read
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# HA NOVA Read

## Scope

Read only:
- `automation.list`
- `automation.read`
- `script.list`
- `script.read`
- `automation.trace`
- `script.trace`

Not for helpers — use `ha-nova:helper` for helper list/read.

Multi-target scope is inventory-only:
- use `skills/ha-nova/bulk-patterns.md` for `prefix` / `domain` / `area` / `label`
- keep full YAML reads single-target only

No writes.
- MUST NOT issue `POST`, `PUT`, `PATCH`, or `DELETE` relay requests.
- MUST NOT call service endpoints or any other mutation path learned during the read flow.
- If the task becomes a config change, hand off to `ha-nova:write` with resolved IDs and current config.

## Bootstrap (once per session)

Verify relay CLI: `ha-nova relay health`
If this fails: `ha-nova setup`

## Relay Contract

Use file-based relay requests:

1. Write final JSON payloads with the client's native file-writing tool. Do not create placeholder templates and patch them later with `perl -0pi`, `sed -i`, or similar rewrites.
2. Use `ha-nova relay ws --data-file `.
3. Use `ha-nova relay core --method  --path  --body-file ` when a body is needed.
4. Use `--jq-file ` for non-trivial filters and `--out ` for large responses.

## Flow

### Listing automations / scripts

Use the compact entity registry (abbreviated keys: `ei`=entity_id, `en`=name, `ai`=area_id):

Create `` with:

```json
{"type":"config/entity_registry/list_for_display"}
```

Then run:

```text
ha-nova relay ws --data-file  --jq-file 
```

Write `` with one of:

```jq
[.data.entities[] | select(.ei | startswith("automation.")) | {entity_id: .ei, name: .en, area_id: .ai}] | .[0:30]
```

```jq
[.data.entities[] | select(.ei | startswith("script.")) | {entity_id: .ei, name: .en, area_id: .ai}] | .[0:30]
```

For bulk inventory by `prefix`, `domain`, `area`, or `label`, reuse `skills/ha-nova/bulk-patterns.md` and return the compact table only. For area scope, use the `search/related` area projection rules, not compact-registry `ai`.

### Keyword search

Use short keyword stems and always limit results.

```text
ha-nova relay ws --data-file  --jq-file 
```

Write `` with:

```jq
[.data.entities[] | select(.ei | startswith("automation.")) | select((.ei + " " + (.en // "")) | test("KEYWORD";"i")) | {entity_id: .ei, name: .en, area_id: .ai}] | .[0:20]
```

If 0 results: try synonyms or shorter stems: `test("kw1|kw2";"i")`.

For "automations in room X": stay inside `read` and follow the area-first `search/related` flow from `skills/ha-nova/bulk-patterns.md`.

### Reading a single config

Resolve the config key via entity registry first; UI-created items often use numeric `unique_id` values.

1. Resolve `unique_id`:
   - create `` with `{"type":"config/entity_registry/get","entity_id":"automation.{slug}"}`
   - run `ha-nova relay ws --data-file  --out `
   - then run `ha-nova relay jq -r --file  '.data.unique_id'` (POSIX example; on Windows/PowerShell pass the same filter with native argument quoting)
   - write the final `entity_id` value directly into ``; do not use placeholder tokens such as `REPLACE_ENTITY_ID`
   - for scripts: use `script.{slug}`
2. Fetch config into ``:
   - `ha-nova relay core --method GET --path /api/config/automation/config/{unique_id} --jq-file  --out `
   - for scripts: `/api/config/script/config/{unique_id}`
   - prefer copying `skills/ha-nova/config-body-filter.jq` to ``
   - if you must recreate it, write `` with:
     ```jq
     if .ok then .data.body else error("relay error: \(.error.message // "unknown")") end
     ```
   - if the contents differ, overwrite the same `` with the canonical line before the first config read; do not create alternate config-filter filenames
   - POSIX heredocs shown elsewhere are examples only; on Windows/PowerShell preserve the same jq body with native file writing
3. Validate JSON:
   - `ha-nova relay jq --file  -e --jq-file `
   - use `type == "object"`
4. For counts or follow-up transforms, use `ha-nova relay jq --file ` with `length` or `--jq-file `.

Read the saved file with the native file-reading tool. Do not analyze configs from shell output.

### Related entities

Find automations/scripts that use a specific entity:

Create `` with:

```json
{"type":"search/related","item_type":"entity","item_id":"{entity_id}"}
```

Then run:

```text
ha-nova relay ws --data-file 
```

If id is ambiguous, ask one clarifying question. Never use raw `get_states`.

## Output Format

After reading a config, present:

```
**{Automation|Script}: {alias}**
- **ID:** {id}
- **Entities:** {list all entity_ids used in triggers, conditions, and actions}
- **Triggers:** {short description of each trigger}
- **Conditions:** {short description or "none"}
- **Actions:** {short description of each action, grouped by trigger if applicable}
- **Mode:** {single|restart|queued|parallel}
```

Then show the full YAML config:

```yaml
alias: ...
triggers: ...
actions: ...
```

For list operations, use a compact table:

```
| Entity ID | Name | Area |
|-----------|------|------|
```

Never show raw JSON to the user.

## Trace Debugging

For trace queries:

1. Resolve the `unique_id` (config key). **`item_id` requires the `unique_id`, NOT the entity_id slug**.
   Create `` with the `config/entity_registry/get` request, then run:
   ```text
   ha-nova relay ws --data-file  --out 
   ha-nova relay jq -r --file  '.data.unique_id'
   ```
   The jq filter quoting above is a POSIX example. On Windows/PowerShell pass the same filter with native argument quoting.
2. List recent traces using the resolved `unique_id`:
   Create `` with:
   ```json
   {"type":"trace/list","domain":"automation","item_id":"{unique_id}"}
   ```
   ```text
   ha-nova relay ws --data-file 
   ```
   For scripts: `"domain":"script"`.
3. For a detailed trace, save `trace/get` to ``:
   Create `` with:
   ```json
   {"type":"trace/get","domain":"automation","item_id":"{unique_id}","run_id":"{run_id}"}
   ```
   ```text
   ha-nova relay ws --data-file  --out 
   ha-nova relay jq --file  empty
   ```
   Read the file with your native file-reading tool.
4. Summarize timestamp, trigger, conditions, actions, and result.
5. If traces do not cover the relevant period, optionally check `last_changed` via `/api/states/{entity_id}`.
6. Before presenting conclusions, verify `item_id` in trace data matches the target's `unique_id`. see `skills/ha-nova/SKILL.md` → Claim-Evidence Binding.

## Latency Policy

- no agent dispatch for simple reads
- no proactive `/health` preflight
- no exploratory retry loops without concrete failure

## Safety

- never guess ids
- if multiple close matches, ask one selection question

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [markusleben](https://github.com/markusleben)
- **Source:** [markusleben/ha-nova](https://github.com/markusleben/ha-nova)
- **License:** MIT
- **Homepage:** https://github.com/markusleben/ha-nova

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-markusleben-ha-nova-read
- Seller: https://agentstack.voostack.com/s/markusleben
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.