Contribute with AI tools

You can use AI tools when you contribute to Home Assistant, and several repositories ship instructions and skills written specifically for them. This page is the practical side of the AI policy: how to get good work out of a tool, and how to stay the person who understands and answers for the result.

An AI tool can save you a lot of reading and typing. It doesn't save you the understanding. Reviewers can tell the difference, and the policy is clear about what happens to pull requests that look like unreviewed AI output: they are closed.

The AI policy is short. In daily work, it comes down to this:

• You understand every change, and can explain it in your own words. If you can't explain a line, find out what it does or remove it before you open the pull request.
• You stay in the loop. Autonomous agents are not allowed. An agent can write code on your machine, but you decide what gets submitted. Don't let a tool open issues or pull requests, or post comments, without you reviewing them first.
• You answer reviewers yourself. Using AI to fix your grammar is fine. The substance of your answers must be your own.
• You disclose honestly where the template asks. The pull request templates of Home Assistant Core and the frontend have two checkboxes: "I understand the code I am submitting and can explain how it works", and "Any generated code has been carefully reviewed for correctness and compliance with project standards". The Android and iOS templates ask you to confirm you read the policy, and to select exactly one of three options: no AI, AI assistance, or code fully generated by AI that you reviewed and understood. Leave those parts of the template in place, and tick them only when they are true.
• You treat AI review comments like any other review comment. Some projects use AI tools for reviews and triage. They can be wrong. If you think a comment is wrong, say so, briefly.

The agent instructions say the same thing to the tool. In core, the frontend, both apps, home-assistant.io, and the Supervisor, they end with an "AI policy" section that tells the agent not to open issues or pull requests autonomously, and not to post comments for you without your review.

You don't have to explain Home Assistant to your AI tool from scratch. Most repositories carry two kinds of files for agents:

• Instructions: one Markdown file with the basics of the repository, like how to set up the environment, run the tests, and format the code, plus the rules agents keep getting wrong. Most tools read it at the start of every session.
• Skills: folders with a SKILL.md file each. The front matter has a name and a description. The tool loads a skill when your task matches its description, or when you ask for it by name. In Claude Code, a skill also becomes a command: the ha-review skill runs with /ha-review.

Both are plain Markdown, and they are worth reading yourself. The integration skill of core, for example, sums up review guidelines in a few dozen lines.

Each tool looks in its own places. This is what the official documentation of each tool says:

File or folder	Read by
AGENTS.md	Codex, GitHub Copilot, and Claude Code when there is no CLAUDE.md
CLAUDE.md	Claude Code. GitHub Copilot also accepts a CLAUDE.md or GEMINI.md in the root
.github/copilot-instructions.md	GitHub Copilot
.github/instructions/*.instructions.md	GitHub Copilot, for the files that match the applyTo pattern of each file
.claude/skills/	Claude Code and GitHub Copilot
.agents/skills/	Codex and GitHub Copilot
.github/skills/	GitHub Copilot

To serve every tool from one source, the repositories use symbolic links. In the frontend, for example, CLAUDE.md and .github/copilot-instructions.md link to AGENTS.md, and .claude/skills links to .agents/skills. That way, most tools get the same instructions. Not every tool finds every skill folder, though. Codex, for example, reads .agents/skills/ and not .claude/skills/, so in core and home-assistant.io you point it to a skill yourself.

• Core: AGENTS.md, with CLAUDE.md linked to it. .github/copilot-instructions.md is generated from it by script/gen_copilot_instructions.py, with extra rules for Copilot code review. Skills in .claude/skills/, and a raise-pull-request subagent in .claude/agents/.
• Frontend: AGENTS.md, with CLAUDE.md and .github/copilot-instructions.md linked to it. Skills in .agents/skills/.
• Android: AGENTS.md, with CLAUDE.md, GEMINI.md, .github/copilot-instructions.md, and .junie/guidelines.md linked to it. Skills in .agents/skills/, and one in .github/skills/.
• iOS: AGENTS.md, with CLAUDE.md and .github/copilot-instructions.md linked to it. Skills in .agents/skills/.
• home-assistant.io: .github/copilot-instructions.md, with AGENTS.md, CLAUDE.md, and GEMINI.md linked to it. Skills in .claude/skills/.
• Supervisor: .github/copilot-instructions.md, with AGENTS.md and CLAUDE.md linked to it. No skills.
• This site: .github/copilot-instructions.md, with AGENTS.md and CLAUDE.md linked to it, and review checklists in .github/instructions/. Skills in .github/skills/, with .claude/skills linked to it.

The operating-system repository has the AI policy, but no agent instructions or skills.

One line per skill. Select a name to read the skill itself.

Skill	Use it for
ha-integration-knowledge	Building, testing, and reviewing integrations. The skill says to use it as the main reference whenever you look at an integration
ha-quality-scale-verify	Checking whether an integration follows a quality scale rule, or reaches a tier
ha-review	Reviewing code changes against the target branch, with each finding double-checked
ha-pr-reviewer	Reviewing a pull request on GitHub. It reports in your terminal only, and doesn't act on GitHub
ha-pr-comment-audit	Finding review comments on a pull request that aren't addressed yet
ha-merge-queue	Finding open pull requests that are ready to merge. Mostly for maintainers
bump-dependency	Bumping a Python dependency, regenerating the requirement files, and preparing the pull request

Skill	Use it for
ha-frontend-components	Dialogs, forms, alerts, keyboard shortcuts, tooltips, panels, cards, and buttons
ha-frontend-contexts	Lit contexts, and moving components away from the broad hass object
ha-frontend-demo	The standalone demo, its configurations, and its mocked APIs
ha-frontend-events	Typing, dispatching, and declaring events
ha-frontend-gallery	Pages, demos, and content of the gallery
ha-frontend-lit	Lit conventions: reactive properties, state, lifecycle, and DOM queries
ha-frontend-review	Reviewing frontend changes, preparing a pull request, and filling in the template
ha-frontend-styling	CSS, theming, spacing, responsive layout, RTL, and view transitions
ha-frontend-testing	Lint, type checks, Vitest, Playwright, and dev servers
ha-frontend-types	TypeScript conventions and data contracts with the backend
ha-frontend-user-facing-text	Labels, errors, terminology, and strings that need translation
ha-frontend-ux-readiness	Deciding whether a new card, badge, screen, or interaction pattern needs input from the design team

Skill	Use it for
ha-android-architecture	Modules, layers, Hilt, secure storage, and calling Home Assistant APIs
ha-android-committing	Finishing a change: format, tests, changelog, branch name, and pull request
ha-android-concurrency	Coroutines, dispatchers, Flows, and thread safety
ha-android-e2e-debugging	Finding out why an end-to-end test failed
ha-android-kotlin-style	Kotlin style: constants, types, time, naming, and comments
ha-android-logging-errors	Logging, error handling, and keeping user data out of logs
ha-android-review	Reviewing a change for correctness, style, and security
ha-android-skill-maintenance	Keeping AGENTS.md and the skills up to date
ha-android-testing	Unit, Robolectric, Flow, and screenshot tests
ha-android-ui	Compose screens, ViewModels, navigation, widgets, and the design system
agentic-workflows	Designing and debugging GitHub Agentic Workflows in the repository

The Android repository also has a Claude Code hook in .claude/settings.json that reminds the agent to load ha-android-testing when it edits a test.

Skill	Use it for
ha-ios-architecture	Project layout, targets, the Current dependency pattern, and code signing
ha-ios-code-style	Swift style, SwiftFormat, SwiftLint, icons, and logging
ha-ios-concurrency	async/await, actors, Combine, and talking to the server with HAKit
ha-ios-localization	Adding or changing user-facing strings
ha-ios-magicitem	The item model shared by widgets, Apple Watch, CarPlay, and App Shortcuts
ha-ios-persistence	Storing data with GRDB, Realm, or UserDefaults
ha-ios-push-live-activities	Push notifications and Live Activities
ha-ios-skill-maintenance	Keeping the skills and AGENTS.md up to date
ha-ios-testing	Unit tests, snapshot tests, and mocking dependencies
ha-ios-ui	SwiftUI and UIKit conventions, and the design system package
ha-ios-webview	The web view that shows the frontend, its message bus, and deep links
ha-ios-workflow-ci	The order of steps before a commit, TestFlight gating, and the CI checks

Skill	Use it for
home-assistant-docs-writing-style	Any documentation, page, or user-facing prose
home-assistant-markdown-liquid-style	Markdown, Liquid, links, images, glossary terms, My links, and text boxes
home-assistant-yaml-style	YAML examples, automations, scripts, and templates
document-integration-docs	Writing or updating the documentation of an integration, in the split-page format
create-blog-post	Turning a Google Docs draft into a blog post
create-astro-component	Rebuilding a piece of the website as an Astro component
update-agent-instructions	Updating the agent instructions of the repository

Skill	Use it for
write-page	Adding or changing a page, from picking the area to running the checks
review	Reviewing a pull request, pages, or site code, with every claim checked against the source
fact-check	Checking existing pages against the source repositories, and fixing what doesn't hold
add-glossary-term	Adding or changing a glossary term
design-component-page	A component page in the Design area, with live demos
update-demos	Rebuilding the live component demos from a newer frontend
port-developers-change	Bringing a change from the old developer documentation over to this site
create-blog-post	Turning a draft into a blog post on this site
update-agent-instructions	Updating the agent instructions, and syncing the writing rules shared with home-assistant.io

These workflows combine the skills above with the guides on this site. They work with any tool that reads the skill folders. If yours doesn't, point it to the SKILL.md file yourself.

1. Reproduce the bug yourself first, and find the issue on GitHub. An agent can't tell you whether its fix fixes your bug if you never saw it fail.
2. Ask the agent to find the cause, with the ha-integration-knowledge skill. Ask it to write a test that fails because of the bug, before it changes the code. A test that passes without the fix proves nothing.
3. Let it fix the code, then run the tests of the integration yourself, as in Running the tests: pytest tests/components/<domain>. If the fix changes strings.json, the core AGENTS.md tells the agent to regenerate the English translations first, because the tests read those.
4. Read the diff. Agents like to add more than the fix: extra "defensive" checks, comments that narrate the code, a refactor on the side. Core's instructions tell agents to avoid comments that restate the code and checks that validation already covers, but check anyway, and remove what the fix doesn't need.
5. Open the pull request yourself, with the template filled in. Core has a raise-pull-request subagent that runs the checks and fills in the template for you. Know that it pushes your branch and opens the pull request as a draft. It leaves "I understand the code..." and "Any generated code has been carefully reviewed..." unchecked, for you to tick once that is true.

A new integration must reach the Bronze tier of the quality scale, and its first pull request should stay small. Read Create an integration first: it explains when a new integration belongs in core, and sets the limits reviewers ask for.

1. Start with the library. The ha-integration-knowledge skill says integrations should be thin wrappers, and that protocol and device logic belongs in a separate library on PyPI. An agent happily writes an HTTP client inside your integration. Don't let it. See Build a Python library.
2. Generate the skeleton yourself, with python3 -m script.scaffold integration. The scaffold leaves TODO comments where your code goes, and a quality_scale.yaml with every rule set to todo.
3. Fill it in with the agent, one platform at a time, with ha-integration-knowledge loaded. Ask it to explain the config flow and the coordinator before you move on. You need to explain them later, to a reviewer.
4. Mark the Bronze rules honestly in quality_scale.yaml: done, or exempt with a reason. The rules explain each one.
5. Verify with ha-quality-scale-verify. The skill checks one rule at a time, and every Bronze rule for a tier. It runs tools where they exist, like hassfest, instead of guessing from the code, and marks a rule as unverified when it can't check it. Some Bronze rules are outside the core repository: the brands assets, and the docs-* rules, which need your documentation pull request on home-assistant.io. Read the report, and fix or exempt what it finds.
6. Run the checks yourself: the tests of your integration and prek run --all-files. See Linters, hassfest, and CI.
7. Read every line, then open the pull request as above. A reviewer will ask why a piece of code is there. "The AI wrote it" is not an answer the policy accepts.

Reviewing helps the whole project, and the core template invites you to review two other pull requests. An AI tool can help you find your way in an unfamiliar change. The review you post must still be yours.

• Core: ha-pr-reviewer reads the pull request with the GitHub CLI, reviews it with ha-review, and checks the open comment threads with ha-pr-comment-audit. It reports in your terminal only.
• Frontend: ha-frontend-review, with the companion skills that match the change. It reads the existing comments first, and gives human feedback priority over feedback from agents.
• Android: ha-android-review.

Then check each finding against the code before you write it down. Drop the ones you can't confirm or don't understand. Post your review in your own words. Don't paste the tool's output, and don't let the tool post for you. Reviewing pull requests explains what a good core review looks for.

For a new card, the project recommends the Marketplace first, see share it. These steps are for a card in the frontend itself.

1. Load ha-frontend-components and ha-frontend-styling. The components skill lists what a card must do: validate its configuration, handle loading, error, unavailable, and missing entities, and come with an editor when needed.
2. Read ha-frontend-ux-readiness before you write much code. A new card is a design decision as much as code. When the direction isn't settled, reviewers ask the design team for input. See Review and release and how we design.
3. Put every visible string through the translation system, as ha-frontend-user-facing-text explains.
4. Run pnpm lint and pnpm test, and try the card yourself in light and dark mode and on a phone. Add screenshots or a short video to the pull request: the frontend template asks for them.

A custom card in your own repository has no skills to load. The custom card guide is the reference there.

The instructions of home-assistant.io tell agents to load the matching skill before they edit, and to load all that apply:

• home-assistant-docs-writing-style for any prose.
• home-assistant-markdown-liquid-style for links, images, Liquid, and other site syntax.
• home-assistant-yaml-style for YAML examples.
• document-integration-docs for an integration page. It takes the domain, like /document-integration-docs <domain> in Claude Code, and reads the triggers, conditions, and actions of the integration in core when you have core and the frontend cloned next to the documentation.

Two rules in those instructions matter most for AI work. Agents must not invent new dashboard, card, automation, or script examples unless you ask for them. And document-integration-docs must not trust the issue text or the existing docs unless core confirms them. Hold your own review to the same standard: check every option, default, and step against the code, and look at your page in the Deploy Preview. Writing docs has the rest.

Translations of the interface happen in Lokalise, by people. The translation rules ask you to translate only into your native language, because machine translation shows. The agent instructions of the apps agree from the other side: an agent adds or changes English strings only. The Android skills say the translated files come from Lokalise and must never be added or edited, and the iOS skill says to only change the English .strings files.

There is one documented exception. For voice intents, the intents repository can generate a prompt that you paste into an AI model to draft the sentences of an intent. That is a draft, for a native speaker to rewrite.

A tool's output is a draft. These are the checks that catch the mistakes that reviews of this very site found again and again.

• Verify against the code, on the right branch. The truth is the default branch of the repository, like dev for core and the frontend. Not your memory, not the tool's memory, and not a local clone that is weeks old. Function names, parameters, and commands change.
• Claims about people, processes, and numbers need a source. Who decides, who reviews, how long it takes, how many there are. No code proves these, and tools fill the gap with something that sounds right. Find an official page, or leave it out.
• Watch the absolute words. "Always", "never", "every", "only". Look for the exception: a second code path, a fallback, a feature flag. A condition often gets lost when a tool summarizes.
• Test across lifecycle boundaries. Code that works on the happy path breaks on the first update, on unload and reload, after a migration, when a device disappears and comes back, or with an empty list. Ask yourself what happens at each one.
• Run the steps, in order, from a fresh start. Instructions written by a tool often skip a cd, an install, or a setting that a later step needs.
• Don't let a summary stand in for the source. A tool that fetches a page or a file gives you its summary, and summaries garble names and numbers. Read the source yourself before you rely on a detail.
• Read the diff before you commit. Look for changes you didn't ask for, comments that promise more than the code does, and code you can't explain.

This site publishes /llms.txt, an index of its areas and pages for AI tools, in the llms.txt format. Give it to your agent at the start of a task, so it can find the guide that applies instead of guessing, or reading outdated pages elsewhere. The same rule applies to what it finds there: it's a starting point, and the code is the source.

• Not sure whether your use of AI fits the policy? Ask a maintainer, in your pull request or on the Home Assistant Discord.
• A skill that gives wrong advice? Open an issue or a pull request in the repository that carries it. The skills are maintained like any other file.