What Is the Prototype Skill and How to Use It in emilkowalski/skills

The prototype skill is a divergence tool that generates 3-5 distinct UI variants for a single component description and renders them behind a standardized visual picker for live comparison, strictly isolating exploration from production code.

The prototype skill is part of the emilkowalski/skills repository and serves as a sandboxed design-exploration engine for UI development. Unlike skills that trigger automatically, this tool runs only when explicitly invoked to help designers and developers explore genuinely different implementations—such as layout, density, personality, motion, or interaction variations—without risking contamination of the production codebase.

How the Prototype Skill Works

The skill operates as a divergence engine that follows a strict six-phase workflow defined in skills/prototype/SKILL.md. It begins with a user-supplied description (e.g., "a toast notification" or "pricing card") and ends with the promotion of a chosen variant into the actual project.

Workflow Phases

According to the source specification, the skill executes these phases sequentially:

1. Scope – Define the component boundaries and constraints.
2. Recon – Inspect the current project stack, design tokens, motion libraries, and personality, or fall back to a neutral static context.
3. Choose Directions – Enumerate 3-5 variant axes (e.g., Quiet, Editorial, Playful), each with a clear name and design rationale.
4. Build Picker Harness – Create an isolated environment for rendering variants.
5. Verify & Hand-off – Ensure all variants are fully functional with real content and interactions.
6. Promote – Merge the selected variant into the production codebase and clean up temporary files.

The Picker Harness Implementation

The harness creation depends on project context. If a dev server exists, the skill generates an isolated route at /prototypes/<slug> with one file per variant plus a harness file. If no project exists, it emits a single self-contained HTML file.

The picker UI itself is immutable. As specified in skills/prototype/PICKER.md, the markup, CSS, and JavaScript must be copied verbatim into every prototype run:

<nav class="proto-picker" aria-label="Prototype variants">
  <span class="proto-picker-highlight" aria-hidden="true"></span>
  <button class="proto-picker-item" data-active aria-current="true">Quiet</button>
  <button class="proto-picker-item">Editorial</button>
  <button class="proto-picker-item">Playful</button>
  <span class="proto-picker-divider" aria-hidden="true"></span>
  <button class="proto-picker-item proto-picker-replay" aria-label="Replay animation (R)">↻</button>
</nav>

// Core picker wiring (from PICKER.md)
let current = 0;
function setActive(i) { /* updates highlight, URL, and mounts variant */ }
document.addEventListener('keydown', (e) => { /* 1‑N keys, ←/→, R */ });

Each variant renders full-size in realistic surrounding context. Users navigate instantly between options using 1-N keys, arrow keys (←/→), or mouse clicks. The picker displays a comparison table summarizing each variant's axis, appropriate use cases, and implementation cost.

Invoking the Prototype Skill

The prototype skill supports several explicit invocation patterns from the command line or chat interface within an Instagit session:

# Basic run – three variants are generated automatically.

prototype "a toast notification"

# Ask for five variants (capped at 5).

prototype "pricing card" x5

# After reviewing, ask for a new round that diverges around a chosen direction.

prototype riff "Playful"

# Promote the second variant into the codebase and clean up the prototype surface.

prototype keep 2

# Promote the winner but keep the picker UI for future reference.

prototype keep 1, leave the picker

Hard rules govern every invocation:

• No changes to production code occur during the exploration phase.
• Each variant must differ on a named design axis (layout, density, personality, motion, or interaction).
• Variants must be fully functional with real content and real interactions, not mere visual mocks.
• The picker UI implementation must match PICKER.md exactly.

Key Files and Implementation Details

The repository contains two canonical files that define the skill's behavior:

• skills/prototype/SKILL.md – Contains the complete skill specification, workflow phases, hard rules, and invocation syntax table.
• skills/prototype/PICKER.md – Provides the canonical markup, CSS, and JavaScript for the visual picker that must be copied verbatim into every prototype harness.

These files work in concert with complementary skills like skills/review-animations/SKILL.md (for convergent animation review) and skills/pick-ui-library/SKILL.md (for library selection), positioning the prototype skill within a broader design-engineering workflow.

Summary

• The prototype skill generates 3-5 genuinely different UI implementations for a single component description, capped at five variants.
• It creates a standardized picker harness (either as a dev server route or static HTML) using immutable UI components defined in skills/prototype/PICKER.md.
• The tool operates under strict isolation rules, ensuring zero production code changes during exploration and requiring full functionality in every variant.
• Users navigate variants via keyboard shortcuts (1-N, ←/→) or mouse interaction, then promote winners using the keep command.
• All behavior is governed by skills/prototype/SKILL.md, which mandates specific workflow phases from reconnaissance through final promotion.

Frequently Asked Questions

How many variants does the prototype skill generate by default?

By default, the skill generates three variants automatically. You can request up to five variants by appending x5 to your invocation (e.g., prototype "pricing card" x5), though five is the hard cap regardless of the requested number.

Can I modify the picker UI when using the prototype skill?

No. The picker UI defined in skills/prototype/PICKER.md must be copied verbatim into every prototype harness. This standardization ensures consistent keyboard navigation (1-N keys, arrow keys, R for replay) and visual comparison across all prototype sessions. The skill enforces this as a hard rule to maintain predictable user experience.

What happens to the prototype files after I choose a variant?

By default, the keep <variant> command promotes the selected variant into your production codebase following existing project conventions, then deletes the temporary prototype surface and isolated route. However, you can preserve the picker UI for future reference by using the syntax keep <variant>, leave the picker.

Does the prototype skill work without a development server?

Yes. If the skill detects no existing project or dev server, it generates a single self-contained HTML file containing all variants and the picker harness. This static file operates identically to the dev server route, allowing design exploration in any environment.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}