Web Technique To Skill

Direct the demo

The demo is the only evidence most readers will ever see. They will not read the source project, and they will judge the technique by this one file. A mechanism that shipped on a considered page, demonstrated by something that looks like a test harness, reads as unfinished — and nobody reaches for a skill that looks unfinished.

So the demo inherits the craft bar of the source, not the craft bar of a code sample.

• Treat the approved reference as an acceptance target, not inspiration. Reproduce the same first frame, layout geometry, palette, type treatment, asset scale, atmosphere, and motion hierarchy around the isolated mechanism. Do a layer-by-layer inventory before coding. Someone opening the demo should identify the source immediately, before reading its name.
• Use the reference's own assets, by porting the code that makes them. If the source generates its sky, its moon, its textures, its silhouettes, bring those functions across unchanged. A hand-rolled CSS approximation of a procedurally generated moon is a flat disc next to one with real maria and a crater field, and the gap is obvious the moment they sit side by side. Porting a generator costs nothing at rest, keeps the demo one self-contained file, and makes the staging genuinely the same rather than merely similar.
• Owned reference assets cross with the technique when they are necessary for fidelity. Copy the smallest local set the demo needs and record their provenance. Exact owned staging outranks a one-file preference; a portable local bundle is better than a self-contained approximation that no longer matches. What must not cross is anything you do not own: a client's brand, licensed fonts, purchased imagery, or third-party media.
• Show the mechanism on the first screen — before any scroll, before any interaction. If it takes a click to see the point, the framing is wrong.
• Verify the whole state path when the mechanism spans time or scroll. The opening frame must establish the world and expose its conductor, but it cannot prove a multi-scene journey by itself. Compare every authored key state plus the forward, reverse, fast-skip, and reload-at-depth paths; a perfect hero does not excuse a broken third chapter.
• Preserve layout-defining reference copy. If changing the headline or body would change the approved composition, keep it exactly and put the technique name, verified stack, and mechanism argument into the browser title plus the reference's existing secondary panel, controls, microcopy, or accessible description. Do not trade visual fidelity for an explanatory headline, but never leave the implementation unidentified.
• Keep a family. Two techniques pulled from the same reference should produce two demos that look like siblings. A library of demos that share a reference reads as a body of work; a library where each one invents its own world reads as scraps.

A worked example of the copy rule, for a Canvas 2D trail that emits per unit of distance:

Vanilla JavaScript · Canvas 2D

Wisps

Distance-emitted Canvas 2D particles keep the same spacing at any hand speed; CSS styles the interface only. Switch emission to a timer and the same gesture breaks apart — a fast pass leaves scattered dots, while a resting hand piles them on one spot. No WebGL, shaders, or Three.js.

The title names the effect. The kicker identifies the stack. The body states the mechanism, the failure, and any likely implementation ambiguity. The control named in the body is on screen, so the reader can check the claim.

• One idea per screen. A demo proving three things proves none of them.
• Controls expose states that matter, as real form elements, and prove the system is parameterised rather than baked. Skip controls that only restate what is already visible.

Quality floor

Every one of these, every time:

• A deliberate type scale with a considered largest and smallest step — never browser defaults
• Spacing on one consistent rhythm
• A restrained palette with one accent that carries meaning
• Every interactive control styled, including its focus state
• A concrete technique title plus the verified runtime, renderer, and major technique libraries on the first screen
• Real, specific copy from a plausible project — never "Card title" or "Demo section"
• One self-contained file when the exact reference permits it; otherwise a minimal local bundle of owned assets with no remote runtime dependency
• 390px through 1440px, semantic HTML, visible focus, and a clean console at both ends

If the demo would embarrass you next to the page you extracted it from, it is not finished.

Verify in a browser, then report

Do not claim visual or interaction behavior from reading the file. Drive it:

1. Load the demo at 1440×900 and 390×844.
2. Confirm the visible title names the technique and the stack disclosure matches the source imports, renderer, and context creation.
3. Exercise the primary interaction and confirm the state actually changes.
4. For scroll, timeline, or multi-state techniques, traverse every authored state forward and backward, fast-skip across seams, and reload at a nonzero state.
5. Tab through and confirm focus is visible and ordered.
6. Run the reduced-motion path and confirm a composed frame renders and animation stops.
7. Confirm the console is clean at both sizes.
8. Capture the preview at the repository's shared dimensions.
9. Compare the demo and source side by side at the source viewport. For multi-state techniques, compare every representative key state. Fix structural drift in hierarchy, crop, scale, alignment, and atmosphere before polishing the isolated effect.

Expect this pass to find something. When it does, fix the demo and re-run rather than softening the rule.

Package and commit

agent-skills/<category>/<skill-name>/
  SKILL.md
  agents/openai.yaml
  demo/
    index.html
    PROMPT.md
    preview.jpg
    reference.*        # optional owned staging required for exact fidelity

Write SKILL.md in imperative form with only name and description in frontmatter, and put every trigger phrase in the description. Give demo/PROMPT.md three headings: Minimal prompt, Recreate the demo, Remix prompt, where the remix changes subject, palette, and composition while preserving the mechanism and the budgets.

Stage only the new folder and the gallery rows it needs. Review git diff --cached --stat before committing, and leave pre-existing dirty files alone.

Verify

• The mechanism sentence survives changing the subject, palette, and layout
• The visible title names the technique instead of using an abstract mechanism claim
• The first screen states the verified runtime, renderer or browser API, and major technique libraries
• Staging lives in the demo, not in the skill body
• Every rule names the failure it prevents
• Constants are real numbers, not adjectives
• The expensive gotchas are written symptom-first
• The boundary against the nearest existing skill is stated in the opening lines
• Provenance is one line of context naming the source project
• The demo is recognisably the reference — same palette, type, composition, atmosphere
• The source and demo were compared side by side at the source viewport; no structural drift remains
• The reference's own generators were ported, or the smallest owned reference asset was bundled when exact code isolation was not practical
• Nothing unowned crossed over, and the demo ships as one file or the smallest justified local owned-asset bundle
• Demos from the same reference look like siblings
• The demo's own copy states the mechanism and names the failure it prevents
• The demo shows the mechanism on the first screen, before scroll or interaction
• A scroll, timeline, or multi-state mechanism was verified at every key state, in reverse, across fast skips, and after reload at depth
• The demo would not embarrass you next to the page it came from
• Type scale, spacing rhythm, and palette are deliberate, not defaults
• Reduced motion renders a designed still, not a hidden element
• Cost claims were measured, not assumed
• The demo was driven in a browser at both breakpoints with a clean console
• Only the new skill folder is staged