What does the HACS default repository require?
The official docs are specific: a public GitHub repository with a description, topics and a README; hacs.json in the root; the integration directory and manifest.json in the required shape; the HACS Action and Hassfest both passing; at least one full GitHub release; then a pull request to hacs/default. The docs also say new additions take months to review. The table below is from reading the hacs.xyz docs page by page on 2026-11-14.
| Requirement | What the docs say (original text read 2026-11-14) | Which page |
|---|---|---|
| Registry | Only public repositories on GitHub work; one integration per repository, with all files under custom_components/<name>/ | /docs/publish/start/, /docs/publish/integration/ |
| hacs.json | In the repository root; name is required, the other keys are optional (content_in_root, zip_release, filename, hide_default_branch, country, homeassistant, hacs, persistent_directory) | /docs/publish/start/ |
| manifest.json | At least domain, documentation, issue_tracker, codeowners, name and version | /docs/publish/integration/ |
| Brand assets | A brand directory in the repository with at least icon.png; if it is missing, the check falls back to looking for the domain in the home-assistant/brands repository | /docs/publish/integration/, /docs/publish/include/ |
| GitHub description and topics | A description is required and says what the repository is for; HACS shows it. Topics are required; HACS does not display them but they can be used for searching in the HACS store | /docs/publish/start/ |
| README | Required; explains how to use it | /docs/publish/start/ |
| License | A license GitHub can identify and the Open Source Initiative (OSI) approves; an unidentified one (NOASSERTION) or one that restricts use (for example non-commercial) fails | /docs/publish/include/ |
| Publishing | At least one full GitHub release, not just a tag; the repository must not be archived; issues must be enabled | /docs/publish/include/ |
| Automated checks | The HACS Action passes with no errors and no ignores; Hassfest passes (integrations only); the domain must not conflict with a core integration | /docs/publish/include/ |
| How to submit | Only the owner or a major contributor can submit; the PR adds the repository to the integration file in hacs/default, in alphabetical order; it cannot be submitted from an organization account | /docs/publish/include/ |
The docs do not say how long the README should be or how many characters the description may have; those numbers are unverified. You can also run the HACS Action checks on your own repository ahead of time, see /docs/publish/action/.
Is the HACS list a public web page, or only inside the app?
We did not find a public web version of the list. Checked 2026-11-14: the HACS catalog data is JSON files on data-v2.hacs.xyz, not individual web pages, and it contains no README text; the hacs.xyz sitemap has only 59 URLs, all documentation pages, and none is an integration page. From Home Assistant 2026.11, HACS is built in as the Marketplace, which is admin-only and opens from Settings.
| Data source | Checked 2026-11-14 | What it means for AI search |
|---|---|---|
| data-v2.hacs.xyz/integration/repositories.json | 200, 5,166 repositories (plugin 1,113, theme 125, template 12, appdaemon 55, python_script 9) | A machine-readable list, not a page for people |
| data-v2.hacs.xyz/integration/data.json | 200, about 3.5 MB; each repository has description, domain, downloads, topics, last_version and similar fields | No README text, so AI cannot read your usage instructions from here |
| hacs.xyz/sitemap.xml | 200, 59 URLs, all documentation pages | No page for any single integration |
| hacs.xyz/robots.txt | 404, no robots.txt | No rules to read, so no AI crawler is named |
| In the app (HACS or Marketplace) | Search covers author, type, description, name, status and topics; the detail view is a rendering of the repository README | Visible only inside the logged-in app, not a public web page |
So the GitHub description, topics and README are what a HACS user sees when searching for you in the app, and they are also the only text about you that is readable on the public web.
Does the home-assistant.io integrations section include custom integrations?
We did not see them included. The home-assistant.io sitemap has 4,431 URLs, 1,701 of them under /integrations/, and those pages document core integrations. On 2026-11-14 we fetched the sample page /integrations/hue/: the text is directly in the HTML, the canonical points to itself, there is a BreadcrumbList JSON-LD block, and there is no noindex. We compared the domains of the 5,166 integrations in the HACS data with this sitemap: there are 5,116 distinct domains, only 50 share a name with a page under /integrations/, and the rest have no page of that name.
We did not check what those 50 are (they may be custom integrations that override a core integration, or integrations that later moved into core), so that is unverified. What we can confirm is the stance of the official Marketplace page: Marketplace content is made and published by the community, not by the Home Assistant project, and is not tested, audited or supported by the project. So do not count on home-assistant.io pages to get you found.
| Site | robots.txt (2026-11-14) | Is the text readable directly |
|---|---|---|
| www.home-assistant.io | 200, 76 bytes: User-agent * with an empty Disallow:, plus a Sitemap line; no AI crawler is named, so everything is allowed | Yes: the sample page text is in the HTML, no noindex |
| hacs.xyz | 404, no robots.txt | Yes: documentation pages are static HTML, 200 |
| community.home-assistant.io (forum) | Unverified: /robots.txt and the home page both return a 403 Cloudflare challenge page; we did not bypass it | Not verified |
| github.com | Eight AI crawlers share one group: Crawl-delay: 1, 282 Disallow lines, repository home pages are not among them; Bytespider is disallowed site-wide | Yes: the sample repository page returns 200 with the README text in the HTML |
The forum has many threads about which integration works well, but we cannot read whether it is open to AI crawlers, so we cannot write that it will or will not be crawled. If you post about your integration there, treat it as a channel to users, not as a source for AI search.
So for a custom integration, what does AI search mostly read?
Mostly the GitHub repository home page. On 2026-11-14 we fetched one HACS integration repository (starwarsfan/shadow-control): HTTP 200, about 678 KB; the <title> is "GitHub - repository name: About text", the meta description is the About text plus the repository name, there is no JSON-LD, and the visible text with scripts removed contains the README text. This is a single sample page.
github.com/robots.txt gives GPTBot, OAI-SearchBot, ChatGPT-User, ClaudeBot, Claude-SearchBot, Claude-User, PerplexityBot and Perplexity-User one shared group: Crawl-delay: 1 and 282 Disallow lines, covering paths such as /*/archive/, /gist/ and /search$, and not repository home pages (read from the text of robots.txt, not verified with a real crawler). How to write the README itself so it can be cited is in Will AI search cite my GitHub README?; the six places beyond the GitHub repository are in How do open source projects get recommended by AI search? Six places beyond the README. This page covers only what is specific to Home Assistant.
| What you control | Where to write it | Who reads it |
|---|---|---|
| GitHub About description | About box on the right of the repository | The description HACS shows; the repository page title and meta description |
| topics | Topics in the repository About box | Search in the HACS store (HACS does not display them); topic pages on GitHub |
| README | README.md in the repository root | The body of the HACS detail view; the repository home page text |
| name in hacs.json | hacs.json in the repository root | The name shown in HACS |
| name and documentation in manifest.json | custom_components/<name>/manifest.json | The name and documentation link shown for the integration in Home Assistant |
| Your own website or docs page (optional) | Your own domain | The definition on the first screen of your site, the second source AI can read |
How to write a website and docs page is in How should developer docs be written so AI can understand and cite them?.
What should I do before and after publishing?
1. Get the repository layout right before the wording
Put the files in the layout below; hacs.json, manifest.json and brand/icon.png are all required.
custom_components/awesome/__init__.py custom_components/awesome/manifest.json custom_components/awesome/sensor.py brand/icon.png hacs.json LICENSE README.md
{ "name": "Awesome Thermostat", "homeassistant": "2026.11.0" }2. Write one good sentence in the GitHub About box
"What it does, and which device or service it connects to", with the brand and model right at the start. This sentence shows up in the HACS list and in the repository page title and meta description.
3. Use topics people will search for
Device brand, protocol, type, for example home-assistant, hacs, integration, thermostat. HACS says it does not display them but they can be used for searching.
4. Make the first screen of the README answer "what is it, how do I install it, what does it support"
Write the install path for Home Assistant 2026.11 and later (Settings > Marketplace) and the path for older HACS; write both. Put supported devices in a table, one model per row.
# Awesome Thermostat for Home Assistant One sentence: this custom integration adds <device or service> to Home Assistant and gives you <entities>. Install: Settings > Marketplace (HACS before 2026.11) > search "Awesome Thermostat" > Install. Supported devices: a table, one model per row. Configuration: Settings > Devices & services > Add integration. Entities and actions: the exact names. Requires Home Assistant 2026.11.0 or newer. Changelog: link to GitHub releases.
5. Publish a GitHub release, then open the PR
A tag is not enough; it has to be a full release. Get the HACS Action and Hassfest passing first, then open the PR to hacs/default. The docs say the wait is months; meanwhile users can already add the repository by hand as a custom repository.
6. Check the public page with curl
Check that the title and description on the repository page are the sentence you wrote, and that one sentence from your README can be found with grep. The text has to be in the HTML; the reason is in Do AI crawlers render JavaScript?.
# What does the public repository page say in raw HTML? curl -sL -A "Mozilla/5.0" "https://github.com/YOUR-NAME/YOUR-REPO" | grep -io '<title>[^<]*</title>' curl -sL -A "Mozilla/5.0" "https://github.com/YOUR-NAME/YOUR-REPO" | grep -io '<meta name="description"[^>]*>' curl -sL -A "Mozilla/5.0" "https://github.com/YOUR-NAME/YOUR-REPO" | grep -c "a sentence from your README" # Is your repository in the HACS catalog data? curl -s "https://data-v2.hacs.xyz/integration/repositories.json" | grep -c '"YOUR-NAME/YOUR-REPO"'
7. Ask with web search on, three times
In ChatGPT and Perplexity ask "how do I connect <device> in Home Assistant", and note which integrations are recommended and which URLs are cited. Whether AI cites integration repositories on GitHub, we have no evidence, so it is unverified; you have to test it yourself.
Structured data for your website is in Does structured data help AI search?; how to write robots.txt is in How do you write robots.txt for AI crawlers?.
How is this different from platforms with public plugin pages, like Obsidian and Figma?
| Home Assistant custom integrations | Platforms with public directory pages, such as Obsidian and Figma | |
|---|---|---|
| Public detail page | Not found: HACS and the Marketplace are inside the app; hacs.xyz has only documentation pages | The platform generates a public page for each plugin |
| Main text AI can read | GitHub repository page: About description, topics, README | The platform's plugin page, plus the GitHub repository page |
| What you can edit | About, topics, README, hacs.json, manifest.json | Each platform's fields (title, description, gallery and so on) |
| What the official docs do not say | Character limits, whether AI cites it | Differs by platform |
If you build an Obsidian plugin, the community plugin page and community-plugins.json are covered in How do I get my Obsidian plugin found in AI search?.
FAQ
What does the HACS default repository require?
The official docs say: a public GitHub repository; description, topics and README present; hacs.json in the root (name required); manifest.json under custom_components/<name>/ (domain, documentation, issue_tracker, codeowners, name, version); a brand directory with icon.png; an OSI-approved license; at least one full GitHub release; the HACS Action and Hassfest both passing. Original text read 2026-11-14.
How long does a hacs/default submission take?
The official docs say new additions take months to review, and give no number of days.
Does the HACS list have public web pages?
We did not find any. Checked 2026-11-14: the catalog data is JSON on data-v2.hacs.xyz with no README; all 59 URLs on hacs.xyz are documentation pages. From Home Assistant 2026.11, HACS is built in as the Marketplace, which opens from Settings and is admin-only.
Will the home-assistant.io integrations section list my custom integration?
We did not see it. Its 1,701 /integrations/ URLs are documentation pages for core integrations; comparing the 5,116 distinct domains in the HACS data with this sitemap, only 50 share a name and the rest have no page of that name. We have not checked what those 50 are.
Can AI crawlers read posts on the Home Assistant community forum?
Unverified. On 2026-11-14 we requested community.home-assistant.io and got a Cloudflare challenge page (HTTP 403); we could not read robots.txt and did not bypass it.
Will ChatGPT or Perplexity cite my integration repository?
We found no official statement and no evidence of actual citations, so it is unverified. What we can confirm: github.com/robots.txt does not disallow repository home pages, and the sample repository page has the README text in its HTML (checked 2026-11-14).
Do I still need a website?
Not required. The repository page already serves its text directly. If you build one, write a single page with the definition, a table of supported devices, install steps and a changelog, consistent with the README, and link to the GitHub repository.
Sources
- HACS · Include default repositories (Read in full 2026-11-14)
- HACS · Integrations (requirements) (Read in full 2026-11-14)
- HACS · General (requirements, hacs.json) (Read in full 2026-11-14)
- HACS · Data sources (Read in full 2026-11-14)
- HACS · Marketplace (Read in full 2026-11-14)
- Home Assistant · Marketplace (Read in full 2026-11-14)
- Home Assistant · robots.txt (Fetched 2026-11-14)
- Home Assistant · sitemap.xml (Fetched 2026-11-14)
- HACS · HACS Data:integration/repositories.json (Fetched 2026-11-14)
- GitHub · robots.txt (Fetched 2026-11-14)
- kagentx evaluations: the data on the case study pages; each example gives its date.