Agent Skills for Home Assistant: Teaching AI Agents Domain Expertise

[sergeykad]

The Problem

AI agents connected to Home Assistant through ha-mcp wield 95+ tools but lack the domain knowledge to use them well. Issue #445 proved the point: agents default to Jinja2 templates when native HA constructs — state conditions with list syntax, min_max helpers, wait_for_trigger — solve the problem directly. Templates are flexible and always syntactically valid, so agents reach for them first. A seasoned HA user never would.

MCP gives agents the ability to act. Skills give agents the knowledge to act well.

What Are Agent Skills?

Agent Skills is an open standard for packaging domain expertise into instruction sets that AI agents load on demand. A skill is a folder containing a SKILL.md file (YAML metadata + Markdown instructions) and optional reference material. 26+ tools adopt the standard: Claude Code, GitHub Copilot, Cursor, VS Code, Gemini CLI, OpenAI Codex, Roo Code, Mistral Vibe, and others. Because the standard is tool-agnostic, a skill authored once works everywhere.

Skills complement ha-mcp: ha-mcp provides connectivity (tools for searching, controlling, and configuring HA); a skill provides expertise (when to use native conditions, which helper type fits, how to structure automations). Together they complete the picture.

For Home Assistant, a single skill — ha-mcp-best-practices — with reference files for deeper material fits naturally. The core SKILL.md covers principles and quick-reference patterns; a references/ directory holds detailed material (automation patterns, helper types, template guidelines, device control) that agents load only when needed.

ha-mcp-best-practices/
├── SKILL.md                    # Core instructions + metadata
├── references/                 # Detailed docs loaded on demand
│   ├── automation-patterns.md  # Native conditions, triggers, waits
│   ├── helper-selection.md     # Built-in helper types and when to use each
│   ├── template-guidelines.md  # When templates ARE the right choice
│   └── device-control.md       # Domain-specific control patterns
└── assets/
    └── examples.yaml           # Working examples

What the Skill Covers

Core principles (in SKILL.md):

• Prefer native HA constructs over templates
• Know built-in helper types before reaching for template sensors
• Use native conditions, triggers, and waits — reserve templates as a last resort
• Control devices with domain-aware patterns (lights, climate, covers, locks)

Reference material (in references/, loaded on demand):

• Automation patterns (#445, #384): state conditions with list syntax, NOT wrappers, attribute conditions, wait_for_trigger, numeric state conditions
• Helper selection: min_max, combine, statistics, threshold, derivative, utility_meter, input helpers, counters, timers
• Template guidelines: when templates are the right tool — cross-entity calculations, complex conditional formatting, dynamic content
• Device control: domain-specific patterns, service parameters, state attributes
• Dashboard design: card selection, modern patterns (ha-mcp already ships dashboard_guide.md — this becomes a reference file)

What the Skill Looks Like (Sketch)

---
name: ha-mcp-best-practices
description: >
  Best practices for configuring Home Assistant via ha-mcp.
  Use when creating or editing automations, helpers, scripts,
  dashboards, or device controls. Teaches native HA constructs
  over templates and guides helper type selection.
---

# Home Assistant Best Practices for AI Agents

## Core Principle

Use native Home Assistant syntax wherever possible. Templates
bypass validation, fail silently at runtime, and obscure intent.
Treat them as a last resort.

## Quick Reference

### Conditions: prefer native syntax

| Instead of template | Use native |
|---|---|
| `{{ states('x') in ['a','b'] }}` | `state:` with list `["a","b"]` |
| `{{ not is_state('x','off') }}` | `condition: not` wrapper |
| `{{ state_attr('x','y') == 'z' }}` | `attribute:` condition |
| `{{ is_state(...) }}` in wait | `wait_for_trigger` with state trigger |

### Helpers: know what exists

Before creating a template sensor, check whether a built-in helper
fits: min_max, combine, statistics, threshold, derivative,
utility_meter, counter, timer, group.

(See references/helper-selection.md for the full list
and decision flow.)

### Automations

(See references/automation-patterns.md for complete patterns
with before/after examples.)

### Device Control

(See references/device-control.md for domain-specific
parameters and capabilities.)

Delivery: How Agents Get the Skill

Two paths serve two types of agents:

1. Filesystem-based agents (Claude Code, Cursor, Copilot, etc.)
Clone or install the skills repo. Point the agent at the directory. It discovers SKILL.md files automatically through the Agent Skills standard.

2. Tool-based / MCP agents (claude.ai, Open WebUI, ChatGPT, etc.)
ha-mcp could expose the skill as an MCP prompt — the MCP-native equivalent of on-demand instruction templates. The MCP spec already defines prompts/list and prompts/get for this purpose. Any MCP client could then discover and activate the skill without filesystem access.

Both paths draw from the same source of truth.

Where Should Skills Live?

Proposal: Start with a homeassistant-ai/skills repository — a dedicated home for community-contributed HA agent skills, following the Agent Skills open standard.

Why a separate repo:

• Skills are knowledge, not code. They demand a different contribution and review model.
• Skill authoring stays decoupled from ha-mcp release cycles.
• Community members contribute skills without touching ha-mcp.
• Filesystem-based agents use the repo standalone.

ha-mcp could serve skills from that repo as MCP prompts, bridging both delivery paths.

If skills must stay tightly coupled to MCP tool descriptions, they can live inside ha-mcp itself — but separation keeps maintenance and contribution cleaner.

References

• Agent Skills open standard — specification and tooling
• Agent Skills GitHub — reference implementation
• Issue #445 — template overuse problem
• Issue #384 — automation best practices
• MCP Prompts specification — MCP-native instruction templates

[julienld]

homeassistant-ai/skills/

@sergeykad : You are now admin of https://github.com/homeassistant-ai/skills/ 🙌🎊

Let me know if it works.

Looking forward to try this! Good luck! 🍀

On skills:

I missed that skills are now open and getting adopted by multiple tools. Nice.

One thing I noticed is that even with *_docs tools in the MCP, the agent does not check it very often. Maybe skill are the answer for that. I think there is a guide for dashboard and maybe 1-2 more.

An interesting skill would be : upgrade Home Assistant each month (backup, check the release logs, check if anything is breaking, upgrade deprecations with the "repair" panel in the settings, etc.) @maxperron would be interested.

[sergeykad]

First of all, thanks for the trust. That was a bit unexpected. I'll try not to disappoint.

On *_docs tools getting underused: skills address this differently. MCP tools require the agent to decide to call them. Skills, in theory, load automatically when the task description matches, so the knowledge lands in context before the agent acts. In practice, agents often need explicit nudging to load skills too. But the mechanism is better suited for this: the knowledge is declarative ("here's how to do things right") rather than a tool the agent has to choose to invoke.

The upgrade assistant is an interesting idea. It's a different kind of skill, more of a guided workflow than a best-practices reference, but the format supports both. Good candidate for the repo.

[sergeykad]

The repo has its first skill, CI validation, and cross-agent installation working.

npx skills add homeassistant-ai/skills works. The home-assistant-best-practices skill passes skills-ref validate, and CI runs that check on every PR.