home-assistant-frontend

name: home-assistant-frontend description: Home Assistant frontend development with Lit Web Components and TypeScript. Use when working in the Home Assistant frontend repo, editing ha-* components, reviewing HA PRs, or applying HA-specific conventions (localization, theming, dialogs, panels, cards).

Home Assistant Frontend

Use this skill when working in the Home Assistant frontend repository or on code that follows its conventions.

Primary Source of Truth

The HA frontend repo contains its own AGENTS.md and may contain repo-local skills. These are the canonical references and must be read and followed directly:

1. Read AGENTS.md in the HA frontend repo root before making any changes.
2. Load any repo-local skills defined in the HA frontend repo — they take precedence over guidance in this skill for repo-specific patterns.
3. Do not duplicate conventions already covered by the repo's own agent instructions. This skill exists only to trigger loading and to list companion skills.

When to Apply

• Editing files in a Home Assistant frontend checkout
• Reviewing or writing ha-* prefixed Web Components
• Working with HA dialogs, panels, Lovelace cards, or selectors
• Applying HA localization, theming, or design token patterns

Companion Skills

This skill works alongside and does not replace:

• lit-rendering — generic Lit rendering and memoization
• home-assistant-lit-rendering — HA-specific Lit rendering extensions
• home-assistant-lazy-context — HA lazy-context and memoization guidance
• home-assistant-list-components — HA list component migration and usage
• types-enforce-ts — TypeScript type-safety baseline
• cleanup-unnecessary-variables — safe variable cleanup
• remove-single-use-functions — safe function inlining

Load all applicable companion skills when the change touches their concerns.

Sibling Repositories

The Home Assistant core, documentation, custom cards, custom dashboards, and core packages all live in the parent directory (../) alongside the frontend. When working across repos, reference sibling code directly rather than guessing APIs or conventions. Each repo with an AGENTS.md has its own conventions — read it before making changes there.

Core (../core)

• Read ../core/AGENTS.md when the frontend change involves backend APIs, WebSocket commands, entity models, or integration data structures.
• Reference core source (e.g. homeassistant/components/<integration>/) to understand data shapes, service schemas, and WebSocket API handlers before consuming them in frontend code.
• When adding or modifying frontend calls to backend APIs, verify the API exists in core and match parameter names, types, and response shapes to the core implementation.
• If asked to make changes that span both frontend and core (new WebSocket command, new entity feature), work in both repos and follow each repo's own AGENTS.md for its conventions.

User Docs (../home-assistant.io)

• Read ../home-assistant.io/AGENTS.md when asked to create or update user-facing documentation.
• Documentation for new frontend features, integrations, or UI changes goes here.
• Follow the docs repo's writing style (American English, Microsoft Style Guide, sentence case, friendly tone, inclusive language) — do not invent a separate style.
• When a frontend change adds user-visible functionality, remind that corresponding docs may be needed and offer to create them following the docs repo's conventions.

Developer Docs (../developers.home-assistant)

• Developer documentation for custom cards, custom dashboards, frontend architecture, and core packages lives here (developers.home-assistant.io).
• When creating or updating documentation for custom card APIs, dashboard strategies, Lovelace extensibility, or frontend development guides, work in this repo.
• Reference docs/frontend/ and docs/frontend.md for existing frontend developer documentation.
• Core packages are cloned here — use them as reference for documenting Python package APIs and integration development patterns.
• If this repo gains an AGENTS.md or .opencode/skills/, read and follow those before making changes.

Creating a New Custom Card, Card Feature, or Dashboard

When asked to create a new custom card, card feature, or dashboard:

1. Find the most recently modified ha-card-*, ha-card-feature-*, or ha-dashboard-* directory in ../ that matches the type being created.
2. Copy that repo as the starting point for the new project.
3. Reset its git history (rm -rf .git && git init --initial-branch=main).
4. Remove files specific to the original project (old source, tests, assets) while keeping the build tooling, config, and project structure.
5. Rename and update package.json, component names, and entry points to match the new project.