blueprint-authoring
Compose, check, and iterate Amdahl workflow recipes (blueprints) for the console's Workflows surface — and route "make this recur" asks to Routines. Use when the user wants to create / edit / fork / v
SKILL.mdplugins/amdahl-gtm/skills/blueprint-authoring/SKILL.md
GitHubAmdahl blueprint authoring
When the user wants to save a repeatable multi-step workflow as a reusable recipe, or to create / edit / fork / validate an Amdahl blueprint (the console calls them Workflows), your job is to compose and check the DSL body with them, then hand off to the console's Workflows surface — where validate, create, fork, and publish run. Authoring is console-only: the blueprints MCP tool was retired, and the endpoints behind the console are not on the public API (an external API key gets 403 not_on_public_api). Never present an API call as the authoring path.
Route the ask first — Routine or Workflow?
- The user wants a standing, scheduled refresh in plain language ("every Monday, refresh the pipeline report") → don't author a blueprint. Create a Routine with the connected Amdahl MCP
create_routinetool (withname+prompt+cron): a Routine is a cron that fires a Chat — one server-side Master agent turn in a fresh Session — each occurrence.run_routine_nowfires one immediately. (Mindactions_allowedon its config: absent = ALL outbound actions allowed; name a list to narrow,[]to disable.) - The user wants one-shot deep work run server-side → an MCP Chat (
start_chat→ pollget_chat_run→answer_chat_question); setdepth: 'deep'for a thorough investigation. - The user wants the fully-typed, step-by-step contract — declared inputs/outputs, a validated step graph, forkable starters → author a Workflow (blueprint) per this skill: compose + explain the body, then point the user at the console's Workflows surface to validate and save it.
If an MCP call fails on auth, tell the user to run /amdahl-gtm:setup.
Hold this mental model and keep the user on it:
- A blueprint is a structured recipe (a typed DSL artifact) with two ways to run. The platform runs Workflows headlessly (fired from the console, and cron schedules fired server-side); an agent in the console reading the recipe can also walk it interactively, making the primitive calls itself (
data.query,external_search.execute,artifacts.create, ...). - Blueprints are off MCP and off the public API. Never tell the user to author or run a blueprint from an MCP session or an API-key script; from MCP the automation surfaces are Routines (
create_routine) and Chat (start_chat), plus the fast-lanesearch_customerstool for quick synchronous lookups. policy.tool_allowlistis load-bearing on headless runs — the platform derives the run's scopes from it (least-privilege) — and guidance for an interactive walker.timeout_secondsandcost_cap_usdare advisory authoring metadata.- A cookbook recipe/prompt (paste-into-Claude text) is a DIFFERENT thing from an in-app blueprint (the DSL artifact). If the user conflates them, clarify once.
Where each job lives (console Workflows surface)
| Job | Where |
|---|---|
| Browse every blueprint the workspace sees (Amdahl starters + tenant rows) | The Workflows list |
| Read one blueprint's full v1 DSL body | Open it from the list (starters resolve by slug) |
| The 8 step kinds with fields + example bodies | The step-kind reference in the editor (also the DSL reference on docs.amdahl.ai) |
Registered prompt:// fragments |
The fragment browser (filter by scheme; open one for its text) |
| Dry-run a draft body through the moat | The editor's Validate action — returns { valid, errors[] } |
| Persist a new tenant blueprint | Save as draft in the editor |
| Edit a tenant blueprint (content is REPLACE-semantic) | Edit + save (always the whole body) |
| Soft-archive / restore | The blueprint's actions menu |
| Copy a starter or tenant blueprint into a fresh draft | The Fork action (new slug + name) |
| Fire one headless run of a published workflow | Run on the blueprint's page |
The loop you drive
Always: orient -> draft -> hand off to validate -> iterate. Never let the user save before validating.
- Orient. If the user's ask is close to an existing recipe, have them open that starter in the Workflows list (forking beats authoring from scratch) and paste you its body; otherwise pull what you need from the DSL anatomy below.
- Draft. Compose the v1 DSL body in your reasoning loop. Show it to the user, explain the step graph, and self-check it against the anatomy + the error table before handing it over.
- Validate. Have the user paste the body into the console editor and run Validate. Fix the returned
errors[]with them bycode(see the table). Re-validate untilvalid: true. - Create or fork. Save as draft for net-new; or Fork a starter, then edit the fork. The fork lands with a fresh id,
versionreset to1.0.0,status: "draft". - Iterate. Edit, re-validate, re-save the full body. Bump
identity.versionon a real change. Publish when the user is happy.
DSL anatomy (what a valid body needs)
Top-level (strict — no extra keys): schema_version ("1.0.0"), identity, inputs, outputs, policy, trigger, steps, outputs_mapping, optional metadata.
identity:slug([a-z0-9-], 3-60),name(<=80),description(30-500 chars),version(semver). Optionalcategory,tags,icon.inputs: typed declarations (string/integer/number/boolean/date/datetime/enum/json/artifact_ref/artifact_ref_list), each withname(snake_case), optionalrequired, optionalvalidate(e.g.enumneedsvalidate.values;artifact_refneedsvalidate.artifact_type).outputs:kind=artifact(withartifact_type+cardinality) |data(withschema) |side_effect(withcategory). May be[](pure side-effect recipe).steps(non-empty): each haskind, uniqueid, optionaloutput_alias. The 8 kinds:tool— call one op:tool(op id) +args. The workhorse.llm—effort(fast/medium/deep/research) +prompt+output_schema(required); optionalprompt_resources,input_data,temperature.loop—over+as+step, optionalparallel.branch—condition+if_true, optionalif_false.parallel—steps(>=1), optionalmerge.blueprint— compose a sub-blueprint:blueprint+args.transform—input+ JSONataexpression.assert—condition+halt_message.
- References (
$):$inputs.NAME,$STEP_ID/$alias,$alias.field,$now,$today,$random_uuid,$secret.NAME(never goes into prompts),$builtin.X. Prefer referencingoutput_aliasover the raw step id. prompt://<scheme>/<id>in anllmstep'sprompt_resourcesinlines a shared fragment. Two schemes:content_writer/*(grounding_rules, audience_scoping, channel_budget, cta_synthesis, hook_patterns, ...) andresearcher/*(topic_decomposition, evidence_synthesis, confidence_scoring, metric_grounding, document_render, ...). DON'T guess ids — have the user check the console's fragment browser.policy.tool_allowlist(>=1 op id) is required — headless runs derive their scopes from it, so keep it honest.trigger:{ "manual": { "enabled": true } };schedule(cron) also ships, though for a plain-language cadence a Routine is usually the better fit.outputs_mapping: map each declared output name to a$-reference (e.g.{ "report": "$report_id" });{}whenoutputsis[].
A minimal valid body:
{
"schema_version": "1.0.0",
"identity": { "slug": "topic-pulse", "name": "Topic pulse", "description": "Runs a fused internal + external search on a topic and returns the brief. The smallest reusable research recipe.", "version": "1.0.0" },
"inputs": [{ "name": "topic", "type": "string", "required": true, "validate": { "min_length": 3, "max_length": 300 } }],
"outputs": [{ "kind": "data", "name": "brief", "schema": { "type": "object" } }],
"policy": { "tool_allowlist": ["external_search.execute"] },
"trigger": { "manual": { "enabled": true } },
"steps": [{ "id": "pulse", "kind": "tool", "tool": "external_search.execute", "args": { "action": "enrich_topic", "topic": "$inputs.topic" }, "output_alias": "pulse_result" }],
"outputs_mapping": { "brief": "$pulse_result" }
}
Validation errors and how to fix them
The console's Validate (and save) return errors keyed by a stable code:
schema_error— body failed the strict v1 schema (wrong field, missing required, bad enum). Re-check the anatomy.unknown_reference— a$alias.fieldpoints at nothing (usually a typo). Check the step that bound the alias.unknown_fragment— aprompt://id isn't registered (e.g.grounded_rulesvsgrounding_rules). Re-check the fragment browser.duplicate_step_id— two steps share anid(common after copy-paste). Rename one.invalid_tool_id— atool_allowlistentry isn't a real operation id.
Operating rules
- Validate before every save. Walk the
errors[]with the user and fix by code, don't just retry blindly. - Edits are REPLACE-semantic: always work from the WHOLE body, never a partial patch — omitted top-level keys are dropped.
- Prefer forking a starter (
draft-piece,research-report, ...) over authoring from scratch when the ask is close to an existing recipe. Starters are read-only; fork first, then edit the fork. - Never put a literal secret in the body — reference
$secret.NAME. A literal key is stored in plaintext on the artifact. - When the user says "run" the blueprint: publish it in the console, then fire a run from its page (headless) — or, if what they really want is "run this on a cadence," offer a Routine instead (
create_routineover MCP). - When the user asks to do any of this from an MCP-connected chat or with an API key: route them to the console — or to Routines (
create_routine) + Chat (start_chat) for the MCP-native equivalents. - The full narrative guide (mental model, anatomy, two worked examples) lives at
prompts/blueprints/authoring-a-blueprint.md— point the user there for depth.
This skill composes and checks the DSL; it stays thin and defers depth to the guide so it remains correct as the platform's starters + fragments evolve.