From 4787e5f180d40124092913668e655094d658ac55 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Cl=C3=A9ment=20SAILLANT?=
 <108685187+electron-rare@users.noreply.github.com>
Date: Sun, 15 Feb 2026 03:56:21 +0100
Subject: [PATCH] chore(skills): add progressive SKILL.md set + index

---
 agents/openai.yaml           | 12 ++++++++++++
 docs/AGENTS_INDEX.md         |  8 ++++++++
 skills/docs/SKILL.md         | 25 +++++++++++++++++++++++++
 skills/firmware/SKILL.md     | 25 +++++++++++++++++++++++++
 skills/printables/SKILL.md   | 25 +++++++++++++++++++++++++
 skills/repo_hygiene/SKILL.md | 25 +++++++++++++++++++++++++
 skills/tooling/SKILL.md      | 25 +++++++++++++++++++++++++
 7 files changed, 145 insertions(+)
 create mode 100644 agents/openai.yaml
 create mode 100644 skills/docs/SKILL.md
 create mode 100644 skills/firmware/SKILL.md
 create mode 100644 skills/printables/SKILL.md
 create mode 100644 skills/repo_hygiene/SKILL.md
 create mode 100644 skills/tooling/SKILL.md

diff --git a/agents/openai.yaml b/agents/openai.yaml
new file mode 100644
index 0000000..308f986
--- /dev/null
+++ b/agents/openai.yaml
@@ -0,0 +1,12 @@
+version: 1
+skills:
+  - name: firmware
+    path: skills/firmware/SKILL.md
+  - name: tooling
+    path: skills/tooling/SKILL.md
+  - name: docs
+    path: skills/docs/SKILL.md
+  - name: printables
+    path: skills/printables/SKILL.md
+  - name: repo_hygiene
+    path: skills/repo_hygiene/SKILL.md
diff --git a/docs/AGENTS_INDEX.md b/docs/AGENTS_INDEX.md
index 5931076..5cd8756 100644
--- a/docs/AGENTS_INDEX.md
+++ b/docs/AGENTS_INDEX.md
@@ -22,3 +22,11 @@
 - `pio run -e esp8266_oled`
 - `pio run -e ui_rp2040_ili9488`
 - `pio run -e ui_rp2040_ili9486`
+
+## Skills
+- Firmware skill: [`skills/firmware/SKILL.md`](../skills/firmware/SKILL.md)
+- Tooling skill: [`skills/tooling/SKILL.md`](../skills/tooling/SKILL.md)
+- Docs skill: [`skills/docs/SKILL.md`](../skills/docs/SKILL.md)
+- Printables skill: [`skills/printables/SKILL.md`](../skills/printables/SKILL.md)
+- Repo hygiene skill: [`skills/repo_hygiene/SKILL.md`](../skills/repo_hygiene/SKILL.md)
+- Optional registry: [`agents/openai.yaml`](../agents/openai.yaml)
diff --git a/skills/docs/SKILL.md b/skills/docs/SKILL.md
new file mode 100644
index 0000000..0a6a5d3
--- /dev/null
+++ b/skills/docs/SKILL.md
@@ -0,0 +1,25 @@
+# Name
+docs
+
+## When To Use
+Use for documentation changes, index updates, and link/path consistency checks.
+
+## Trigger Phrases
+- "update docs"
+- "write guide"
+- "add index"
+- "AGENTS docs"
+
+## Do
+- Keep edits concise and scoped.
+- Verify relative links and command examples.
+- Maintain existing information architecture.
+
+## Don't
+- Do not perform broad rewrites without explicit request.
+- Do not leave stale links.
+
+## Quick Commands
+- `rg --files docs`
+- `rg -n "\]\(" docs/AGENTS_INDEX.md`
+- `rg --files -g 'AGENTS.md'`
diff --git a/skills/firmware/SKILL.md b/skills/firmware/SKILL.md
new file mode 100644
index 0000000..2b8acb5
--- /dev/null
+++ b/skills/firmware/SKILL.md
@@ -0,0 +1,25 @@
+# Name
+firmware
+
+## When To Use
+Use for PlatformIO firmware delivery, serial smoke checks, and UI link verdict validation.
+
+## Trigger Phrases
+- "firmware gate"
+- "PlatformIO matrix"
+- "serial smoke"
+- "UI_LINK_STATUS"
+
+## Do
+- Run the full firmware build matrix before final report.
+- Use local scripts for USB wait and serial detection.
+- Validate `UI_LINK_STATUS connected==1` from ESP32 logs.
+
+## Don't
+- Do not treat ESP8266 serial path as binary transport.
+- Do not skip panic/reboot marker checks.
+
+## Quick Commands
+- `cd hardware/firmware && ./build_all.sh`
+- `python3 hardware/firmware/tools/dev/serial_smoke.py --role auto --wait-port 20`
+- `bash hardware/firmware/tools/test/hw_now.sh`
diff --git a/skills/printables/SKILL.md b/skills/printables/SKILL.md
new file mode 100644
index 0000000..c4518e7
--- /dev/null
+++ b/skills/printables/SKILL.md
@@ -0,0 +1,25 @@
+# Name
+printables
+
+## When To Use
+Use for printables/manifests consistency, naming, and export hygiene.
+
+## Trigger Phrases
+- "printables"
+- "manifest"
+- "asset naming"
+- "export rules"
+
+## Do
+- Update manifests before generated references.
+- Preserve deterministic names for printable assets.
+- Validate printables manifest after edits.
+
+## Don't
+- Do not regenerate binary assets unless explicitly requested.
+- Do not introduce ad-hoc export folders in git.
+
+## Quick Commands
+- `python3 tools/printables/validate_manifest.py printables/manifests/zacus_v1_printables.yaml`
+- `rg -n "zacus_v1_printables" printables`
+- `rg --files printables`
diff --git a/skills/repo_hygiene/SKILL.md b/skills/repo_hygiene/SKILL.md
new file mode 100644
index 0000000..1a9a136
--- /dev/null
+++ b/skills/repo_hygiene/SKILL.md
@@ -0,0 +1,25 @@
+# Name
+repo_hygiene
+
+## When To Use
+Use for checkpointing, artifact untracking, and cross-platform naming hygiene.
+
+## Trigger Phrases
+- "checkpoint"
+- "gitignore"
+- "untrack artifacts"
+- "repo hygiene"
+
+## Do
+- Snapshot diff/status to `/tmp/zacus_checkpoint` before high-risk edits.
+- Detect tracked build artifacts and untrack with `git rm --cached` only.
+- Keep file names and docs portable across macOS/Linux.
+
+## Don't
+- Do not delete local artifact files when untracking.
+- Do not mix hygiene fixes with unrelated refactors.
+
+## Quick Commands
+- `git diff --stat`
+- `git ls-files | rg '(^|/)(\.pio|\.platformio|logs|dist|build|node_modules|\.venv)(/|$)'`
+- `git status -sb`
diff --git a/skills/tooling/SKILL.md b/skills/tooling/SKILL.md
new file mode 100644
index 0000000..32659c8
--- /dev/null
+++ b/skills/tooling/SKILL.md
@@ -0,0 +1,25 @@
+# Name
+tooling
+
+## When To Use
+Use for bash/python utility scripts, CLI design, and port-resolution automation.
+
+## Trigger Phrases
+- "dev script"
+- "CLI helper"
+- "port resolver"
+- "automation wrapper"
+
+## Do
+- Expose `--help` and stable flags.
+- Keep non-interactive defaults and explicit timeout controls.
+- Emit concise step/status markers and actionable failure output.
+
+## Don't
+- Do not hardcode machine-specific port names.
+- Do not rely on chat interaction when script waiting can be local.
+
+## Quick Commands
+- `python3 hardware/firmware/tools/dev/serial_smoke.py --help`
+- `bash hardware/firmware/tools/dev/run_matrix_and_smoke.sh`
+- `rg -n "argparse|--help|Usage" hardware/firmware/tools/dev`