chore(skills): add progressive SKILL.md set + index

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

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)

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'`

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`

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`

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`

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`