From 3b9bf943535b0a8f98742eabf41503ffecb2e356 Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 3 Sep 2026 01:06:26 +0000 Subject: [PATCH] docs(skills): admit hand-authored reference files under `references/` MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The catalog anatomy in `skills/README.md` reserved `references/` for the generated `_index.md` alone and assigned every hand-authored per-topic file to `rules/`. Three published skills already keep hand-authored anchors under `references/` (`objectstack-data/references/data-hooks.md`, `objectstack-platform/references/plugin-hooks.md`), each linked directly from its own `SKILL.md` and cited by path from sibling packages, so the anatomy described a layout the catalog does not have. Amend the anatomy rather than move the files: the reader reaches the same text either way, and a move would be a multi-package rename with binding checks and ceiling-row renames for zero reader value. `_index.md` keeps its "generated — do not hand-edit" line and its `gen:skill-refs` pointer, byte-identical; `rules/` keeps its per-topic role. The requirement travels with the permission: a hand-authored reference file must be linked from `SKILL.md`. Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_01LraLgQVGq8egUwfYZpbYt1 --- skills/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/skills/README.md b/skills/README.md index e4f9f45fd1..2940ce527d 100644 --- a/skills/README.md +++ b/skills/README.md @@ -52,7 +52,7 @@ apps too). ``` skills// ├── SKILL.md # frontmatter + prose guide -├── references/ +├── references/ # may also hold hand-authored reference files linked from SKILL.md │ └── _index.md # generated pointers into @objectstack/spec sources │ # (pnpm --filter @objectstack/spec gen:skill-refs — do not hand-edit) ├── rules/ # (optional) detailed per-topic rule files linked from SKILL.md