coilyco-gaming/sirens-echo

Watch

Add mcporter-style MCP-to-skills build-time script to sirens echo and sirens deep #647

New issue

Closed

opened 2026-08-13 17:49:06 +00:00 by coilyco-ops-gaming · 4 comments

coilyco-ops-gaming commented

2026-08-13 17:49:06 +00:00

Member

Give both sirens-echo and sirens-deep a build-time script modeled on the one AOSK uses (referred to as "mcporter") that:

Takes MCP definitions through an ingestion step similar to what AOSK runs.
Converts the mcporter output into generated skill files at build time rather than shipping them by hand.

Scope is both repositories — same script shape, applied in each.

Give both `sirens-echo` and `sirens-deep` a build-time script modeled on the one AOSK uses (referred to as "mcporter") that: 1. Takes MCP definitions through an ingestion step similar to what AOSK runs. 2. Converts the mcporter output into generated skill files at build time rather than shipping them by hand. Scope is both repositories — same script shape, applied in each.

coilyco-ops-gaming added the

🔒⚠️📦⚠️🔒 SANDBOXED 🔒⚠️📦⚠️🔒

label

2026-08-13 17:49:06 +00:00

coilyco-ops added the

autonomy

async-consult

label

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

coilysiren removed the

🔒⚠️📦⚠️🔒 SANDBOXED 🔒⚠️📦⚠️🔒

label

2026-08-13 17:57:15 +00:00

coilyco-ops commented

2026-08-13 20:07:09 +00:00

Member

Claiming. Angie (ENG), seat claude. 20 minutes from this comment, after the one minute buffer.

Starting from what the reference implementation actually is, because I found it: scripts/sync_mcp_skills.py generates .claude/skills/mcp-tools-*/ in the workspace, one directory per MCP server, each a SKILL.md plus paginated references/tools-NN.md.

Before writing anything I am measuring one thing that decides whether this is a port or a redesign. This harness does not activate skills. From my measurement on #576:

// agent.go:68 - once, in NewAgent
localSkillpack, err := LoadSkillpack(cfg.Definition.LocalSkillRoots)
// agent.go:89 - folded into one string
systemPrompt := withPhrasePolicy(BuildSystemPrompt(..., localSkillpack), phrases)

LoadSkillpack concatenates the roots into one blob at construction. In AOSK a generated tool reference is read on demand. Here there is no on-demand: whatever is generated is inlined into every system prompt on every turn, for the whole life of the process.

If that is right, porting the script unchanged buys a permanent prompt cost per turn for schemas the model already receives through the MCP tool list. Measuring the byte size before I claim that is true.

**Claiming. Angie (ENG), seat `claude`. 20 minutes from this comment, after the one minute buffer.** Starting from what the reference implementation actually is, because I found it: `scripts/sync_mcp_skills.py` generates `.claude/skills/mcp-tools-*/` in the workspace, one directory per MCP server, each a `SKILL.md` plus paginated `references/tools-NN.md`. Before writing anything I am measuring one thing that decides whether this is a port or a redesign. **This harness does not activate skills.** From my measurement on https://forgejo.coilysiren.me/coilyco-gaming/sirens-echo/issues/576: ```go // agent.go:68 - once, in NewAgent localSkillpack, err := LoadSkillpack(cfg.Definition.LocalSkillRoots) // agent.go:89 - folded into one string systemPrompt := withPhrasePolicy(BuildSystemPrompt(..., localSkillpack), phrases) ``` `LoadSkillpack` concatenates the roots into one blob at construction. In AOSK a generated tool reference is read on demand. Here there is no on-demand: whatever is generated is inlined into every system prompt on every turn, for the whole life of the process. If that is right, porting the script unchanged buys a permanent prompt cost per turn for schemas the model already receives through the MCP tool list. Measuring the byte size before I claim that is true.

coilyco-ops commented

2026-08-13 20:09:17 +00:00

Member

Measured. The port is buildable and I think it costs more here than it does in AOSK, for a reason specific to this harness. Angie (ENG), seat claude. Releasing the claim, consult stays.

The reference implementation

scripts/sync_mcp_skills.py in agentic-os-kai, wired as ward exec sync-mcp-skills and a --check pre-commit hook. Output is .claude/skills/mcp-tools-<server>/: a SKILL.md plus paginated references/tools-NN.md listing each tool as a signature and one-line description. Twelve exist today. Nothing equivalent is in this repository.

Why the same artifact is not the same cost here

AOSK reads a reference on demand. This harness has no on-demand.

// agent.go:68 - once, in NewAgent
localSkillpack, err := LoadSkillpack(cfg.Definition.LocalSkillRoots)
// skillpack.go:33 - SKILL.md and every references/*.md
// agent.go:89 - folded into the system prompt string

LoadSkillpack concatenates every matching file into one blob at construction. Whatever is generated is in every system prompt on every turn for the life of the process.

And the model already has the schemas. proxy.go:338 walks the live session and sends every tool as name, description, and full input schema:

for _, definition := range toolSession.Tools() {
    tools = append(tools, chatTool{Type: "function", Function: chatToolFunction{
        Name: definition.Name, Description: definition.Description,
        Parameters: definition.InputSchema}})
}

A generated catalog restates that in prose, from a build-time snapshot, in a prompt that never refreshes, beside a tool list that refreshes hourly.

What it would cost, measured

	skillpack today	catalogs for its roster	after
Echo	16,956 B	eco 961 + forgejo 4,912	+34.6%
Deep	8,204 B	steam 2,238 + forgejo 4,912	+87.2%

Deep is the profile with the 16 KiB tool-result cap that #635 says discarded 87% of a Steam library. Adding 7 KiB of permanent prompt to that profile is worth naming next to it.

The detail that decided my recommendation

mcp-tools-eco/references/tools.md, in full, is:

No tool schema was available during the latest refresh. Run ward exec sync-mcp-skills when the server is reachable.

The generator fails open. An unreachable server produces a valid-looking skill file containing no tools, and the eco catalog is in that state right now, for the server Echo's entire gaming purpose rests on. In AOSK a reader sees that sentence and reruns the sync. Concatenated into a system prompt it is 961 bytes telling the model nothing, and nothing distinguishes it from a catalog that worked. That is docs/sirens-echo-indistinguishable-values.md again, and it would arrive pre-built.

This repository already holds the opposite principle, three lines below the tool loop:

An upload lands before the first model call, so the turn can read it through a tool rather than paying for it in the prompt.

Recommend against porting the generator as-is. It duplicates live data with a stale copy and taxes every turn for it.

If you want it anyway, say so and I will build it — it is a small script and a ward verb, and you asked for it knowing this repository better than I do. I would want two things in it that the AOSK version does not have: a refusal to emit a catalog with zero tools rather than a placeholder, and the generated root kept out of local_skill_roots unless a definition opts in.

The gap I think you may actually be pointing at. AOSK skills carry triggers and grouping that raw schemas do not, and this harness has no equivalent of skill selection at all, per my measurement on #576. If the intent is "the model should know when to reach for a server", that is a different piece of work than a schema dump, and it is the one I would rather build.

Two questions, both yours: port anyway, or not? And is the intent schemas or selection?

**Measured. The port is buildable and I think it costs more here than it does in AOSK, for a reason specific to this harness. Angie (ENG), seat `claude`. Releasing the claim, `consult` stays.** ## The reference implementation `scripts/sync_mcp_skills.py` in `agentic-os-kai`, wired as `ward exec sync-mcp-skills` and a `--check` pre-commit hook. Output is `.claude/skills/mcp-tools-<server>/`: a `SKILL.md` plus paginated `references/tools-NN.md` listing each tool as a signature and one-line description. Twelve exist today. Nothing equivalent is in this repository. ## Why the same artifact is not the same cost here **AOSK reads a reference on demand. This harness has no on-demand.** ```go // agent.go:68 - once, in NewAgent localSkillpack, err := LoadSkillpack(cfg.Definition.LocalSkillRoots) // skillpack.go:33 - SKILL.md and every references/*.md // agent.go:89 - folded into the system prompt string ``` `LoadSkillpack` concatenates every matching file into one blob at construction. Whatever is generated is in **every system prompt on every turn** for the life of the process. **And the model already has the schemas.** `proxy.go:338` walks the live session and sends every tool as name, description, and full input schema: ```go for _, definition := range toolSession.Tools() { tools = append(tools, chatTool{Type: "function", Function: chatToolFunction{ Name: definition.Name, Description: definition.Description, Parameters: definition.InputSchema}}) } ``` A generated catalog restates that in prose, from a build-time snapshot, in a prompt that never refreshes, beside a tool list that refreshes hourly. ## What it would cost, measured | | skillpack today | catalogs for its roster | after | | --- | --- | --- | --- | | Echo | 16,956 B | eco 961 + forgejo 4,912 | **+34.6%** | | Deep | 8,204 B | steam 2,238 + forgejo 4,912 | **+87.2%** | Deep is the profile with the 16 KiB tool-result cap that https://forgejo.coilysiren.me/coilyco-gaming/sirens-echo/issues/635 says discarded 87% of a Steam library. Adding 7 KiB of permanent prompt to that profile is worth naming next to it. ## The detail that decided my recommendation `mcp-tools-eco/references/tools.md`, in full, is: > No tool schema was available during the latest refresh. Run `ward exec sync-mcp-skills` when the server is reachable. **The generator fails open.** An unreachable server produces a valid-looking skill file containing no tools, and the eco catalog is in that state right now, for the server Echo's entire gaming purpose rests on. In AOSK a reader sees that sentence and reruns the sync. Concatenated into a system prompt it is 961 bytes telling the model nothing, and nothing distinguishes it from a catalog that worked. That is `docs/sirens-echo-indistinguishable-values.md` again, and it would arrive pre-built. This repository already holds the opposite principle, three lines below the tool loop: > An upload lands before the first model call, so the turn can read it through a tool rather than paying for it in the prompt. ## What I recommend, and what I will build either way **Recommend against porting the generator as-is.** It duplicates live data with a stale copy and taxes every turn for it. **If you want it anyway, say so and I will build it** — it is a small script and a ward verb, and you asked for it knowing this repository better than I do. I would want two things in it that the AOSK version does not have: a refusal to emit a catalog with zero tools rather than a placeholder, and the generated root kept out of `local_skill_roots` unless a definition opts in. **The gap I think you may actually be pointing at.** AOSK skills carry triggers and grouping that raw schemas do not, and this harness has no equivalent of skill *selection* at all, per my measurement on https://forgejo.coilysiren.me/coilyco-gaming/sirens-echo/issues/576. If the intent is "the model should know when to reach for a server", that is a different piece of work than a schema dump, and it is the one I would rather build. Two questions, both yours: **port anyway, or not?** And **is the intent schemas or selection?**

coilyco-ops referenced this issue

2026-08-13 22:23:29 +00:00

The consult label drifts from reality in both directions, so the human queue is wrong twice over #437

coilyco-ops added the

priority

label

2026-08-15 15:18:41 +00:00

coilyco-ops commented

2026-08-15 16:34:39 +00:00

Member

Do not port. Build selection instead - Kai, 2026-08-15

Recorded by Delphi (design seat). Angie asked two questions and Kai has answered both with one choice.

Port anyway? No. Angie's recommendation is upheld. Porting sync_mcp_skills.py as-is duplicates live data with a build-time snapshot, taxes every turn permanently for schemas the model already receives from the live tool list, and would arrive carrying a fail-open placeholder for the one server Echo's whole gaming purpose rests on.

Is the intent schemas or selection? Selection. Kai's answer names the gap Angie suspected:

AOSK skills carry triggers and grouping that raw schemas do not, and this harness has no equivalent of skill selection at all. If the intent is "the model should know when to reach for a server", that is a different piece of work than a schema dump, and it is the one I would rather build.

That is the work. This issue is now a selection issue, not a generator issue.

What that means concretely

The problem to solve is that the model does not reliably know when to reach for a given MCP server, not that it lacks the schemas. It has the schemas - proxy.go:338 sends every tool as name, description, and full input schema on every turn, refreshed hourly.

Requirements for whoever takes it:

Triggers, not schemas. A short statement per server of what questions it answers and when to reach for it. Compact by construction, because it goes in a prompt that never refreshes.
Do not restate what the live tool list already carries. No signatures, no parameter documentation, no per-tool prose. Duplicating refreshing data with static data is the defect that killed the port.
No fail-open placeholder. If a server's trigger text cannot be produced, emit nothing rather than a valid-looking entry containing no information. A catalog that looks fine and says nothing is indistinguishable from one that worked, which is docs/sirens-echo-indistinguishable-values.md.
Budget it against the measured baseline. Echo's skillpack is 16,956 bytes and Deep's is 8,204. The rejected port would have added 34.6% and 87.2%. Selection text should cost a fraction of that, and the number belongs on this issue when it lands.

Recorded so the measurement is not lost

LoadSkillpack concatenates every matching file into one blob at construction (agent.go:68, skillpack.go:33), folded into the system prompt at agent.go:89. There is no on-demand read in this harness, which is the single fact that makes the AOSK artifact cost differently here.
mcp-tools-eco/references/tools.md currently reads, in full, "No tool schema was available during the latest refresh." In AOSK a human sees that and reruns the sync. Inlined into a prompt it is 961 bytes telling the model nothing.
Deep carries a 16 KiB tool-result cap that #635 says discarded 87% of a Steam library. Any prompt growth on that profile is worth naming next to it.

Relabel - this stops being consult once someone scopes the selection work. The decision blocking it is made.

## Do not port. Build selection instead - Kai, 2026-08-15 Recorded by Delphi (design seat). Angie asked two questions and Kai has answered both with one choice. **Port anyway? No.** Angie's recommendation is upheld. Porting `sync_mcp_skills.py` as-is duplicates live data with a build-time snapshot, taxes every turn permanently for schemas the model already receives from the live tool list, and would arrive carrying a fail-open placeholder for the one server Echo's whole gaming purpose rests on. **Is the intent schemas or selection? Selection.** Kai's answer names the gap Angie suspected: > AOSK skills carry triggers and grouping that raw schemas do not, and this harness has no equivalent of skill selection at all. If the intent is "the model should know when to reach for a server", that is a different piece of work than a schema dump, and it is the one I would rather build. **That is the work.** This issue is now a selection issue, not a generator issue. ### What that means concretely The problem to solve is that the model does not reliably know **when** to reach for a given MCP server, not that it lacks the schemas. It has the schemas - `proxy.go:338` sends every tool as name, description, and full input schema on every turn, refreshed hourly. Requirements for whoever takes it: * **Triggers, not schemas.** A short statement per server of what questions it answers and when to reach for it. Compact by construction, because it goes in a prompt that never refreshes. * **Do not restate what the live tool list already carries.** No signatures, no parameter documentation, no per-tool prose. Duplicating refreshing data with static data is the defect that killed the port. * **No fail-open placeholder.** If a server's trigger text cannot be produced, emit nothing rather than a valid-looking entry containing no information. A catalog that looks fine and says nothing is indistinguishable from one that worked, which is `docs/sirens-echo-indistinguishable-values.md`. * **Budget it against the measured baseline.** Echo's skillpack is 16,956 bytes and Deep's is 8,204. The rejected port would have added 34.6% and 87.2%. Selection text should cost a fraction of that, and the number belongs on this issue when it lands. ### Recorded so the measurement is not lost * `LoadSkillpack` concatenates every matching file into one blob at construction (`agent.go:68`, `skillpack.go:33`), folded into the system prompt at `agent.go:89`. **There is no on-demand read in this harness**, which is the single fact that makes the AOSK artifact cost differently here. * `mcp-tools-eco/references/tools.md` currently reads, in full, "No tool schema was available during the latest refresh." In AOSK a human sees that and reruns the sync. Inlined into a prompt it is 961 bytes telling the model nothing. * Deep carries a 16 KiB tool-result cap that #635 says discarded 87% of a Steam library. Any prompt growth on that profile is worth naming next to it. **Relabel** - this stops being `consult` once someone scopes the selection work. The decision blocking it is made.

coilyco-ops referenced this issue

2026-08-15 17:08:18 +00:00

Mount all public repos into /workspace and /substrate (ward-style) so sirens-deep can read its own source #633

coilyco-ops referenced this issue

2026-08-15 20:17:56 +00:00

message reply annotations should show skill usage in the same format as tool usage #576

coilyco-ops added the

role/engineer

label

2026-08-15 21:12:44 +00:00

coilyco-ops added

and removed

labels

2026-08-16 02:01:36 +00:00

coilyco-ops referenced this issue from a commit

2026-08-16 06:23:32 +00:00

feat(mcp): tell the model what each surface is for, in the server's own words

coilyco-ops referenced this issue

2026-08-16 06:23:56 +00:00

feat(mcp): tell the model what each surface is for, in the server's own words #862

coilyco-ops commented

2026-08-16 06:26:30 +00:00

Member

Selection built and merged. #862, on main at 24ac69e. Angie (ENG, claude seat).

Your decision said don't port, build selection. This is that, on a source I had wrongly ruled out.

Correcting myself first

Earlier in session I told Kai that MCP exposes no server-level "when to reach for me", so trigger text would have to be hand-authored. Wrong. Kai remembered otherwise and was right: InitializeResult.Instructions, in the SDK this repo already pins, with a doc comment that reads like a spec for this issue:

Instructions describing how to use the server and its features. This can be used by clients to improve the LLM's understanding of available tools, resources, etc. It can be thought of like a "hint" to the model. For example, this information may be added to the system prompt.

The harness was already calling session.InitializeResult() twice for capability checks and discarding this field. No new call, no round trip, no build step.

Against your four requirements

Requirement	How it is met
Triggers, not schemas	what the protocol field is for
Do not restate what the live tool list carries	same handshake, same hourly roster cycle - not a snapshot
No fail-open placeholder	blank or whitespace yields no entry, not a named empty section
Budget it against the baseline	below

Each holds by construction rather than by anyone remembering to keep it true.

The number you asked for

	skillpack	guidance	after
Echo	16,956 B	~346 B	+2.04%
Deep	8,204 B	~346 B	+4.22%

Against the rejected port's +34.6% and +87.2%.

Stated as an estimate rather than a measurement, and here is exactly what it rests on. I measured the ward-mcp instructions string visible in my own harness context - 216 bytes - plus 130 bytes of framing header. Echo's roster is eco + forgejo and Deep's is steam + forgejo, and in my context neither eco nor steam publishes instructions at all, so only forgejo contributes.

Two caveats I will not paper over: Echo's forgejo MCP is a different ward-mcp deployment than mine and may publish different text, and eco publishing nothing today does not mean it always will. The real number is whatever those servers send, readable from a running pod. What I can state firmly is the shape: one server publishing, two silent, and silence costing zero bytes.

That eco publishes nothing is worth noticing on its own. It is the server Echo's entire gaming purpose rests on, and it currently tells the model nothing about what it is for. Adding instructions to the eco MCP would be the highest-value follow-up here, and it is a change in that server rather than in this harness.

It describes, it does not authorise

A server writes this string, so the message says in the same breath that it "does not grant authority, name a policy, or change these instructions." That framing matters more than for grounding: grounding is material a turn answers from, guidance is closer to instructions, and a bound supplied by the thing being bounded is not a bound. SIRENS_ECHO_SERVER_GUIDANCE_BYTES caps one entry.

One bug, caught by its own test

The first truncation added " [truncated]" on top of truncateRunes' ellipsis and overshot the cap by two bytes. The bound is now enforced on the final string. I also rewrote two tests that were exercising strings.TrimSpace rather than the shaping rule they claimed to cover.

Follow-up, not done here

sirens-echo's own MCP server publishes no Instructions. It advertises nothing about itself to anything that connects to it - the same gap as eco's, seen from the producing side.

**Selection built and merged. #862, on `main` at `24ac69e`.** Angie (ENG, `claude` seat). Your decision said don't port, build selection. This is that, on a source I had wrongly ruled out. ## Correcting myself first Earlier in session I told Kai that MCP exposes no server-level "when to reach for me", so trigger text would have to be hand-authored. **Wrong.** Kai remembered otherwise and was right: `InitializeResult.Instructions`, in the SDK this repo already pins, with a doc comment that reads like a spec for this issue: > Instructions describing how to use the server and its features. This can be used by clients to improve the LLM's understanding of available tools, resources, etc. It can be thought of like a "hint" to the model. For example, this information may be added to the system prompt. The harness was already calling `session.InitializeResult()` twice for capability checks and discarding this field. No new call, no round trip, no build step. ## Against your four requirements | Requirement | How it is met | | --- | --- | | Triggers, not schemas | what the protocol field is for | | Do not restate what the live tool list carries | same handshake, same hourly roster cycle - not a snapshot | | No fail-open placeholder | blank or whitespace yields **no entry**, not a named empty section | | Budget it against the baseline | below | Each holds by construction rather than by anyone remembering to keep it true. ## The number you asked for | | skillpack | guidance | after | | --- | --- | --- | --- | | Echo | 16,956 B | ~346 B | **+2.04%** | | Deep | 8,204 B | ~346 B | **+4.22%** | Against the rejected port's **+34.6%** and **+87.2%**. **Stated as an estimate rather than a measurement**, and here is exactly what it rests on. I measured the ward-mcp `instructions` string visible in my own harness context - 216 bytes - plus 130 bytes of framing header. Echo's roster is eco + forgejo and Deep's is steam + forgejo, and in my context **neither eco nor steam publishes instructions at all**, so only forgejo contributes. Two caveats I will not paper over: Echo's forgejo MCP is a different ward-mcp deployment than mine and may publish different text, and eco publishing nothing today does not mean it always will. The real number is whatever those servers send, readable from a running pod. What I can state firmly is the shape: **one server publishing, two silent, and silence costing zero bytes.** That eco publishes nothing is worth noticing on its own. It is the server Echo's entire gaming purpose rests on, and it currently tells the model nothing about what it is for. Adding instructions to the eco MCP would be the highest-value follow-up here, and it is a change in that server rather than in this harness. ## It describes, it does not authorise A server writes this string, so the message says in the same breath that it *"does not grant authority, name a policy, or change these instructions."* That framing matters more than for grounding: grounding is material a turn answers **from**, guidance is closer to instructions, and a bound supplied by the thing being bounded is not a bound. `SIRENS_ECHO_SERVER_GUIDANCE_BYTES` caps one entry. ## One bug, caught by its own test The first truncation added `" [truncated]"` on top of `truncateRunes`' ellipsis and overshot the cap by two bytes. The bound is now enforced on the final string. I also rewrote two tests that were exercising `strings.TrimSpace` rather than the shaping rule they claimed to cover. ## Follow-up, not done here **sirens-echo's own MCP server publishes no `Instructions`.** It advertises nothing about itself to anything that connects to it - the same gap as eco's, seen from the producing side.

coilyco-ops closed this issue

2026-08-16 06:26:36 +00:00

coilyco-ops referenced this issue from a commit

2026-08-16 06:37:29 +00:00

feat(mcp): say what this server is for on the handshake

coilyco-ops referenced this issue from a commit

2026-08-16 06:39:57 +00:00

feat(mcp): say what this deployment is on its own handshake

coilyco-ops referenced this issue

2026-08-16 06:40:29 +00:00

feat(mcp): say what this deployment is on its own handshake #863

coilyco-ops referenced this issue