# Home Assistant Dashboard Designer (Codex Skill)
This directory contains the `homeassistant-dashboard-designer` Codex skill, stored in-repo so it can be shared with the community.
### Quick navigation
- You are here: `codex_skills/homeassistant-dashboard-designer/`
- [Repo overview](../../README.md) | [Codex skills](../README.md) | [Dashboards](../../config/dashboards/README.md) | [Issues](https://github.com/CCOSTAN/Home-AssistantConfig/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc)
## What This Skill Does
- Enforces a constrained Lovelace design system (button-card first, minimal card-mod, grid/vertical-stack layout rules).
- Encourages centralized templates and deterministic YAML output.
- Treats Stitch MCP output as inspiration only and translates ideas into safe Lovelace YAML.
Skill source of truth inside this folder:
- `SKILL.md`
- `agents/openai.yaml`
- `references/dashboard_rules.md`
- `scripts/validate_lovelace_view.py`
## Install (Local Codex)
Codex loads skills from your local Codex skills directory.
1. Copy this folder into your Codex skills directory as:
- `~/.codex/skills/homeassistant-dashboard-designer/` (Linux/macOS)
- `%USERPROFILE%\\.codex\\skills\\homeassistant-dashboard-designer\\` (Windows)
2. Restart your Codex session/editor so it re-indexes skills.
## Stitch MCP Install (Design Inspiration)
Stitch is optional and used only for design inspiration. To enable it, add a Stitch MCP server entry to your Codex config.
1. Set an environment variable with your API key:
- `STITCH_API_KEY=`
2. Add this to your `~/.codex/config.toml`:
```toml
[mcp_servers.stitch]
url = "https://stitch.googleapis.com/mcp"
env_http_headers = { "X-Goog-Api-Key" = "STITCH_API_KEY" }
http_headers = { "Accept" = "application/json" }
```
## Usage
Invoke in chat:
- `$homeassistant-dashboard-designer`
Then describe what you want in natural language (what to change + where + any constraints). The skill will infer the structured intent internally and enforce the button-card-first / layout constraints defined in `SKILL.md`.
Workflow notes:
- This skill uses direct updates for `config/dashboards/**` (no staged rollout workflow in-skill).
- It requires post-edit validation in this order:
- `pwsh -NoProfile -File tools/validate_dashboards.ps1`
- `pwsh -NoProfile -File tools/ha_ui_smoke.ps1`
- `python codex_skills/homeassistant-dashboard-designer/scripts/validate_lovelace_view.py `
Examples:
- "Refactor `config/dashboards/infrastructure/partials/mariadb_sections.yaml` to match the existing Infrastructure design language. Preserve existing templates and keep diffs small."
- "Add a new Infrastructure view for Docker containers using the same layout rules as the other views (4 columns desktop / 2 columns mobile)."
Optional:
- If you already have an entity list, include it.
- If you do not, enable the Home Assistant MCP so Codex can validate entity IDs/services against your live HA instance (recommended).
## Home Assistant MCP (Built-In) Enablement
The Home Assistant MCP lets Codex validate entity IDs and service calls against your *real* HA instance before it edits YAML.
1. Create a Home Assistant Long-Lived Access Token (Profile page in HA).
2. Set an environment variable (do not commit tokens):
- `HOMEASSISTANT_MCP_AUTH=Bearer `
3. Add this to your `~/.codex/config.toml`:
```toml
[mcp_servers.homeassistant]
url = "http://:8123/api/mcp"
env_http_headers = { "Authorization" = "HOMEASSISTANT_MCP_AUTH" }
```
Notes:
- Use `https://` if your HA is behind TLS.
- Keep tokens in environment variables, not in files under git.
### Notes
- This skill intentionally contains no secrets. Configure MCP credentials via environment variables in your local Codex setup.
**All of my configuration files are tested against the most stable version of home-assistant.**
**Still have questions on my Config?**
**Message me on X :** [](https://www.x.com/ccostan)
**Still have questions on my Config?** 
