home-assistant-skills

Home Assistant Agent Skills

An Agent Skill is a plugin that teaches AI coding agents best practices for a specific technology, delivered as a portable Markdown knowledge pack.

This repository provides an Agent Skill for Home Assistant, following the open Agent Skills standard. Install a skill and your agent gains Home Assistant best practices that persist across sessions.

Included Skill

home-assistant-best-practices: Native HA constructs over templates, helper selection, automation modes, Zigbee button patterns, device control best practices, YAML-only integration management, dashboard configuration, and safe refactoring.

Installation

Agent Skills installer

Requires Node.js 18+.

npx skills add homeassistant-ai/skills

Works with AI coding agents that support the Agent Skills standard: Claude Code, Cursor, Copilot, VS Code, Gemini CLI, and others. To update: npx skills update

Claude Code plugin

Run each command separately inside Claude Code:

/plugin marketplace add homeassistant-ai/skills

/plugin install home-assistant-skills@home-assistant-skills

Run /reload-plugins or restart Claude Code for the skill to take effect.

Claude Desktop / claude.ai

1. Download or clone this repository
2. Zip the skill folder: cd skills && zip -r home-assistant-best-practices.zip home-assistant-best-practices/
3. Upload to:
   • Claude Desktop: Customize (left sidebar) → Skills → + → Create skill
   • claude.ai: claude.ai/customize/skills → Upload

Skill Contents

The home-assistant-best-practices skill includes:

File	Purpose
SKILL.md	Decision workflow and quick-reference routing
references/safe-refactoring.md	Safe workflow for renaming entities, replacing helpers, restructuring automations
references/automation-patterns.md	Native conditions, triggers, waits, automation modes
references/helper-selection.md	Built-in helpers vs template sensors (with decision matrix)
references/template-guidelines.md	When to use templates, when to avoid them, and sensor best practices
references/yaml-only-integrations.md	YAML-only integration types, post-edit actions (reload vs restart)
references/device-control.md	Service calls, entity_id vs device_id, Zigbee buttons
references/dashboard-guide.md	Dashboard layout, view types, sections, custom cards, CSS styling
references/dashboard-cards.md	Card type lookup and card-specific documentation
references/domain-docs.md	Integration and domain documentation for service calls, entity attributes
references/examples.yaml	Compound examples combining multiple best practices
references/appdaemon.md	AppDaemon apps: when to use vs. native HA, app structure, service calls, scheduling, error handling, safe refactoring impact

Contributing

See CONTRIBUTING.md for guidelines on writing and submitting skills.

License

MIT