Agent Skills & AGENTS.md

Heatwave keeps its AI-agent conventions in version control alongside the code, so every tool that honours the AGENTS.md convention — Claude Code, Cursor, OpenAI Codex CLI, Zed, Aider — reads the same context. This page explains how that system is laid out. It is a map, not the rules themselves: the rules live in the files described below.

The two layers

Layer	File(s)	Purpose
Hard rules	AGENTS.md (with CLAUDE.md a symlink to it)	The always-loaded contract: toolchain pins, hard-block commands, migration/Zeitwerk/commit conventions, and a pointer index to every skill.
Intent-triggered skills	.agents/skills/<name>/SKILL.md	Focused, on-demand playbooks for a specific area (state machines, Turbo streams, migrations, a given external API, etc.). Loaded by the agent only when the task matches.

AGENTS.md is the single source of truth for cross-tool context. CLAUDE.md is a symlink to it so Claude Code picks it up without a second copy drifting.

Where skills live

.agents/skills/<name>/
├─ SKILL.md            # frontmatter (name, description, …) + the playbook body
└─ references/         # progressive-disclosure detail kept out of SKILL.md
.claude/skills         # symlink → ../.agents/skills (Claude Code reads here)
skills-lock.json       # hash-pinned lockfile for vendored third-party skills

First-party skills authored in this repo and third-party skills vendored via skills-lock.json coexist in the same tree, so a single discovery root covers everything. Zed reads .agents/skills/ natively; Claude Code reaches it through the .claude/skills symlink.

Skills follow the Agent Skills standard: each is a directory containing a SKILL.md whose frontmatter carries at least a name (matching the directory) and a description (≤ 1024 chars). Detail beyond ~500 lines moves into references/ per progressive disclosure.

Finding the right skill

The skill index is a table in AGENTS.md, grouped by area (Rails core, Models, Hotwire/UI, CRM, background work, quality, docs, edge/SEO, external CLIs, ops, infra). Before writing code in an unfamiliar area, scan that index and read the matching SKILL.md — skills carry hard-won conventions (strong params, Turbo response patterns, state-machine validations, …) that are easy to rediscover wrongly.

Adding or changing a skill

1. Create .agents/skills/<name>/SKILL.md with agentskills.io frontmatter.
2. Add the skill to the index table in AGENTS.md.
3. Run script/validate_skills.sh — it checks every skill against the spec (frontmatter present, name matches directory and the naming regex, description length) and warns when a SKILL.md exceeds the 500-line best-practice budget.

New rules and conventions are written as skills, not as a separate per-tool config tree. There is no .cursor/rules/ tree any more — everything an agent needs is either a hard rule in AGENTS.md or a skill under .agents/skills/.

Why skills are not in this portal

The skills themselves are agent-targeted instructions — the agents read them straight from the repo, where they sit next to the code they describe. Dumping hundreds of SKILL.md files into a human documentation portal would bury the curated narrative. This overview page is the human-facing entry point; browse the skill bodies in the repo under .agents/skills/.