From 3d9f224eac76b3a72c00c80ec87fc512d37a317f Mon Sep 17 00:00:00 2001
From: Tyler <tyler@crispygoat.com>
Date: Sun, 21 Jun 2026 12:46:52 -0600
Subject: [PATCH] docs(readme): add Skills section linking the 8-skill catalog

---
 README.md | 20 ++++++++++++++++++++
 1 file changed, 20 insertions(+)

diff --git a/README.md b/README.md
index a1d6acd..c45a802 100644
--- a/README.md
+++ b/README.md
@@ -51,6 +51,26 @@ VITE_API_BASE_URL=http://127.0.0.1:8000
 Without that, the UI falls back to its in-memory sample store via the
 existing `data` adapter (parses are disabled).
 
+## Skills
+
+Cyclone ships 8 project-scoped AI-assistant skills under
+[`.superpowers/skills/`](.superpowers/skills/). Each one codifies the
+conventions for a major subsystem so the next contributor (human or
+AI) gets the lay of the land automatically.
+
+| Skill | Owns |
+|-------|------|
+| [`cyclone-spec`](.superpowers/skills/cyclone-spec/SKILL.md) | The SP-N spec → plan → implement → merge flow. |
+| [`cyclone-tests`](.superpowers/skills/cyclone-tests/SKILL.md) | pytest + vitest fixture patterns, prodfiles drop-in. |
+| [`cyclone-edi`](.superpowers/skills/cyclone-edi/SKILL.md) | EDI parser/validator conventions (837P/835/999/270/271/277CA/TA1). |
+| [`cyclone-tail`](.superpowers/skills/cyclone-tail/SKILL.md) | Live-tail streaming wire format and the hook triplet. |
+| [`cyclone-store`](.superpowers/skills/cyclone-store/SKILL.md) | Store write-paths, pubsub event contract, SP21 split map. |
+| [`cyclone-api-router`](.superpowers/skills/cyclone-api-router/SKILL.md) | FastAPI router conventions (`api_routers/`, `api_helpers.py`). |
+| [`cyclone-frontend-page`](.superpowers/skills/cyclone-frontend-page/SKILL.md) | React page conventions (TanStack Query, drawer, URL state). |
+| [`cyclone-cli`](.superpowers/skills/cyclone-cli/SKILL.md) | CLI subcommand conventions (`cli.py`, exit codes, smoke tests). |
+
+Skills auto-load by description match — no slash command needed.
+
 ## Test
 
 ```bash