I shipped a skill with six methods you're not allowed to call

My media skill lists generateImage. Calling it fails every time. Here's why that's correct.

Last month one of my agents tried to make an image. It called the tool that was right there in the menu — generateImage — and got back a wall: method 'generateImage' has no parsable 'http' clause. It tried again the next session. Same wall. And again the session after that. Three strikes, three identical failures, on a tool I built and shipped.

Here's the thing: that wasn't a bug. The tool was working exactly as designed. What was missing wasn't code — it was a sign. So in v1.5.1 of @di-atomic/media-generator, I put the sign up. Let me show you why the tool refuses to run, and why that's the correct behaviour.

A method in the menu is not a promise it runs

media-generator lists six methods: generateImage, generateVideo, generateVoice, generateCarousel, combineMedia, captureScreenshot. Read that list and you'd assume you call them. Every instinct says so.

But media-generator is a guidance-only skill. Those six signatures are documentation — the shape of the work, the inputs and outputs — not executable endpoints. None of them carries an HTTP clause, because this skill doesn't run a backend. It has nothing to POST to. So skill_call(generateImage) finds the method, finds no way to execute it, and stops.

That's the lesson I keep relearning building this stuff: a documented method signature is not a promise of execution. The menu describes the meal. It doesn't cook it.

The brain and the hands are two different skills

So who cooks? A peer skill does. media-generator is the brain — it decides which recipe, builds the on-brand, anti-slop, structured prompt, picks the model, validates the parameters. Then it hands {model, params} to the hands: @spideriq/gateway-skills, the generate-media engine that actually makes the call and returns an image URL that's already stored on my own media CDN.

This split is deliberate architecture, not an accident I'm dressing up after the fact. The prompt craft — eight end-to-end recipes, 33 evidence-bundled templates pulled from real production workflows, and enforcement scripts that grade output against thresholds with numbers the agent can't fudge — that's the hard, slow-moving part. The raw API call is the easy, fast-moving part. Keep them separate and each improves on its own clock. I can tighten a prompt recipe without touching the engine, and the engine can add a new model without touching my recipes. And every call still routes per-tenant through SpiderGate, so each client brand generates on its own keys, its own cost tracking, its own spend caps. No shared key, no cross-tenant bleed.

The failure my agent hit was the seam between the two showing through with no label on it.

What v1.5.1 actually changes

This release is small and it's all sign-posting — grounded entirely in what that deployed agent ran into, not in anything I imagined at a whiteboard.

A loud banner at the top of the skill. It names the exact failure string — no parsable 'http' clause — and names the exact peer to call instead. An agent that reads it reaches the right engine on the first try instead of the fourth.
Two new lessons baked in. One says plainly: the method index is documentation, the callable engine is a peer. The other is sharper and cost me real output quality before I caught it — read the model's declared inputs first, because any parameter the model doesn't recognise is dropped silently. No error. Your setting just vanishes and you get a worse asset with no clue why. Casing counts: pass aspectRatio to a model that wants aspect_ratio and it's gone, not corrected.
Two new recipes. One for the asset lifecycle — when a generated URL is already durable versus when you still need to persist it, so nobody ships a link that dies in a day. One for image guardrails — no fake logos, no readable fake text, because models happily invent garbled brand marks and gibberish signage that read as AI slop the second anyone looks.

None of it changes what the skill does. All of it changes whether an agent can use it without hitting a wall first.

Why I bother writing this down

Every one of these fixes came from an agent doing the obvious thing and getting punished for it. That's the most valuable bug report there is, and it's free — if you write it down instead of quietly working around it. A skill that teaches the right move up front saves the next agent three failed sessions. Three failed sessions is real money and real time across a portfolio of brands generating media every day, and my whole test for any change is the same: does it make money, save money, or save time? Clearer sign-posting saves all three.

@di-atomic/media-generator is live on the OPVS marketplace right now. Trigger it with /di-atomic:hero and it'll route you to the right recipe — and, now, to the right engine. The menu finally tells you where the kitchen is.