feat: make the skills real with on-demand reference reads

coilyco-ops commented

2026-08-17 19:51:37 +00:00

Member

Makes the pointers true. SKILL.md stays inline as the index, references become fetchable.

Echo   25777 -> 18839   (-27%)
Deep   14521 -> 12649   (-13%)

The mechanism

A reference is fetchable unless it declares inline: always in its own frontmatter, so the decision about a file lives in the file rather than in a list somewhere else that drifts from it.

The pack ends with a Readable references index carrying each path and its heading, because a file the model cannot see is a file it will not ask for. read_skill takes the path exactly as listed, and an unknown path refuses with the list, because a model that guessed once guesses again.

What stayed inline, and why one of them was not my call

Four declare inline: always:

sirens-echo-knowledge/references/boundaries.md and both capability.md shape refusals. The issue's own warning: a model that has to choose to read its own boundaries may not.
coilyco-org/references/organizations.md joined them because TestTheOrgFactsReachBothPrompts failed when it left. That is the test doing its job: "who do you work for" is not a question the model should have to decide to look up. I had it in the long tail and was wrong.

Moved: links-eco, links-community, object-emoji, scratchpad, community, guardfile.

Kai's note about the trade

"Keep the highest-traffic references inline and move the long tail, rather than moving everything on principle." Taken. An on-demand read costs a tool round and #577 already has Echo's p99 at the 180s ceiling, so the six that moved are the ones a turn can answer without.

The budget drop is recorded

docs/sirens-echo-prompt.md logs raises with their cause. It now logs this drop too: a budget left at the old number banks the saving and spends it again unnoticed, which is the same defect one direction over.

Merge ordering, please read

This branch is cut from main without #916. If PR #926 (the calculator) merges first, this needs a rebase and the two budget numbers go up by 203 each, to 19042 and 12852, because #916 adds a prompt rule. TestRenderedPromptsStayInsideTheirBudget will say so rather than letting it pass quietly. Both PRs also touch the raise log in docs/sirens-echo-prompt.md, in different paragraphs, and docs/sirens-echo-tools.md, in different sections.

Tests

skilltool_test.go covers the split, the index, reading by path, the refusal-with-list, an inline reference not also being fetchable, and a root with nothing to serve offering no tool. skillpack_test.go is updated where it asserted the old inlining.

just gate PASS.

closes #859

Makes the pointers true. `SKILL.md` stays inline as the index, references become fetchable. ``` Echo 25777 -> 18839 (-27%) Deep 14521 -> 12649 (-13%) ``` ## The mechanism **A reference is fetchable unless it declares `inline: always` in its own frontmatter**, so the decision about a file lives in the file rather than in a list somewhere else that drifts from it. The pack ends with a **Readable references** index carrying each path and its heading, because a file the model cannot see is a file it will not ask for. `read_skill` takes the path exactly as listed, and an unknown path refuses **with the list**, because a model that guessed once guesses again. ## What stayed inline, and why one of them was not my call Four declare `inline: always`: * `sirens-echo-knowledge/references/boundaries.md` and both `capability.md` shape refusals. The issue's own warning: a model that has to *choose* to read its own boundaries may not. * `coilyco-org/references/organizations.md` joined them because **`TestTheOrgFactsReachBothPrompts` failed when it left**. That is the test doing its job: "who do you work for" is not a question the model should have to decide to look up. I had it in the long tail and was wrong. Moved: `links-eco`, `links-community`, `object-emoji`, `scratchpad`, `community`, `guardfile`. ## Kai's note about the trade "Keep the highest-traffic references inline and move the long tail, rather than moving everything on principle." Taken. An on-demand read costs a tool round and #577 already has Echo's p99 at the 180s ceiling, so the six that moved are the ones a turn can answer without. ## The budget drop is recorded `docs/sirens-echo-prompt.md` logs raises with their cause. It now logs this drop too: **a budget left at the old number banks the saving and spends it again unnoticed**, which is the same defect one direction over. ## Merge ordering, please read This branch is cut from `main` **without** #916. If PR #926 (the calculator) merges first, this needs a rebase and the two budget numbers go up by 203 each, to 19042 and 12852, because #916 adds a prompt rule. `TestRenderedPromptsStayInsideTheirBudget` will say so rather than letting it pass quietly. Both PRs also touch the raise log in `docs/sirens-echo-prompt.md`, in different paragraphs, and `docs/sirens-echo-tools.md`, in different sections. ## Tests `skilltool_test.go` covers the split, the index, reading by path, the refusal-with-list, an inline reference not also being fetchable, and a root with nothing to serve offering no tool. `skillpack_test.go` is updated where it asserted the old inlining. `just gate` PASS. closes #859

coilyco-ops added 1 commit

2026-08-17 19:51:37 +00:00

feat: make the skills real with on-demand reference reads

ci / image-build (pull_request) Successful in 41s

Details

ci / test (pull_request) Successful in 1m7s

Details

ci / publish-echo-image (pull_request) Has been skipped

Details

ci / publish-observed (pull_request) Has been skipped

Details

4068c149b6

Every reference file was concatenated into the system prompt at boot, so the
pointers were decorative: "Read references/object-emoji.md before ..."
instructed the model to read something already sitting above it in the same
prompt. References were 79% of Echo's prompt and a member asking ping paid for
all of them.

SKILL.md stays inline as the index. A reference is fetchable through read_skill
unless it declares inline: always in its own frontmatter, so the decision about
a file lives in the file.

Four declare it. sirens-echo-knowledge/boundaries.md and both capability.md
shape refusals, and a model that has to choose to read its own boundaries may
not. coilyco-org/organizations.md joined them because TestTheOrgFactsReachBothPrompts
failed when it left, which is that test doing its job: "who do you work for" is
not a question the model should have to decide to look up.

Echo's prompt 25777 to 18839, Deep's 14521 to 12649. The budgets drop with
them and the drop is recorded in docs/sirens-echo-prompt.md, because a budget
left high banks the saving and spends it again unnoticed.

The long tail moved and the load-bearing did not, per Kai's note that an
on-demand read costs a tool round and #577 already has Echo against the turn
ceiling.

An unknown path refuses with the list of readable ones, and the pack indexes
every fetchable reference with its heading, because a file the model cannot see
is a file it will not ask for.

closes #859

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Co-authored-by: Kai Siren <coilysiren@gmail.com>
Co-authored-by: Claude <noreply@anthropic.com>

coilyco-ops requested review from coilysiren

2026-08-17 19:51:37 +00:00

coilyco-ops referenced this pull request

2026-08-17 19:51:58 +00:00

Skills are skill-shaped directories, not skills: every reference file is inlined into every prompt #859

coilyco-ops added 1 commit

2026-08-17 20:31:22 +00:00

Merge main: keep both in-process tools and re-derive the budgets

ci / image-build (pull_request) Successful in 38s

Details

ci / test (pull_request) Successful in 1m3s

Details

ci / publish-echo-image (pull_request) Has been skipped

Details

ci / publish-observed (pull_request) Has been skipped

Details

94b6798233

main gained the calculator (#916) and the ticket validity checks (#852) while
this branch was open. Six conflicts, all from the two branches editing the same
prompt-shaped surfaces.

The provider list keeps both registrations. The rendered prompts are generated,
so they were regenerated rather than hand-merged, and the budgets come from the
regenerated sizes: 19042 and 12852. Those are exactly the numbers this PR
predicted for the post-#916 rebase, which is the arithmetic checking out rather
than a coincidence.

Both docs pages carried two features' worth of new prose after the merge and
went over the 8000-char band cap. sirens-echo-tools.md was rebuilt from main so
the calculate section is untouched, and the read_skill entry is cut to the
mechanical facts, with the reason living on sirens-echo-prompt.md where the
budget drop is already recorded. Five restatements elsewhere on the two pages
were compressed to make room. No live fact was dropped.

Co-authored-by: Kai Siren <coilysiren@gmail.com>
Co-authored-by: Claude <noreply@anthropic.com>