Index of every page on this site: llms.txt
All skills
segmently-ai avatar

/screen-block-builder

@f3f9f19
Run it yourself

Author, validate, preview, and publish reusable Segmently strategy block examples through the public CLI and an exact runtime prompt packet. Use for block-library authoring, creating example blocks, adapting a library block, generating or revising one block's simplified screens, instructions, data usage, data mappings, or asset intents, and for dry-run/apply/readback library workflows.

  • 22 files
  • 465.1 KB
  • Updated 2 weeks ago
  • GitHub
Use this Skill: https://skilld.dev/gh/segmently-ai/segmently-support-plugins/screen-block-builder

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈103 tokens for metadata: the name and description. ≈2.8k when used: this file. ≈92k more on demand in 9 files.

Description uses 5.1% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈411 characters, or 5.1%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

Screen Block Builder

Build one reusable strategy-block example without approximating the runtime agent prompt. Treat full screens as render-only previews and simplified screens as the authoring/adaptation contract.

When Segmently Launch Assistant delegates here, the routing marker is owningSkill=screen-block-builder.

Non-negotiable boundaries

  • Obtain systemPrompt, provider-neutral userMessage, exact effectiveUserMessage, renderInput, resolved branch state, and selected output schema from one CLI-exported runtime packet. Never reconstruct them from prompt files or prose.
  • Give a fresh agent only the generated agent-request.json. Do not give it repository access, editing tools, expected output, evaluator notes, or held-back eval-context.json / validation-schema.json files.
  • Keep previewScreens as full render-only snapshots. Never include them in a runtime packet, model request, adapted output, or target materialization.
  • Treat asset examples as references to intent and visual function. Author new target aiMeta.assetIntents; later asset generation creates provider-ready prompts from target context.
  • A write is incomplete until dry-run review, explicit user approval, apply, and authoritative readback all succeed. Create, update, and disable use CLI get; delete uses the apply response's readback.exists=false receipt.
  • Use only public project-library commands. Do not expose privileged catalogue maintenance syntax in customer output.

Theme adaptation and inserted-screen verification

Use theme-authoring for the destination's native visual contract and animation-authoring for native motion. Carry explicit target IDs, available subtypes, variables and selected recipe references; re-inspect after either saves. Never import a source project's literals, assets, custom code or answer values merely because they appear in previewScreens.

Review three different results: semantic blueprint, render-only example preview, and the actual inserted/materialized screens. Preview fidelity alone does not prove adaptation. In an authorized test insertion, check destination typography, media, mascot sections, actions, inputs/outputs and required context. Preserve branch coordinates and inspect the resulting layout for overlap. A strategy edit does not prove the linked onboarding changed: inspect its reconciliation/push result separately and verify the exact resulting version before reporting done.

Inputs

Collect or discover:

  • project id;
  • source strategy id and source block id for capture, or a local v2 block example file for create/update;
  • target name, description, tags, instructions, contract, and data semantics;
  • full previewScreens for exact visual review;
  • simplified blueprint screens plus aiMeta.dataMapping and semantic aiMeta.assetIntents;
  • model id from segmently ai models list <projectId> --env <env> when an agent run is requested.

Use examples/library-authoring-request.json as the complete UpdateBlockFromLibraryCompileInput template. Replace <projectId> in the CLI command and <project-model-id> / target-id placeholders in the file with values read from the project. Do not put credentials in authoring files.

Workflow

1. Read current state

segmently strategies blocks library list <projectId> --format json --env <env>
segmently strategies blocks library get <exampleId> <projectId> --format json --env <env>
segmently strategies blocks list <strategyId> <projectId> --format json --env <env>
segmently strategies screens list <strategyId> <blockId> --simplified <projectId> --format json --env <env>

For a new captured example, export before authoring:

segmently --env <env> strategies blocks library capture <strategyId> <blockId> <projectId> \
  --id <exampleId> --out block-library-draft.json --dry-run --format json

Review the blueprint and preview separately:

  • blueprint: brief, regenerated instructions, simplified screens, contract, data semantics, data mappings, and asset intents/examples;
  • preview: full screen snapshots only, used to confirm what the example looks like.

2. Validate the dual representation

node <skill-root>/scripts/validate-library-example.mjs \
  --input block-library-draft.json --format json

node <skill-root>/scripts/render-library-preview.mjs \
  --input block-library-draft.json --out block-library-preview.html

segmently --env <env> strategies blocks library validate \
  --file block-library-draft.json <projectId> --format json

Stop if the blueprint and preview screen ids/count/order differ, a screen is missing, the checksum is invalid, or full-preview/generated-asset material appears in the blueprint.

3. Export the exact runtime packet

Build the compile input from the project-library readback and compact target strategy context. Copy only source.blueprint; never copy previewScreens into this file. target.sequence, predecessor, and successor are compact block summaries with no full screens. Set exactly one evidence state under evidence.selection: strategy-default, selected-only, or no-evidence.

Validate the complete input, then use the public preview adapter. The adapter calls the same compiler as the runtime:

node <skill-root>/scripts/validate-compile-input.mjs \
  --input examples/library-authoring-request.json --format json
segmently --env <env> strategies blocks library prompt-packet \
  --request-file examples/library-authoring-request.json \
  --out runtime-packet.json <projectId> --format json

node <skill-root>/scripts/validate-runtime-packet.mjs \
  --packet runtime-packet.json --format json

The packet contract is in references/runtime-packet-contract.md. If the installed CLI does not expose prompt-packet, stop and report the missing capability. Do not fall back to manual prompt assembly.

4. Prepare a packet-only agent run

node <skill-root>/scripts/prepare-agent-run.mjs \
  --packet runtime-packet.json --out-dir agent-run

This writes:

  • agent-request.json: the only file given to a fresh agent;
  • eval-context.json: held back for deterministic evaluation;
  • validation-schema.json: checksum-pinned, held-back output schema snapshot;
  • run-manifest.json: immutable prepared packet hash and advisory-proof metadata.

Run a fresh agent with no inherited conversation and no repository/filesystem tools. Its task is only: obey systemPrompt, use userMessage (which is the packet's exact effectiveUserMessage), and return JSON matching the supplied output schema when present. Save its raw response as agent-run/raw-output.json.

Subagent smoke is advisory. It never replaces a real runtime task and its recorded prompt version/readback.

5. Evaluate and review the authored block

node <skill-root>/scripts/evaluate-agent-output.mjs \
  --packet runtime-packet.json \
  --output agent-run/raw-output.json \
  --validation-schema agent-run/validation-schema.json \
  --run-manifest agent-run/run-manifest.json \
  --report agent-run/evaluation.json

After a passing evaluation, the operator records the fresh-agent identity, agent-request-only boundary, artifact checksums, and concise evaluator notes in a separate completion receipt. Never rewrite the prepared manifest to claim a completed run:

node <skill-root>/scripts/record-agent-completion.mjs \
  --run-dir agent-run \
  --scenario <scenario-name> \
  --run-id <run-id> \
  --agent-task <fresh-agent-task-id> \
  --note "Topology matched the resolved branch." \
  --note "Evidence, variables, routes, and assets passed review."

For Google packets, both held-back files are mandatory. Evaluation fails before semantic acceptance if the manifest does not bind the exact packet or the schema bytes do not match the manifest checksum. Never substitute the current packaged schema for a prepared run snapshot.

Review these surfaces separately:

  1. description and reusable job/pattern;
  2. instructions rewritten for the target context;
  3. simplified screens, routes, and required variable collection;
  4. dataUsage and every screen's aiMeta.dataMapping;
  5. aiMeta.assetIntents and asset examples as pattern references;
  6. full render-only preview;
  7. evaluator failures and earliest failure stage.

Repeat with a new fresh agent when the packet or example changes. Preserve raw outputs, evaluator reports, and completion.json receipts for each cycle.

6. Dry-run, ask approval, apply, read back

For create or update, first ask the CLI for a deterministic receipt:

segmently --env <env> strategies blocks library create \
  <exampleId> --file block-library-draft.json --dry-run <projectId> --format json

Show the receipt/checksum and material changes to the user. Do not apply until the user explicitly approves that exact revision.

After approval:

segmently --env <env> strategies blocks library create \
  <exampleId> --file block-library-draft.json --apply \
  --dry-run-checksum <reviewedChecksum> \
  <projectId> --format json

segmently strategies blocks library get <exampleId> <projectId> --format json --env <env>

Use the matching update or disable verb for an existing example, with the same dry-run → approval → apply → get/readback discipline. For delete, require readback.exists=false in the successful apply response; a later get is expected to return structured not_found, not a successful entity readback. If the checksum changes between review and apply, stop and repeat the review.

Updating a normal strategy block

For a block that is not being authored as a library example, use the standard segmently generate block flow from the Product CLI guide. This skill still requires the runtime packet when evaluating a library-derived adaptation; it does not read prompt source files.

Failure handling

  • Missing CLI auth: ask the user to run segmently auth login, then retry.
  • Missing project access/capability: report the structured CLI error; do not broaden scopes or use a private fallback.
  • Missing prompt-packet: stop; the exact-runtime guarantee cannot be met.
  • Empty or invalid selected evidence: stop before the agent call and ask for a new selection or explicit no-evidence mode.
  • Empty strategy-default evidence: accept only when the packet records an explicit resolved no-evidence fallback.
  • First, last, or isolated/manual target: accept absent neighbours as valid; never invent them.
  • Packet hash mismatch or forbidden preview/source asset leakage: discard the packet and export again.
  • Invalid agent JSON/schema/routes/variables/data mappings: do not create or update the library record; revise the packet/example and rerun.

Verification

Run deterministic skill checks after edits:

node <skill-root>/scripts/run-evals.mjs

For an actual authoring session, retain the CLI dry-run receipt, approved checksum, apply response, authoritative readback, runtime packet, raw agent output, evaluation report, and completion receipt.

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No third-party reports yet.

Signed by skilld at f3f9f19. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub last week.

Activeupdated 2 weeks ago

README badge

README badge for segmently-ai/segmently-support-plugins/screen-block-builder