skills: Instructions file for Claude Code

CLAUDE.md

Repo Layout

Eval cases live in a top-level evals/<case>/case.yaml, not under skills/. claude plugin eval rejects any eval directory whose first segment names a loaded component directory (commands, skills, agents, hooks, themes, output-styles, monitors, workflows, bin) — and rejects it softly: it warns, falls back to the default evals/, and finds nothing, so cases in the wrong place silently never run. evals/ at the plugin root is the default and needs no experimental.evals key.

SKILL.md is in context on every trigger; references/ load only when read. That is why SKILL.md body size is capped and why domain-niche content belongs in a reference file behind a single routing row, not in the always-loaded table.

Skill Format

Every skill is a SKILL.md with name/description frontmatter. Full authoring constraints: CONTRIBUTING.md. Two rules to check when editing a skill:

• metadata.version must be "0" on new skills — do not edit manually; CI assigns the real version on merge and syncs it into .claude-plugin/plugin.json (.version) and .claude-plugin/marketplace.json (.metadata.version) — three files, one source of truth
• description is capped at 1024 chars and runs close to it — measure the parsed length before adding trigger/symptom bullets: uvx --from skills-ref agentskills read-properties skills/<skill-name> | jq '.description | length'. Its first line tells agents to load the skill before answering or exploring; keep that line when trimming, because small models skip the skill without it (CONTRIBUTING.md has the numbers)

Skill Authoring Principles

The wording of these content-quality principles is mirrored in CONTRIBUTING.md (contributors); each file also carries guidance the other omits. When you change a shared principle, change both — they have drifted before.

• Context window conservation — keep what is HA-specific, cut general programming advice; the test is the content itself, not whether a given model already knows it (skills run on frontier and small local models alike)
• Conciseness — provide patterns and quick-reference tables, not tutorials
• Consistent terminology — one term per concept throughout a skill; contrasting code blocks are # WRONG — why / # RIGHT — why (emoji only in table status columns). A renamed HA term uses the new name and cites the old one with its version ("named Developer Tools before 2026.8") — never a bare swap, since readers on older releases still see the old label
• Symptom-based triggering — the description frontmatter should describe observable agent behaviors that signal the skill is needed
• No tool names — reference HA REST APIs and concepts, never specific MCP tool names (e.g. ha_rename_entity); tool names vary by agent setup