migrate-integration-trigger-condition-docs - SKILL.md Agent Skill

name: migrate-integration-trigger-condition-docs description: Migrate Home Assistant integration trigger and condition docs to split-page format.

Usage: /migrate-integration-trigger-condition-docs <domain> [epic-or-issue]

Migrate ./source/_integrations/<domain>.markdown to the current Home Assistant split-page documentation format, but only for Labs triggers and conditions.

Keep the main context small. Use sub-agents for discovery and review. Do not trust the epic, issue text, or existing docs unless Core confirms them. Treat https://raw.githubusercontent.com/home-assistant/developers.home-assistant/master/docs/documenting/integration-docs-examples.md as the canonical template for split pages. Treat https://raw.githubusercontent.com/home-assistant/developers.home-assistant/master/docs/documenting/yaml-style-guide.md as the YAML style source for all YAML examples. Do not loosely imitate it. Follow its structure closely unless Core implementation makes a specific section inapplicable.

Already documented actions are out of scope for this command. Leave existing action pages intact. Do not create new action pages. Do not migrate action docs as part of this command.

Stage 1: inventory with a sub-agent

Launch a sub-agent to inspect:

./source/_integrations/<domain>.markdown
If you have Home Assistant Core and Frontend checked out, inspect:
- ../core/homeassistant/components/<domain>/conditions.yaml
- ../core/homeassistant/components/<domain>/services.yaml
- ../core/homeassistant/components/<domain>/triggers.yaml
- ../core/homeassistant/components/<domain>/strings.json
- ../frontend/src/translations/en.json
any existing split pages for <domain> in:
- ./source/_triggers
- ./source/_conditions
- ./source/_actions

The sub-agent must return only this compact inventory:

Domain: <domain>

Triggers to document:
- key: <domain>.<trigger_key>
  title: <title>
  description: <description>
  target domains: [...]
  options: [...]

Conditions to document:
- key: <domain>.<condition_key>
  title: <title>
  description: <description>
  target domains: [...]
  options: [...]

Existing actions to leave intact:
- page: ...
- integration-page references: ...

Categories not implemented:
- ...

Existing split pages:
- ...

UI wording:
- trigger behavior labels: ...
- condition behavior labels: ...
- action-specific labels: ...
- automation example action labels to mirror: ...

Important implementation notes:
- ...

Mismatches between epic/issue text and Core:
- ...

Rules for Stage 1:

Core is the source of truth.
Verify categories from Core, not from the issue.
Verify exact keys from YAML or implementation.
Verify supported target entity domains.
Verify behavior labels from frontend strings.
If actions already exist in docs, identify them so Stage 3 can avoid changing them unnecessarily.
If actions exist, capture the current UI action label forms once in Stage 1 and reuse them later instead of doing extra lookups during writing.
Keep the output short and factual.
Note any mismatch between existing split pages and the current developer examples template.

Stage 2: template and style extraction with a sub-agent

Launch a sub-agent to inspect:

./source/_integrations/_integration_docs_template.markdown
https://raw.githubusercontent.com/home-assistant/developers.home-assistant/master/docs/documenting/integration-docs-examples.md
https://raw.githubusercontent.com/home-assistant/developers.home-assistant/master/docs/documenting/general-style-guide.md
https://raw.githubusercontent.com/home-assistant/developers.home-assistant/master/docs/documenting/yaml-style-guide.md
relevant include snippets under ./source/_includes
2-4 existing files across triggers, conditions, and actions

The sub-agent must return only this:

Integration page requirements:
- ...
- automation examples section requirement: ...

Trigger page requirements:
- required includes in order: ...
- required heading flow: ...
- required UI wording: ...
- Good to know guidance: ...

Condition page requirements:
- required includes in order: ...
- required heading flow: ...
- required UI wording: ...
- Good to know guidance: ...

Action page requirements:
- required includes in order: ...
- required heading flow: ...
- required UI wording: ...
- Good to know guidance: ...

Common pitfalls to avoid:
- ...

Focus on include order, heading expectations, UI wording, Good to know placement, and the integration-level automation examples section. Keep it compact.

The sub-agent must explicitly call out mandatory split-page sections and include order from the developer examples template, including sections that are often missing in older docs.

Stage 3: write or update the docs

Using only the distilled outputs from Stage 1 and Stage 2:

Update ./source/_integrations/<domain>.markdown.
Create or update one split page per trigger.
Create or update one split page per condition.
Do not create new action pages.
Do not rewrite existing action pages.
If split pages already exist for triggers or conditions, update them instead of duplicating them.

Hard requirements:

This command documents triggers and conditions only.
Leave already documented actions intact.
If the integration page already references actions, preserve those action references and documented action sections as they are unless the current template clearly requires a mechanical placement change.
In the integration page, if triggers, conditions, and actions all exist and are already documented, you may use {% include integrations/triggers_conditions_actions.md %}.
If actions are not documented, do not add action include lines just because Core has services.
If one or more included categories should be represented individually, include only the applicable lines below, separated by blank lines:
- {% include integrations/triggers.md %}
- {% include integrations/conditions.md %}
- {% include integrations/actions.md %}
If the integration page already has documented actions, insert the trigger and condition Liquid includes above those documented action sections.
Do not remove, rewrite, or reorder existing documented action sections beyond placing the trigger and condition includes above them when needed.
Ensure the integration page has an ## <Integration name> automation examples section that follows the current integration template.
Add that section even if it was missing before the migration.
In that section, example headings must be level-3 headings prefixed with Automation:.
The integration-page automation examples must match the documented trigger and condition split pages and use the same feature names and behavior.
Do not document unsupported Core features.
When documenting a for attribute in options or fields, document its type as string, not time.
Do not use Markdown H1 headings.
Keep blank lines around headings and Liquid blocks.
Follow the Home Assistant YAML style guide for all YAML examples.
In UI options and YAML options sections, list default values when applicable.
Use sentence-style capitalization.
Prefer globally understood wording.
Avoid region-specific household terms.
Avoid invented workflows like “Away mode” unless explicitly framed as user-created.
If using a helper, explicitly say it must be created separately and use {% term helper %} where appropriate.
Do not assume a Labs note is required for actions.
Include integrations/labs_entity_triggers_note.md only where the current template or existing Home Assistant docs pattern actually requires it.
For trigger and condition pages, follow the developer examples template section-for-section unless a section is truly not applicable.
Do not omit a template section just because the older page for this integration did not have it.
Keep include order aligned with the developer examples template.
Keep heading flow aligned with the developer examples template and the headings produced by includes.
Keep UI-step and options-section structure aligned with the developer examples template.
If deviating from the template, do so only for a Core-based reason and keep the deviation minimal.

UI wording requirements:

Do not prefix selected UI items with the domain.
Trigger pages must say: Select what you want to monitor. Under **By target** ...
Condition pages must say: Select what you want to check. Under **By target** ...
In automation examples, do not repeat the domain in UI action names. Use the action label without the Domain: prefix.
If the current UI label is Light: Turn on light, write Turn on light.
If the current UI label would read awkwardly with the domain, such as Lock: Lock lock, write only the non-prefixed label.
Use the action labels from their related strings.json in Core to make sure they match what users see in the UI.

Split-page naming rules:

Triggers: source/_triggers/<domain>.<trigger_key>.markdown
Conditions: source/_conditions/<domain>.<condition_key>.markdown

Use exact Core keys.

Each trigger and condition page must have:

a strong introductory context explaining when it is useful
exactly two concrete automation examples for different use cases

Example rules:

Examples must match what the page claims.
Prefer standard Home Assistant concepts like time, sun, person/zone, notifications, locks, lights, alarm control panels, scripts, and automations.
Do not invent unsupported modes, flows, or features.
Do not imply a helper exists unless you explicitly say it is user-created.
In automation examples, do not list default values such as default for or behavior values.
In automation examples, use the correct full action labels, such as Lock lock or Turn on switch, not shortened labels like Lock or Turn on.

For the examples that use the mobile notification action, use this pattern to refer to the mobile device:

In UI:

- **Action**: Send a notification message
  - **Target**: My Device (`notify.my_device`)

In YAML:

actions:
  - action: notify.send_message
    target:
      entity_id: notify.my_device
    data:
      message: >
        ...

If there are other **Target** items in UI lists, they should be nested with two spaces under the trigger/action/condition above them.

Stage 4: review with a sub-agent

Launch a sub-agent to review the updated files against Core, templates, includes, and developer examples.

It must return only:

Problems found:
- [severity] <file>: <issue>

Passed checks:
- <check>

Required review checks:

integration page uses {% include integrations/triggers_conditions_actions.md %} only when triggers, conditions, and actions are all already documented and that include is actually appropriate
if one or more categories is missing from the documented scope, the integration page uses only the applicable individual include lines with blank lines between them
integration page does not add new action documentation outside the current scope
existing action pages were left intact
existing documented action sections in the integration page were kept intact
trigger and condition Liquid includes were inserted above existing documented action sections when needed
integration page contains the ## <Integration name> automation examples section when required by the current template
integration-page example headings are level 3 and start with Automation:
integration-page automation example content is consistent with the trigger and condition split pages
trigger and condition pages follow the current developer examples template closely
no mandatory trigger or condition template section was omitted without a Core-based reason
trigger and condition pages contain required includes
include order matches the developer examples template
heading levels align with include-generated headings
section order matches the developer examples template
UI wording matches current developer examples
selected item labels do not use Domain: Label
trigger steps use Select what you want to monitor. Under **By target** ...
condition steps use Select what you want to check. Under **By target** ...
automation examples do not use Domain: Label for action names
automation example action names reuse the current non-prefixed UI label form already captured during Stage 1
unavailable / unknown notes are in Good to know
every documented feature exists in Core
no unsupported feature was invented
examples are realistic and globally understandable
in YAML options, for is documented as type: string and the format is explained in the description
UI options and YAML options sections list default values when applicable
automation examples do not list default values such as for for or behavior
automation examples use correct full action labels such as Lock lock or Turn on switch
YAML examples follow the Home Assistant YAML style guide
helper usage, if any, is explicitly framed as user-created
Labs note usage matches the current template and actual feature requirements

Stage 5: fix and re-review

If the review sub-agent reports problems:

fix them
run one more compact review pass
stop only when no material issues remain

Final response

Return:

Summary:
- ...

Files updated:
- ...

Files created:
- ...

Categories intentionally not documented:
- actions: left for later migration unless already documented and preserved

Mismatches found between epic/issue text and Core:
- ...

Assumptions:
- ...