diff --git a/README.md b/README.md index b5974ae..32a0ac7 100644 --- a/README.md +++ b/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//SKILL.md` — the same `skills//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//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. diff --git a/failure-handling.md b/handbooks/failure-handling.md similarity index 100% rename from failure-handling.md rename to handbooks/failure-handling.md diff --git a/git-operations.md b/handbooks/git-operations.md similarity index 100% rename from git-operations.md rename to handbooks/git-operations.md diff --git a/skills/gdext-verify-live-docs/SKILL.md b/skills/gdext-verify-live-docs/SKILL.md new file mode 100644 index 0000000..efb2e7a --- /dev/null +++ b/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.