Agent skill

Grounding A Design

by andrew-blake in andrew-blake/melcloudhome

A skill your agent uses when about to propose, brainstorm, review or revise a design, fix approach or plan for a feature or behaviour change in this repo, including "brief" or "quick" design…

MITAuto-check passedDevelopment

Install Grounding A Design

skills CLI

$ npx skills add andrew-blake/melcloudhome --skill grounding-a-design -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI

$ gh skill install andrew-blake/melcloudhome grounding-a-design --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy

$ git clone --depth 1 https://github.com/andrew-blake/melcloudhome.git skills-src && mkdir -p .claude/skills && cp -r skills-src/.claude/skills/grounding-a-design .claude/skills/grounding-a-design && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Paste into Claude Code

Install the "grounding-a-design" agent skill from https://github.com/andrew-blake/melcloudhome/tree/main/.claude/skills/grounding-a-design into .claude/skills/grounding-a-design/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "grounding-a-design", then confirm the skill loads.

Claude Code copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

$skill-installer

$skill-installer install https://github.com/andrew-blake/melcloudhome/tree/main/.claude/skills/grounding-a-design

Type this inside Codex. $skill-installer <name> installs a curated skill from openai/skills. The installer writes to $CODEX_HOME/skills (default ~/.codex/skills). Restart Codex if the skill does not show up.

skills CLI

$ npx skills add andrew-blake/melcloudhome --skill grounding-a-design -a codex

Project install goes to .agents/skills/; add -g for ~/.codex/skills/.

GitHub CLI

$ gh skill install andrew-blake/melcloudhome grounding-a-design --agent codex

Project scope by default (.agents/skills/); add --scope user for a personal install.

Manual copy

$ git clone --depth 1 https://github.com/andrew-blake/melcloudhome.git skills-src && mkdir -p .agents/skills && cp -r skills-src/.claude/skills/grounding-a-design .agents/skills/grounding-a-design && rm -rf skills-src

Use ~/.agents/skills/ instead of .agents/skills for a personal install.

Codex skills documentation · loads skills from .agents/skills/

Paste into Codex

Install the "grounding-a-design" agent skill from https://github.com/andrew-blake/melcloudhome/tree/main/.claude/skills/grounding-a-design into .agents/skills/grounding-a-design/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "grounding-a-design", then confirm the skill loads.

Codex copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

skills CLI

$ npx skills add andrew-blake/melcloudhome --skill grounding-a-design -a cursor

Project install goes to .agents/skills/; add -g for ~/.cursor/skills/.

GitHub CLI

$ gh skill install andrew-blake/melcloudhome grounding-a-design --agent cursor

Project scope by default (.agents/skills/); add --scope user for a personal install.

Manual copy

$ git clone --depth 1 https://github.com/andrew-blake/melcloudhome.git skills-src && mkdir -p .cursor/skills && cp -r skills-src/.claude/skills/grounding-a-design .cursor/skills/grounding-a-design && rm -rf skills-src

Use ~/.cursor/skills/ instead of .cursor/skills for a personal install.

Cursor skills documentation · loads skills from .cursor/skills/, .agents/skills/, .claude/skills/, .codex/skills/

Paste into Cursor

Install the "grounding-a-design" agent skill from https://github.com/andrew-blake/melcloudhome/tree/main/.claude/skills/grounding-a-design into .cursor/skills/grounding-a-design/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "grounding-a-design", then confirm the skill loads.

Cursor copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

gemini skills install

$ gemini skills install https://github.com/andrew-blake/melcloudhome.git --path .claude/skills/grounding-a-design

--scope user (default) or --scope workspace; --path is the subfolder of the repo that holds the skill; --consent skips the security confirmation prompt.

skills CLI

$ npx skills add andrew-blake/melcloudhome --skill grounding-a-design -a gemini-cli

Project install goes to .agents/skills/; add -g for ~/.gemini/skills/.

GitHub CLI

$ gh skill install andrew-blake/melcloudhome grounding-a-design --agent gemini-cli

Project scope by default (.agents/skills/); add --scope user for a personal install.

Manual copy

$ git clone --depth 1 https://github.com/andrew-blake/melcloudhome.git skills-src && mkdir -p .gemini/skills && cp -r skills-src/.claude/skills/grounding-a-design .gemini/skills/grounding-a-design && rm -rf skills-src

Use ~/.gemini/skills/ instead of .gemini/skills for a personal install, then run /skills reload.

Gemini CLI skills documentation · loads skills from .gemini/skills/, .agents/skills/

Paste into Gemini CLI

Install the "grounding-a-design" agent skill from https://github.com/andrew-blake/melcloudhome/tree/main/.claude/skills/grounding-a-design into .gemini/skills/grounding-a-design/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "grounding-a-design", then confirm the skill loads.

Gemini CLI copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

GitHub CLI

$ gh skill install andrew-blake/melcloudhome grounding-a-design

Installs for Copilot at project scope by default; add --scope user for a personal install. Preview a skill first with gh skill preview. Needs GitHub CLI 2.90.0 or later (public preview).

skills CLI

$ npx skills add andrew-blake/melcloudhome --skill grounding-a-design -a github-copilot

Project install goes to .agents/skills/; add -g for ~/.copilot/skills/.

Manual copy

$ git clone --depth 1 https://github.com/andrew-blake/melcloudhome.git skills-src && mkdir -p .github/skills && cp -r skills-src/.claude/skills/grounding-a-design .github/skills/grounding-a-design && rm -rf skills-src

Use ~/.copilot/skills/ instead of .github/skills for a personal install. Commit .github/skills so cloud agent and code review can use it.

GitHub Copilot skills documentation · loads skills from .github/skills/, .claude/skills/, .agents/skills/

Paste into GitHub Copilot

Install the "grounding-a-design" agent skill from https://github.com/andrew-blake/melcloudhome/tree/main/.claude/skills/grounding-a-design into .github/skills/grounding-a-design/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "grounding-a-design", then confirm the skill loads.

GitHub Copilot copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

skills CLI

$ npx skills add andrew-blake/melcloudhome --skill grounding-a-design -a opencode

OpenCode documents no install command of its own. Project install goes to .agents/skills/; add -g for ~/.config/opencode/skills/.

GitHub CLI

$ gh skill install andrew-blake/melcloudhome grounding-a-design --agent opencode

Project scope by default (.agents/skills/); add --scope user for a personal install.

Manual copy

$ git clone --depth 1 https://github.com/andrew-blake/melcloudhome.git skills-src && mkdir -p .opencode/skills && cp -r skills-src/.claude/skills/grounding-a-design .opencode/skills/grounding-a-design && rm -rf skills-src

Use ~/.config/opencode/skills/ instead of .opencode/skills for a personal install.

OpenCode skills documentation · loads skills from .opencode/skills/, .claude/skills/, .agents/skills/

Paste into OpenCode

Install the "grounding-a-design" agent skill from https://github.com/andrew-blake/melcloudhome/tree/main/.claude/skills/grounding-a-design into .opencode/skills/grounding-a-design/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "grounding-a-design", then confirm the skill loads.

OpenCode copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

Facts

Skill name: grounding-a-design
GitHub stars: 142
Token cost: ~1.1k tokens
SKILL.md length: 535 words
Files: 2
Skills in repo: 2
Repo updated: Oct 9, 2026
First seen: Oct 7, 2026
Licence: MIT

At a glance

A skill your agent uses when about to propose, brainstorm, review or revise a design, fix approach or plan for a feature or behaviour change in this repo, including "brief" or "quick" design…

Works in 5 steps: Check the premise → Inventory every ADR → Read the other records → …
About to propose
SKILL.md covers Step 1: Check the premise, Step 2: Inventory every ADR, Step 3: Read the other records and Step 4: Delegate the reading…, plus 2 more sections
Calls git and gh

What it does

Grounding A Design is an agent skill from andrew-blake/melcloudhome. Use when about to propose, brainstorm, review or revise a design, fix approach or plan for a feature or behaviour change in this repo, including "brief" or "quick" design requests, read-only design tasks, and answering "what are the weak points?"

Its SKILL.md is about 1.1k tokens, which your agent loads only when the skill is triggered. The skill folder holds 1 other file (for example `grounding-agent-prompt.md`).

It sits in Development, covering Brainstorming and Architecture decision records. It works with Home Assistant. The repository describes itself as: MELCloudHome - Home Assistant Integration. The licence is MIT.

When your agent uses it

About to propose
Revise a design
Plan for a feature
Behaviour change in this repo

Example prompts

“design requests, read-only design tasks, and answering”
“/grounding-a-design”

Workflow steps

5 steps, taken from the step headings in SKILL.md.

Check the premise
Inventory every ADR
Read the other records
Delegate the reading when it's large
Design or review from the constraints

What it can do on your machine

Read from SKILL.md and the folder at commit fdb0b32. It shows what the files ask for, not the result of running them.

Tool permissions
Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.
From allowed-tools in the SKILL.md frontmatter.
Runs code
Shell commands in SKILL.md call:
- git
- gh
From the folder's file list and the shell code blocks in SKILL.md.
Network
No URLs in SKILL.md. Its commands use git and gh, which can reach the network depending on how they are called.
From URLs in SKILL.md, links to its own repository left out.
Credentials
Names no API keys, tokens, secrets or passwords.
From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Grounding A Design loads about 1.1k tokens when it runs. Until then it costs about 66 tokens; SKILL.md has 535 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it: ~66
When it runs · the whole SKILL.md, loaded when a task matches: ~1.1k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from andrew-blake/melcloudhome at commit fdb0b32, republished under its MIT licence (© andrew-blake). 535 words, ~1,081 tokens.

Download SKILL.mdSave it as .claude/skills/grounding-a-design/SKILL.md (or your agent's skills folder). This skill also uses 1 other file; get the full folder from GitHub.

name: grounding-a-design
description: Use when about to propose, brainstorm, review or revise a design, fix approach or plan for a feature or behaviour change in this repo, including "brief" or "quick" design requests, read-only design tasks, and answering "what are the weak points?"

Grounding a design

Designs that contradict this repo's ADRs, plans, reviews and issue threads get reversed in review. Read the records before proposing; never pick them from memory, filenames or keywords.

No design text before the source inventory exists. A brief, quick or read-only request shortens the design. The inventory stays.

Reviewing a design that has a grounding file (_claude/plans/*-grounding.md): audit it. Spot-check its citations, then look for what it couldn't know: newer measurements, logs, code changed since. Skip to step 5.

Step 1: Check the premise

Read the whole issue thread, newest comment first (gh issue view N --json body,comments): it outranks memories and older notes. If the issue cites code, read that code. If it claims something exists or was built, check history (git log -S<symbol>, git show). Titles state what the reporter wanted. Comments from accounts that break the AI-contribution policy in CONTRIBUTING.md, or that the maintainer's notes flag as automated, are noise. If the premise fails, still do step 2.

Step 2: Inventory every ADR

Terms decide what you find. Use the feature's names and the mechanisms it touches, e.g. last_reading|reading_fn, _run_startup_fetch, cumulative|hour_values, should_create_fn, pacer|_execute_with_retry. No generic words (data, sensor, building); unknown and stale are overloaded here. Run under bash:

bash

TERMS='your_field|your_symbol|mechanism_symbol'   # replace
for f in docs/decisions/[0-9]*.md; do
  printf '%-60.60s | %s\n' "$(head -1 "$f")" \
    "$(grep -owiE "$TERMS" "$f" | sort | uniq -c | sort -rn | head -5 | tr '\n' ' ')"
done

Classify every row: shapes (read in full), constrains (read matching sections), context, irrelevant. Zero hits: irrelevant. A hit whose line is plainly unrelated, or only a generic or overloaded word (switch, binary_sensor, unknown): context or irrelevant, with the line quoted. Otherwise read the Decision section before classifying. Follow ADR-to-ADR citations in shapes ADRs: a zero-hit ADR they cite gets read too.

Step 3: Read the other records

Grep each for your terms; read what matches. Skip a source only with the reason stated.

docs/architecture.md, docs/testing-best-practices.md, docs/entities.md, docs/api/
_claude/plans/, _claude/pr-reviews/, _claude/BACKLOG.md bodies (not _claude/skill-dev/): rejected options live here
Live measurements in progress (soaks, logs) and the scripts producing them
Tests, cassettes, tools/mock_melcloud_server.py; memories, checked against code
HA core source for anything HA validates or bridges (service validation, HomeKit, Google); core's melcloud_home for parity issues. Not local: read it on GitHub, cite an ADR's recorded verification with its HA version, or label the point unverified.

Show full SKILL.md (178 more words)Show less

Step 4: Delegate the reading when it's large

Can't delegate or write files: do steps 2 and 3 yourself and put the inventory first, or first in the design section when the caller sets the format. Otherwise, with more than two shapes ADRs or more than one module, give grounding-agent-prompt.md (this directory) to a fresh agent.

Step 5: Design or review from the constraints

Cite the constraint behind each decision. Mark claims measured, read or judgement. Check each weak point before stating it, or label it unverified: with no live system to test against, that is a valid outcome. If none survive, the design holds. A design ends with Open decisions and their options; a review folds the options into its weak points.

Rationalisations

Excuse	Reality
"It's brief / quick / read-only"	Someone acts on it.
"I know which ADRs matter"	Recall found 5 of 13 on #350.
"Filenames show which apply"	Baselines missed constraints that way.
"The memory says X"	A dated claim. Check the code.
"Stated a risk naming an unopened ADR"	Open it, or label it unverified.

Files

SKILL.md and 1 other file in .claude/skills/grounding-a-design of andrew-blake/melcloudhome.

SKILL.md
grounding-agent-prompt.md

Open the folder on GitHubat commit fdb0b32

Compare with similar skills

Grounding A Design next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Grounding A Design compared with similar skills
Skill	Stars	Used in	Tokens	Auto-check	Licence	Repo updated
Grounding A Design this skillandrew-blake/melcloudhome	142	—	~1.1k	Automated safety check: Pass	MIT	today
Brainstormingfeiskyer/claude-code-settings	1.7k	—	~985	Automated safety check: Pass	MIT	12 days ago
Track Ideacdiggins/plato	106	—	~1.3k	Automated safety check: Pass	MIT	13 days ago
Setuprvdbreemen/OTGW-firmware	207	—	~964	Automated safety check: Pass	GPL-3.0	3 days ago
Comet Designrpamis/comet	3.2k	—	~1.9k	Automated safety check: Pass	MIT	today
Implement Next Taskrvdbreemen/OTGW-firmware	207	—	~2.1k	Automated safety check: Pass	GPL-3.0	3 days ago

Similar skills

Brainstorming
feiskyer/claude-code-settings
Explore user intent, requirements, and design options through collaborative dialogue before implementation.
1.7k GitHub stars~985 tokensUpdated 12 days ago
DevelopmentAuto-check passed
Track Idea
cdiggins/plato
Log a new idea into tracker/ with elaboration — assumptions, design decisions, related work links, approach brainstorm, and simplest implementation.
106 GitHub stars~1.3k tokensUpdated 13 days ago
DevelopmentAuto-check passed
Setup
rvdbreemen/OTGW-firmware
One-time project setup for adr-kit. An agent skill from rvdbreemen/OTGW-firmware.
207 GitHub stars~964 tokensUpdated 3 days ago
DevelopmentAuto-check passed
Comet Design
rpamis/comet
A skill your agent uses when full Comet change 已完成 open 阶段但缺少 Superpowers Design Doc，或 design 阶段需要从 OpenSpec 交接包恢复。
3.2k GitHub stars~1.9k tokensUpdated today
Agent WorkflowsAuto-check passed
Implement Next Task
rvdbreemen/OTGW-firmware
Drive the autonomous 2.0.0 ESP32-S3-only async + FreeRTOS migration (epic TASK-865).
207 GitHub stars~2.1k tokensUpdated 3 days ago
DevelopmentAuto-check passed
Lint
rvdbreemen/OTGW-firmware
Lints existing Architecture Decision Records against the four verification gates (Completeness, Evidence, Clarity, Consistency).
207 GitHub stars~4.3k tokensUpdated 3 days ago
DevelopmentAuto-check passed

Questions about Grounding A Design

What does Grounding A Design do?

A skill your agent uses when about to propose, brainstorm, review or revise a design, fix approach or plan for a feature or behaviour change in this repo, including "brief" or "quick" design…. Grounding A Design is an agent skill from andrew-blake/melcloudhome.

When should I use Grounding A Design?

Grounding A Design fits situations like: about to propose; revise a design; plan for a feature; behaviour change in this repo.

How do I install Grounding A Design in Claude Code?

Run `npx skills add andrew-blake/melcloudhome --skill grounding-a-design -a claude-code`. Or copy the skill folder (.claude/skills/grounding-a-design in andrew-blake/melcloudhome) into .claude/skills/grounding-a-design in your project. Claude Code loads it when a task matches its description.

How do I install Grounding A Design in Codex?

Run `npx skills add andrew-blake/melcloudhome --skill grounding-a-design -a codex`. Or copy the skill folder (.claude/skills/grounding-a-design in andrew-blake/melcloudhome) into .agents/skills/grounding-a-design in your project. Codex loads it when a task matches its description.

Can I use Grounding A Design in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add andrew-blake/melcloudhome --skill grounding-a-design -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/grounding-a-design, .gemini/skills/grounding-a-design, .github/skills/grounding-a-design and .opencode/skills/grounding-a-design in your project.

What does Grounding A Design need to run?

Going by SKILL.md and its folder, Grounding A Design needs the command-line tools its instructions call (git and gh).

Does Grounding A Design access the network?

SKILL.md contains no URLs. Its commands use git and gh, which can reach the network depending on how they are called. This is read from the text; nothing was executed.

Is Grounding A Design safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does Grounding A Design use?

Grounding A Design is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Grounding A Design use?

About 1.1k tokens (SKILL.md is roughly 4.3k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to Grounding A Design?

Skills that share tags, products or a category with Grounding A Design: Brainstorming (feiskyer/claude-code-settings, 1.7k stars), Track Idea (cdiggins/plato, 106 stars), Setup (rvdbreemen/OTGW-firmware, 207 stars) and Comet Design (rpamis/comet, 3.2k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Grounding A Design?

andrew-blake (a GitHub user) maintains it in andrew-blake/melcloudhome, which has 142 GitHub stars. The repository holds 2 skills in this directory. The repository was last updated on October 9, 2026.

Source: andrew-blake/melcloudhome on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.

Grounding A Design

Install Grounding A Design

Facts

At a glance

What it does

When your agent uses it

Example prompts

Workflow steps

What it can do on your machine

Tool permissions

Runs code

Network

Credentials

Context cost

Safety

SKILL.md

Grounding a design

Step 1: Check the premise

Step 2: Inventory every ADR

Step 3: Read the other records

Step 4: Delegate the reading when it's large

Step 5: Design or review from the constraints

Rationalisations

Files

Compare with similar skills

Similar skills

Brainstorming

Track Idea

Setup

Comet Design

Implement Next Task

Lint

More from andrew-blake/melcloudhome

PR Body

Questions about Grounding A Design

Install Grounding A Design

Facts

At a glance

What it does

When your agent uses it

Example prompts

Workflow steps

What it can do on your machine

Tool permissions

Runs code

Network

Credentials

Context cost

Safety

SKILL.md

Grounding a design

Step 1: Check the premise

Step 2: Inventory every ADR

Step 3: Read the other records

Step 4: Delegate the reading when it's large

Step 5: Design or review from the constraints

Rationalisations

Files

Compare with similar skills

Similar skills

Brainstorming

Track Idea

Setup

Comet Design

Implement Next Task

Lint

More from andrew-blake/melcloudhome

PR Body

Related

Questions about Grounding A Design