AGENTS.md · frenck/awesome-home-assistant

Sections

1. What this repo is
2. Where the actual rules live
3. Curation principles
4. Voice and writing style
5. Reviewing a PR that adds an entry
6. Behaviors specific to AI agents
7. Files an agent will touch most often

First lines (shown under the repo's CC-BY-4.0 license)

# AGENTS.md

Guidance for AI coding agents (and the humans driving them) working on this
repository. `CLAUDE.md` is a symlink to this file because Claude is the
odd one out; everyone else already reads `AGENTS.md`.

This is a curated awesome-list, not a software project. Most agent work
here is editing `README.md` and a small set of supporting scripts. The
mechanical rules (entry format, quality bar, license requirements, link
hygiene) already live in `.github/CONTRIBUTING.md` and the scripts under
`scripts/`. This file covers the things those don't: taxonomy, audience,
voice, and behaviors specific to working with an AI agent.

## What this repo is

`Awesome Home Assistant` is a community-curated index of resources that
live *outside* Home Assistant itself: custom integrations installable via
HACS, custom dashboard cards, themes, icon packs, Apps, ESPHome and DIY
projects, blogs, podcasts, YouTube channels, and more. The deployed site
is <https://awesome-ha.com>, built with `mkdocs-material` from `README.md`.

The audience is **Home Assistant users**, with a strong tilt toward
**newcomers and less-technical users**. Section intros and entry
descriptions should make sense to someone setting up their first
dashboard, not to someone who already knows what HACS is.

## Where the actual rules live

Before editing the list or reviewing a PR, read these:

- `.github/CONTRIBUTING.md` for entry format, license requirements,
  acceptance criteria, and link hygiene.
- `scripts/check_listing.py <repo-url>` validates a single contribution
  end-to-end (age, license, activity, HACS metadata). Run it on every
  proposed addition before merging.
- `scripts/check_activity.py` flags entries whose upstream is archived,
  deleted, or stale. Runs weekly; opens a maintenance PR.
- `scripts/update_stars.py` keeps the `(N,NNN★)` counts current. Don't
  hand-edit star counts.
- `scripts/update_youtube_subs.py` keeps the `(N subs)` counts in the
  YouTube Channels section current. Don't hand-edit subscriber counts.

If a rule appears here *and* in CONTRIBUTING.md, CONTRIBUTING.md wins.

## Curation principles

These are judgement calls a linter cannot make for you.

1. **Outside Home Assistant only.** This list does not duplicate
   home-assistant.io. Anything documented at
   `home-assistant.io/integrations/<name>` is a built-in integration and
   does not belong here. Same for HA-internal sections (Hardware, Project
   & roadmap, Open Home Foundation, Works With Home Assistant); reference
   them sparingly in the intro, never as their own section.

2. **Taxonomy is structural, not topical.** Top-level sections describe
   *what kind of thing* an entry is (custom integration, dashboard card,
   app, blueprint, blog), not *what topic* it covers (Voice, AI, Energy,
   Matter, Zigbee). Topic groupings live as subsections inside a
   structural parent. The exception is standalone community projects with
   their own ecosystem (ESPHome, Music Assistant, Z2M); those can be
   top-level on their own merit.

3. **Detect HACS-as-bootstrap.** Some HACS "integrations" are actually
   cards, themes, icon packs, or dashboards using a `custom_component` as
   bootstrap glue. Tells: "card", "theme", "dashboard", "icon pack",
   "frontend" in the description. Those go under Dashboard Cards / Themes
   / Icon packs / Dashboards, never under Custom Integrations.

## Voice and writing style

These apply to any prose an agent writes: section intros, entry
descriptions, PR titles and bodies, commit messages, code comments.

- **Lead with the user-facing problem, then name the technology.** "Pull
  data from sensors that broadcast over Bluetooth, or use Bluetooth itself
  for room-level presence detection" beats "BLE-related integrations".
- **Never call the project anything other than "Home Assistant".** Not
  "HA", not "Hass", not "Hass.io", not "HASS", not "hassio". This applies
  to prose *we* write. Project names that contain those strings (the
  "HASS Aarlo" repo, the "Hass.io Google Drive Backup" project, the
  `hassio-addons` GitHub org in URLs) stay as-is because they are the
  actual names.
- **Don't say "Home Assistant" inside an entry description.** The list's
  title already implies it. "A card for controlling robot vacuums" beats
  "A Home Assistant card for controlling robot vacuums".
- **No em dashes or en dashes anywhere.** They're a tell that text was
  generated by an AI. Use commas, parentheses, or restart the sentence.
- **No marketing fluff.** Strike "powerful", "amazing", "easy to use",
  "next-gen", "robust". State what the thing does.
- **Don't reference issue or PR numbers in committed comments.** They rot
  as the codebase evolves; that context belongs in commit messages and PR
  descriptions instead.

## Reviewing a PR that adds an entry

Run the checks in this order; the first failure ends the review.

1. Does it belong on the list at all? (Outside HA, type-correct, not a
   built-in.)
2. `python scripts/check_listing.py <url>` is green.
3. Right section *and* right subsection. Watch for HACS-as-bootstrap.
4. Description follows the voice rules above.
5. `awesome-lint` and `lychee` are green.

If a check fails and the project is close to meeting it (e.g., will pass
the age bar in three weeks), say so and invite resubmission. Be friendly;
many contributors here are first-time open-source contributors and the
list rejecting their submission is often their first OSS feedback.

## Behaviors specific to AI agents

- **Do not push directly to `main`.** Always work on a branch and open a
  PR, even for typo fixes.
- **One concern per PR.** Don't bundle a description fix, a section
  reorder, and a workflow change. Reviewers and `git revert` both prefer
  small, focused changes.
- **Don't claim CI passed unless you saw it pass.** "All checks green" is
  a verifiable claim, not a polite closing.
- **Don't fabricate star counts, license names, or last-commit dates.**
  Read them from the repo or via `scripts/check_listing.py`. If you
  can't, say so.
- **Side quests stay in scope.** If you notice something unrelated worth
  fixing, surface it as a follow-up rather than smuggling it into the
  current PR.

## Files an agent will touch most often

- `README.md` — the list itself
- `.github/CONTRIBUTING.md` — contributor-facing rules
- `scripts/check_listing.py` / `check_activity.py` / `update_stars.py` /
  `update_youtube_subs.py` — maintenance scripts
- `mkdocs.yml` — site config
- `.github/workflows/*.yaml` — link checks, listing checks, weekly maintenance