跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
浏览器与自动化

entity-rename

Batch rename Home Assistant entities to follow a consistent naming convention. Discovers entities, proposes renames, executes via HA API, and updates all YAML/TypeScript references automatically. Trigger phrases: "rename entities", "fix entity names", "standardize entity IDs", "entity rename", "clean up names".

dcb · 已有 AI 审核记录

安装与使用

运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。

npx skills add dcb/homeassistant-claude-kit --skill entity-rename

技能说明


name: entity-rename description: > Batch rename Home Assistant entities to follow a consistent naming convention. Discovers entities, proposes renames, executes via HA API, and updates all YAML/TypeScript references automatically. Trigger phrases: "rename entities", "fix entity names", "standardize entity IDs", "entity rename", "clean up names".

Entity Rename Skill

Rename Home Assistant entities to follow a consistent domain.{room}_{descriptor} convention. Updates all YAML automations, scripts, dashboard code, and .storage/ configs automatically.

See references/naming-convention.md for the full naming convention. See docs/solutions/tooling/entity-rename-lessons.md for safety rules from production use.

Step 0: Prerequisites

Verify the environment is ready:

# Check .env exists with HA connection
test -f .env && grep -q HA_TOKEN .env && echo "ENV_OK" || echo "ENV_MISSING"

# Check entity registry exists (needs make pull first)
test -f config/.storage/core.entity_registry && echo "REGISTRY_OK" || echo "REGISTRY_MISSING"

# Check ha-ws is available on HA instance
source .env 2>/dev/null
ssh "$SSH_USER@$HA_HOST" "command -v ha-ws" >/dev/null 2>&1 && echo "HAWS_OK" || echo "HAWS_MISSING"
  • ENV_MISSING: Tell user to run setup-infrastructure first or create .env manually.
  • REGISTRY_MISSING: Tell user to run make pull first.
  • HAWS_MISSING: Install claude-code-ha on the HA instance:
    ssh "$SSH_USER@$HA_HOST" "bash ${HA_REMOTE_PATH}claude-code-ha/install.sh"
    
    See danbuhler/claude-code-ha. Provides ha-api (REST) and ha-ws (WebSocket) CLI tools that run directly on HA.

Step 1: Discovery

Parse local registry files to build a complete entity inventory:

source venv/bin/activate
python tools/entity_explorer.py config/ --full

This uses the device registry join (entity.device_id -> device.area_id) to resolve areas for entities that don't have a direct area_id.

Present the inventory to the user grouped by area/room:

  • Show entity count per area
  • Highlight entities that don't follow the naming convention
  • Flag entities with serial numbers, product names, or non-English names

Step 2: Convention Proposal

For each non-conforming entity, propose a new name following references/naming-convention.md.

Present renames grouped by room. For each room, show:

Living Room (12 entities to rename):
  climate.jch_8862dcd1     -> climate.living_room_ac
  light.hue_ambiance_spot_1 -> light.living_room_spot_1
  ...
  [Approve all] [Edit] [Skip room]

Before proposing each rename:

  1. Verify target entity_id doesn't already exist (safety rule 3)
  2. Detect name collisions requiring two-step renames (safety rule 4)
  3. For each device, enumerate ALL child entities (safety rule 2):
    • battery, calibration, heating, window_detection, anti_scaling, etc.
    • Use device_id from entity registry to find siblings

Save approved renames to a JSON file for batch execution:

# Write to entity-renames.json (or a temp batch file)
python3 -c "
import json
renames = [
    {'old_id': 'climate.jch_8862dcd1', 'new_id': 'climate.living_room_ac'},
    ...
]
with open('rename_batch.json', 'w') as f:
    json.dump(renames, f, indent=2)
"

Step 3: Reference Scanning

Before executing, scan for all references to understand the blast radius:

source venv/bin/activate
python tools/update_yaml_refs.py rename_batch.json --dry-run

This shows which files reference each old entity ID and how many replacements would be made. Present the summary to the user:

climate.jch_8862dcd1: 34 references across 5 files
  config/automations/climate.yaml: 18 refs
  config/scripts/climate.yaml: 8 refs
  config/configuration.yaml: 4 refs
  dashboard/src/lib/entities.ts: 2 refs
  config/automations.yaml: 2 refs

Step 4: Batch Execution

Execute renames in batches, grouped by room. For EACH batch:

4a. Rename entities on HA

Primary (ha-ws via SSH):

# Rename a single entity
ssh "$SSH_USER@$HA_HOST" "source /etc/profile.d/claude-ha.sh; source ${HA_REMOTE_PATH:=/config/}.env; ha-ws entity update sensor.old_name new_entity_id=sensor.new_name"

# Batch rename from a file
cat rename_batch.json | python3 -c "
import json, sys, subprocess
for r in json.load(sys.stdin):
    cmd = f'ha-ws entity update {r[\"old_id\"]} new_entity_id={r[\"new_id\"]}'
    print(f'Renaming: {r[\"old_id\"]} -> {r[\"new_id\"]}')
    subprocess.run(['ssh', '$HA_HOST', f'source /etc/profile.d/claude-ha.sh; source ${HA_REMOTE_PATH:=/config/}.env; {cmd}'])
"

Alternative (Python script with WebSocket fallback):

source venv/bin/activate
python tools/entity_rename.py rename_batch.json

Only needed if SSH is unavailable. The script connects directly via WebSocket.

4b. Update all YAML/TypeScript references locally

python tools/update_yaml_refs.py rename_batch.json

4c. Check for .storage/ files that need patching

If any renamed entities are in Adaptive Lighting zones, patch the zone config on HA via SSH:

# Back up first (safety rule 10)
ssh "$SSH_USER@$HA_HOST" "cp ${HA_REMOTE_PATH}.storage/core.config_entries ${HA_REMOTE_PATH}.storage/core.config_entries.bak"

# Patch AL zone lights arrays
ssh "$SSH_USER@$HA_HOST" "python3 -c \"
import json
with open('${HA_REMOTE_PATH}.storage/core.config_entries') as f:
    data = json.load(f)
for entry in data.get('data', {}).get('entries', []):
    if entry.get('domain') == 'adaptive_lighting':
        opts = entry.get('options', {})
        lights = opts.get('lights', [])
        # Replace old IDs with new IDs
        opts['lights'] = [MAPPING.get(l, l) for l in lights]
with open('${HA_REMOTE_PATH}.storage/core.config_entries', 'w') as f:
    json.dump(data, f, indent=2)
print('AL zones patched')
\""

4d. Record in tracker

Append batch results to entity-renames.json:

阅读完整来源 ↗