From 2cce76f46f213f133c2c0becdff0e04ecd7520ab Mon Sep 17 00:00:00 2001 From: Mikkeli Date: Sun, 23 Aug 2026 11:45:40 +0900 Subject: [PATCH] feat: add redirect-skills as a second content type, split into dirs This repo now houses two shapes of authored, version-controlled content: long-form handbooks (retrieved via a KB) and short redirect-skills (deployed into an agent's own skill directory). A redirect-skill's entire job is pointing at a live or handbook source instead of caching an answer that would go stale - the gdext binding for Godot 4 is the first case, since it's pre-1.0 with no existing skill or MCP tool anywhere. Neither shape is consumed directly from this repo: a handbook isn't live until admitted to kb-engineering, a skill isn't live until copied (never symlinked, since an agent may write back to its own skill files) into wherever it actually runs. Handbooks moved from the repo root into handbooks/, for symmetry with skills/ - each content shape now owns its own directory instead of handbooks implicitly owning the root. Co-Authored-By: Claude Sonnet 5 Claude-Session: https://claude.ai/code/session_011EBCcjJvEvhpToahqdsLLA --- README.md | 68 +++++++++++++++---- .../failure-handling.md | 0 .../git-operations.md | 0 skills/gdext-verify-live-docs/SKILL.md | 27 ++++++++ 4 files changed, 83 insertions(+), 12 deletions(-) rename failure-handling.md => handbooks/failure-handling.md (100%) rename git-operations.md => handbooks/git-operations.md (100%) create mode 100644 skills/gdext-verify-live-docs/SKILL.md 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.