# Contribute with AI tools

> How to use AI coding tools well when you contribute. What the AI policy asks of you, the instructions and skills the repositories carry for agents, workflows for common tasks, and what to check yourself every time.

Source: https://contributors.home-assistant.io/start/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](https://contributors.home-assistant.io/start/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.

## What the policy asks of you, in practice

The [AI policy](https://contributors.home-assistant.io/start/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](https://github.com/home-assistant/core/blob/dev/.github/PULL_REQUEST_TEMPLATE.md) and the [frontend](https://github.com/home-assistant/frontend/blob/dev/.github/PULL_REQUEST_TEMPLATE.md) 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](https://github.com/home-assistant/android/blob/main/.github/pull_request_template.md) and [iOS](https://github.com/home-assistant/iOS/blob/main/.github/pull_request_template.md) 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](https://github.com/home-assistant/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.

## How the repositories prepare your agent

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.

### Which tool reads which file

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](https://learn.chatgpt.com/docs/agent-configuration/agents-md), [GitHub Copilot](https://docs.github.com/en/copilot/how-tos/copilot-on-github/customize-copilot/add-custom-instructions/add-repository-instructions), and [Claude Code](https://code.claude.com/docs/en/memory) 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](https://code.claude.com/docs/en/skills) and [GitHub Copilot](https://docs.github.com/en/copilot/concepts/agents/about-agent-skills) |
| `.agents/skills/` | [Codex](https://learn.chatgpt.com/docs/build-skills) 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](https://github.com/home-assistant/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](https://github.com/home-assistant/frontend)**: `AGENTS.md`, with `CLAUDE.md` and `.github/copilot-instructions.md` linked to it. Skills in `.agents/skills/`.
- **[Android](https://github.com/home-assistant/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](https://github.com/home-assistant/iOS)**: `AGENTS.md`, with `CLAUDE.md` and `.github/copilot-instructions.md` linked to it. Skills in `.agents/skills/`.
- **[home-assistant.io](https://github.com/home-assistant/home-assistant.io)**: `.github/copilot-instructions.md`, with `AGENTS.md`, `CLAUDE.md`, and `GEMINI.md` linked to it. Skills in `.claude/skills/`.
- **[Supervisor](https://github.com/home-assistant/supervisor)**: `.github/copilot-instructions.md`, with `AGENTS.md` and `CLAUDE.md` linked to it. No skills.
- **[This site](https://github.com/home-assistant/contributors.home-assistant.io)**: `.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](https://github.com/home-assistant/operating-system) repository has the AI policy, but no agent instructions or skills.

## The skills per repository

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

### Home Assistant Core

| Skill | Use it for |
| --- | --- |
| [`ha-integration-knowledge`](https://github.com/home-assistant/core/blob/dev/.claude/skills/ha-integration-knowledge/SKILL.md) | 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`](https://github.com/home-assistant/core/blob/dev/.claude/skills/ha-quality-scale-verify/SKILL.md) | Checking whether an integration follows a quality scale rule, or reaches a tier |
| [`ha-review`](https://github.com/home-assistant/core/blob/dev/.claude/skills/ha-review/SKILL.md) | Reviewing code changes against the target branch, with each finding double-checked |
| [`ha-pr-reviewer`](https://github.com/home-assistant/core/blob/dev/.claude/skills/ha-pr-reviewer/SKILL.md) | Reviewing a pull request on GitHub. It reports in your terminal only, and doesn't act on GitHub |
| [`ha-pr-comment-audit`](https://github.com/home-assistant/core/blob/dev/.claude/skills/ha-pr-comment-audit/SKILL.md) | Finding review comments on a pull request that aren't addressed yet |
| [`ha-merge-queue`](https://github.com/home-assistant/core/blob/dev/.claude/skills/ha-merge-queue/SKILL.md) | Finding open pull requests that are ready to merge. Mostly for maintainers |
| [`bump-dependency`](https://github.com/home-assistant/core/blob/dev/.claude/skills/bump-dependency/SKILL.md) | Bumping a Python dependency, regenerating the requirement files, and preparing the pull request |

### Frontend

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

### Android app

| Skill | Use it for |
| --- | --- |
| [`ha-android-architecture`](https://github.com/home-assistant/android/blob/main/.agents/skills/ha-android-architecture/SKILL.md) | Modules, layers, Hilt, secure storage, and calling Home Assistant APIs |
| [`ha-android-committing`](https://github.com/home-assistant/android/blob/main/.agents/skills/ha-android-committing/SKILL.md) | Finishing a change: format, tests, changelog, branch name, and pull request |
| [`ha-android-concurrency`](https://github.com/home-assistant/android/blob/main/.agents/skills/ha-android-concurrency/SKILL.md) | Coroutines, dispatchers, Flows, and thread safety |
| [`ha-android-e2e-debugging`](https://github.com/home-assistant/android/blob/main/.agents/skills/ha-android-e2e-debugging/SKILL.md) | Finding out why an end-to-end test failed |
| [`ha-android-kotlin-style`](https://github.com/home-assistant/android/blob/main/.agents/skills/ha-android-kotlin-style/SKILL.md) | Kotlin style: constants, types, time, naming, and comments |
| [`ha-android-logging-errors`](https://github.com/home-assistant/android/blob/main/.agents/skills/ha-android-logging-errors/SKILL.md) | Logging, error handling, and keeping user data out of logs |
| [`ha-android-review`](https://github.com/home-assistant/android/blob/main/.agents/skills/ha-android-review/SKILL.md) | Reviewing a change for correctness, style, and security |
| [`ha-android-skill-maintenance`](https://github.com/home-assistant/android/blob/main/.agents/skills/ha-android-skill-maintenance/SKILL.md) | Keeping `AGENTS.md` and the skills up to date |
| [`ha-android-testing`](https://github.com/home-assistant/android/blob/main/.agents/skills/ha-android-testing/SKILL.md) | Unit, Robolectric, Flow, and screenshot tests |
| [`ha-android-ui`](https://github.com/home-assistant/android/blob/main/.agents/skills/ha-android-ui/SKILL.md) | Compose screens, ViewModels, navigation, widgets, and the design system |
| [`agentic-workflows`](https://github.com/home-assistant/android/blob/main/.github/skills/agentic-workflows/SKILL.md) | 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.

### iOS app

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

### Documentation on home-assistant.io

| Skill | Use it for |
| --- | --- |
| [`home-assistant-docs-writing-style`](https://github.com/home-assistant/home-assistant.io/blob/current/.claude/skills/home-assistant-docs-writing-style/SKILL.md) | Any documentation, page, or user-facing prose |
| [`home-assistant-markdown-liquid-style`](https://github.com/home-assistant/home-assistant.io/blob/current/.claude/skills/home-assistant-markdown-liquid-style/SKILL.md) | Markdown, Liquid, links, images, glossary terms, My links, and text boxes |
| [`home-assistant-yaml-style`](https://github.com/home-assistant/home-assistant.io/blob/current/.claude/skills/home-assistant-yaml-style/SKILL.md) | YAML examples, automations, scripts, and templates |
| [`document-integration-docs`](https://github.com/home-assistant/home-assistant.io/blob/current/.claude/skills/document-integration-docs/SKILL.md) | Writing or updating the documentation of an integration, in the split-page format |
| [`create-blog-post`](https://github.com/home-assistant/home-assistant.io/blob/current/.claude/skills/create-blog-post/SKILL.md) | Turning a Google Docs draft into a blog post |
| [`create-astro-component`](https://github.com/home-assistant/home-assistant.io/blob/current/.claude/skills/create-astro-component/SKILL.md) | Rebuilding a piece of the website as an Astro component |
| [`update-agent-instructions`](https://github.com/home-assistant/home-assistant.io/blob/current/.claude/skills/update-agent-instructions/SKILL.md) | Updating the agent instructions of the repository |

### This contributor site

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

## Workflows for common tasks

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.

### Fix a bug in an integration

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](https://contributors.home-assistant.io/core/development/testing/): `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](https://contributors.home-assistant.io/core/development/submitting/) 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.

### Build a new integration and take it to Bronze

A new integration must reach the Bronze tier of the [quality scale](https://contributors.home-assistant.io/core/quality-scale/), and its first pull request should stay small. Read [Create an integration](https://contributors.home-assistant.io/core/integrations/create/) 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](https://contributors.home-assistant.io/core/integrations/api-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](https://contributors.home-assistant.io/core/quality-scale/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](https://contributors.home-assistant.io/core/development/checks/).
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.

### Review a pull request

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](https://contributors.home-assistant.io/core/development/reviewing/) explains what a good core review looks for.

### Add a card to the frontend

For a new card, the project recommends the Marketplace first, see [share it](https://contributors.home-assistant.io/frontend/custom-ui/#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](https://contributors.home-assistant.io/frontend/development/review-and-release/) and [how we design](https://contributors.home-assistant.io/design/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](https://contributors.home-assistant.io/frontend/custom-ui/card/) is the reference there.

### Write documentation on home-assistant.io

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](https://contributors.home-assistant.io/writing/) has the rest.

### Translations are not an AI task

Translations of the interface happen in [Lokalise](https://contributors.home-assistant.io/glossary/lokalise/), by people. The [translation rules](https://contributors.home-assistant.io/translate/reference/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](https://contributors.home-assistant.io/translate/voice/style-guide/#drafts-from-an-ai-model), the [intents repository](https://github.com/OHF-Voice/intents) 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.

## What to check yourself, every time

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.

## Give your agent context about this site

This site publishes [`/llms.txt`](https://contributors.home-assistant.io/llms.txt), an index of its areas and pages for AI tools, in the [llms.txt format](https://llmstxt.org/). 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.

## Who to talk to

- Not sure whether your use of AI fits the policy? Ask a maintainer, in your pull request or on the [Home Assistant Discord](https://www.home-assistant.io/join-chat/).
- 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.