Merge branch 'feat/redirect-skills-and-handbooks-dir'

Adds redirect-skills as a second content type alongside handbooks,
and splits both into their own directories (handbooks/, skills/).
First redirect-skill: gdext-verify-live-docs.

README.md

@@ -1,14 +1,24 @@
 # Handbooks
 
-Instance-agnostic reference material for coding agents — the verbose, citable kind that belongs in
-a retrieval store, not in a skill.
+Instance-agnostic reference material for coding agents, in two shapes: long-form **handbooks** meant
+for a retrieval store, and short **redirect-skills** meant to be deployed into an agent's own skill
+directory. Both are authored and version-controlled here; neither is consumed directly *from* here —
+a handbook isn't live until admitted to a KB, a skill isn't live until deployed to wherever it
+actually runs.
 
 ## What goes here
 
-- Public standards, style guides, and conventions that apply regardless of which box or project is
-  running — general git operations, language style guides, CERT/MISRA-style rulebooks.
-- Long-form and specific. A handbook can be as detailed as it needs to be; nothing here is loaded
-  into a model's context wholesale, so length carries no per-turn tax.
+- **Handbooks: public standards, style guides, and conventions** that apply regardless of which box
+  or project is running — general git operations, language style guides, CERT/MISRA-style rulebooks.
+  Long-form and specific; nothing here is loaded into a model's context wholesale, so length carries
+  no per-turn tax.
+- **Redirect-skills: short, prescriptive, and specifically pointer-shaped** — their entire job is
+  telling an agent to verify against a live or handbook source rather than trust its own recall,
+  for domains that churn too fast for a stored answer to stay correct (`gdext-verify-live-docs` is
+  the first: gdext is pre-1.0, so the skill points at `docs.rs/gdext` and the `godot-rust` book
+  instead of encoding any API surface as text). **Not** a home for full procedural skills that encode
+  real workflow knowledge of their own (a debugging methodology, a review checklist) — those still
+  belong wherever they're consumed, authored there directly.
 
 ## What does not go here
 
@@ -16,17 +26,24 @@ a retrieval store, not in a skill.
   box's PR checklist — that's instance-bound and belongs in that project's own KB corpus instead
   (the `engineering` corpus, for
   [halogen](https://git.novoyuuparosk.org/mikkeli/halogen-workstation-roadmap)).
-- **Short, prescriptive procedures achievable within a context window or two.** That's a skill, not
-  a handbook — it gets loaded, not retrieved. See `skills/` in the halogen-workstation-roadmap repo
-  for the sibling convention.
+- **Full procedural skills that aren't redirect-shaped.** Genuine workflow knowledge — a debugging
+  methodology, a review checklist, anything that *is* the content rather than pointing at it — still
+  belongs where it's consumed: the shared, git-tracked `skills/` at halogen-workstation-roadmap's
+  root (OpenCode, Codex, Claude Code, via `--link`), or authored directly by an agent into its own
+  runtime skill directory (hermes' per-profile home isn't git-tracked at all).
 - **The retrieval store itself.** This repo holds the source-of-truth markdown a human has vouched
   for. The chunked, embedded index built from it is derived and rebuildable state — it lives beside
   whichever KB is consuming it, never committed here.
+- **The deployed copy of a skill.** This repo holds the authored source; the running copy lives
+  wherever the consuming agent actually reads skills from, deployed by copy (never symlink — an
+  agent may write back to its own skill files, which a symlink would corrupt at the source).
+  Deployment tooling lives with the consumer, not here.
 
 ## Format
 
-One markdown file per topic at the repo root. Each file should stand as a single admittable
-document — the same shape a human vouches for at KB admission time.
+**Handbooks:** one markdown file per topic under `handbooks/`. Each file should stand as a single
+admittable document — the same shape a human vouches for at KB admission time. (Redirect-skills live
+under `skills/` instead, with their own format — see below.)
 
 Each file opens with a small flat YAML frontmatter block — `title` and `collections` only, no nested
 structure, so it stays greppable without a YAML dependency (same reasoning `index.py` itself gives
@@ -54,7 +71,7 @@ Markdown needs no conversion and no extraction verifier — admit it straight fr
 `title`/`collections` from the frontmatter instead of retyping them:
 
 ```bash
-F=~/dev/handbooks/git-operations.md
+F=~/dev/handbooks/handbooks/git-operations.md
 TITLE=$(sed -n '/^---$/,/^---$/{/^title:/s/^title:[[:space:]]*//p}' "$F")
 COLLECTIONS=$(sed -n '/^---$/,/^---$/{/^collections:/s/^collections:[[:space:]]*//p}' "$F" \
   | tr -d '[]' | tr ',' '\n' | sed 's/^ *//;s/ *$//')
@@ -75,6 +92,23 @@ the only record of which revision a chunk reflects, which is also why editing a
 itself update the corpus — re-admission is deliberate, a fresh claim about a specific version of a
 document, not something that should happen automatically on every commit.
 
+## Redirect-skills
+
+Live under `skills/<name>/SKILL.md` — the same `skills/<name>/SKILL.md` shape every consuming agent
+already expects, so a skill here copies straight across with no reshaping. Frontmatter is `name` +
+`description` (the Agent Skills standard, not this repo's `title`/`collections`): `description` is
+what a consuming agent's own trigger-matching reads to decide relevance, so it needs to name the
+concrete situation the skill applies to, not just summarize the body.
+
+A redirect-skill's body should contain no cacheable domain knowledge — only what to check, where, and
+under what condition to suspect staleness over a code error. If a skill here starts accumulating API
+details "for next time," that's the sign it's stopped being a redirect and started being the exact
+stale cache it exists to avoid.
+
+**Deploying one is out of scope for this repo** — copy the file into wherever the consuming agent
+reads skills from, never symlink (an agent may write back to its own skill files over time, which a
+symlink would corrupt at the vendor source). The deployment tooling itself lives with the consumer.
+
 ## Status
 
 Started 2026-08-21. First handbook, `git-operations.md`, composed 2026-08-21 – 2026-08-22: branching,
@@ -90,3 +124,13 @@ Frontmatter (`title`, `collections`) added to both 2026-08-22, after `--collecti
 this file's own recipe was found to have drifted from `handbooks`, the value actually used at
 admission — the two ingest-time values that describe the document now live with it instead of being
 retyped by hand.
+
+Scope widened 2026-08-22, superseding the same-day note above: this repo now also houses
+**redirect-skills** (`skills/<name>/SKILL.md`) — short, pointer-shaped skills whose job is verifying
+against a live or handbook source rather than caching an answer that would go stale. First one:
+`gdext-verify-live-docs`, for `gdext` (Rust bindings for Godot 4, pre-1.0, no existing skill or MCP
+tool anywhere). Full procedural skills — genuine workflow knowledge, not a pointer — still don't
+belong here; they're authored where they're consumed, same as before.
+
+Handbooks moved from the repo root into `handbooks/` the same day, for symmetry with `skills/` —
+each content shape gets its own directory rather than handbooks implicitly owning the root.

skills/gdext-verify-live-docs/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: gdext-verify-live-docs
+description: Verify gdext (Rust bindings for Godot 4) API usage against live docs before writing code. Use whenever writing, reviewing, or debugging Rust code that uses the gdext crate — GodotClass derives, node registration, signals, exported properties, or any gdext-specific macro or trait.
+---
+
+# gdext: verify against live docs, don't trust recall
+
+`gdext` is pre-1.0 and under active development — breaking changes between versions are routine, not
+exceptional. Training-data recall of its API is likely to be stale in exactly the way that looks
+correct: a plausible macro invocation or trait bound that compiled against an earlier version and
+silently doesn't against the one actually in use.
+
+**Before writing gdext-specific code (a `#[derive(GodotClass)]`, `#[godot_api]` block, signal
+registration, an exported property, or any other gdext macro/trait), check the version actually
+pinned in the project's `Cargo.toml`, then verify the API against:**
+
+- `https://docs.rs/gdext` — pin the query to the pinned version, not `/latest`, if the two differ.
+- `https://godot-rust.github.io/book` — the official book; tutorials and patterns change with the
+  crate, so prefer the version-matched section over a remembered pattern.
+
+If a build fails on a gdext API call that looks like it should work, the first hypothesis is a
+version mismatch between what's remembered and what's pinned — check the docs at the pinned version
+before assuming the code is wrong.
+
+Do not treat this skill as a place to cache gdext API details for next time. Anything gdext-specific
+written here would go stale the same way recall does — the whole point is redirecting to a source
+that stays current on its own.