Playground

Playground Builder

A playground is a self-contained HTML file with interactive controls on one side, a live preview on the other, and a prompt output at the bottom with a copy button. The user adjusts controls, explores visually, then copies the generated prompt back into Claude.

When to use this skill

When the user asks for an interactive playground, explorer, or visual tool for a topic — especially when the input space is large, visual, or structural and hard to express as plain text.

How to use this skill

1. Identify the playground type from the user's request
2. Load the matching template from templates/:
   • templates/design-playground.md — Visual design decisions (components, layouts, spacing, color, typography)
   • templates/data-explorer.md — Data and query building (SQL, APIs, pipelines, regex)
   • templates/concept-map.md — Learning and exploration (concept maps, knowledge gaps, scope mapping)
   • templates/document-critique.md — Document review (suggestions with approve/reject/comment workflow)
   • templates/diff-review.md — Code review (git diffs, commits, PRs with line-by-line commenting)
   • templates/code-map.md — Codebase architecture (component relationships, data flow, layer diagrams)
3. Follow the template to build the playground. If the topic doesn't fit any template cleanly, use the one closest and adapt.
4. Open in browser. After writing the HTML file, run open <filename>.html to launch it in the user's default browser.

Core requirements (every playground)

• Single HTML file. Inline all CSS and JS. No external dependencies.
• Live preview. Updates instantly on every control change. No "Apply" button.
• Prompt output. Natural language, not a value dump. Only mentions non-default choices. Includes enough context to act on without seeing the playground. Updates live.
• Copy button. Clipboard copy with brief "Copied!" feedback.
• Sensible defaults + presets. Looks good on first load. Include 3-5 named presets that snap all controls to a cohesive combination.
• Dark theme. System font for UI, monospace for code/values. Minimal chrome.

State management pattern

Keep a single state object. Every control writes to it, every render reads from it.

const state = { /* all configurable values */ };

function updateAll() {
  renderPreview(); // update the visual
  updatePrompt();  // rebuild the prompt text
}
// Every control calls updateAll() on change

Prompt output pattern

function updatePrompt() {
  const parts = [];

  // Only mention non-default values
  if (state.borderRadius !== DEFAULTS.borderRadius) {
    parts.push(`border-radius of ${state.borderRadius}px`);
  }

  // Use qualitative language alongside numbers
  if (state.shadowBlur > 16) parts.push('a pronounced shadow');
  else if (state.shadowBlur > 0) parts.push('a subtle shadow');

  prompt.textContent = `Update the card to use ${parts.join(', ')}.`;
}

Common mistakes to avoid

• Prompt output is just a value dump → write it as a natural instruction
• Too many controls at once → group by concern, hide advanced in a collapsible section
• Preview doesn't update instantly → every control change must trigger immediate re-render
• No defaults or presets → starts empty or broken on load
• External dependencies → if CDN is down, playground is dead
• Prompt lacks context → include enough that it's actionable without the playground

── KNOWLEDGE INJECTION: GitHub Spec Kit — Spec-Driven AI Development ──

Source: "Spec Kit: Github's NEW tool That FINALLY Fixes AI Coding" — Better Stack (2026) Added: 2026-03-17 · Relevant skills: ai-agent-builder, claude-md-improver, skill-development Repo: https://github.com/github/spec-kit

GitHub Spec Kit — Complete Reference

The Problem It Solves

Traditional AI coding = vague prompts → unpredictable code → fix loops. Spec Kit = structured specs as living contracts → AI agents execute with precision.

"Intent is the source of truth. Separate stable intent (WHAT) from flexible implementation (HOW)."

Installation

# Install CLI
uv tool install specify-cli --from git+https://github.com/github/spec-kit.git

# OR via uvx (no install)
uvx --from git+https://github.com/github/spec-kit.git specify init <PROJECT_NAME>

# Initialize project
specify init my-project
# → choose AI agent: Copilot / Claude Code / Gemini CLI / Cursor / Windsurf
# → choose shell: Bash / PowerShell

Project Structure

my-project/
├── constitution.md   ← non-negotiable principles & tech stack
├── spec.md           ← what you're building (features, user flows)
├── plan.md           ← technical architecture & components
├── tasks.md          ← sequential implementation chunks
└── quickstart.md     ← generated guidance

7 Slash Commands (Sequential Workflow)

File Contents

constitution.md — unchanging decisions:

## Tech Stack
- Framework: React + Vite + TypeScript
- Styling: Tailwind CSS
- State: useState / useReducer / Context API
- HTTP: Axios for external API calls
- No class components — functional only

spec.md — functional requirements (user-facing, no tech):

## Features
- Product listing page: grid of book cover, title, author, price
- Product detail page: larger image, description, add-to-cart button
- Cart page: item list, quantity controls, remove button, total price

plan.md — technical architecture:

## Components
- App.tsx (router root)
- ProductListPage.tsx + ProductCard.tsx
- ProductDetailPage.tsx
- CartPage.tsx
- CartContext.tsx (global state)
- api.ts (Axios data fetching)

## Routes
- / → product listing
- /product/:id → detail
- /cart → cart

tasks.md — sequential implementation:

## Tasks
- [] Scaffold project with Vite + React + TypeScript
- [] Create CartContext with add/remove/quantity actions
- [] Build ProductCard component
- [] Build ProductListPage with grid layout
- [] Build ProductDetailPage
- [] Build CartPage with totals
- [] Connect api.ts to Open Library API

Compatible AI Agents

• GitHub Copilot
• Claude Code ← (us!)
• Gemini CLI
• Cursor
• Windsurf

Use Cases

Key Principles

1. Specs as living contracts — not one-shot prompts
2. Gate each phase — don't implement until spec + plan + tasks are validated
3. /analyze before /implement — catches inconsistencies early
4. Constitution = immutable — tech decisions made once, respected always
5. Tasks = atomic — each task independently reviewable

Apply to Claude Code Projects

When starting any new project in Claude Code:

specify init <project-name>
# Then work through: /constitution → /specify → /clarify → /plan → /tasks → /analyze → /implement

This replaces ad-hoc CLAUDE.md prompting with a structured, validated spec system.

── KNOWLEDGE INJECTION: GitHub Spec Kit — Deep Dive (from GitHub Repo) ──

Source: https://github.com/github/spec-kit · Fetched: 2026-03-17 Extends: prior Spec Kit knowledge injection (Better Stack video)

Complete CLI Reference

Installation

# Persistent install (recommended)
uv tool install specify-cli --from git+https://github.com/github/spec-kit.git

# One-time (no install)
uvx --from git+https://github.com/github/spec-kit.git specify init <PROJECT_NAME>

# Upgrade
uv tool install specify-cli --force --from git+https://github.com/github/spec-kit.git

# Check prerequisites
specify check

specify init — All Options

specify init <project-name>          # create in new directory
specify init --here                  # init in current directory
specify init . --ai claude           # Claude Code agent
specify init . --ai gemini           # Gemini CLI
specify init . --ai copilot          # GitHub Copilot
specify init . --ai cursor-agent     # Cursor
specify init . --ai windsurf         # Windsurf
specify init . --ai generic --ai-commands-dir ./my-cmds  # custom agent
specify init . --script ps           # PowerShell scripts
specify init . --no-git              # skip git init
specify init . --force               # skip merge confirmation
specify init . --ai-skills           # install Prompt.MD skill templates
specify init . --debug               # verbose output

Supported Agents (24+)

Claude Code, Gemini CLI, GitHub Copilot, Cursor, Windsurf, Kiro CLI, Codex CLI, Qwen Code, Roo Code, Kilo Code, OpenCode, Amp, SHAI, Tabnine CLI, Kimi Code, IBM Bob, Jules, CodeBuddy CLI, Mistral Vibe, Auggie CLI, Antigravity, Trae, Qoder CLI, generic

Full Project Structure

.specify/
├── memory/
│   └── constitution.md         ← non-negotiable principles (immutable)
├── scripts/
│   ├── check-prerequisites.sh
│   ├── common.sh
│   ├── create-new-feature.sh   ← scaffold new feature spec
│   ├── setup-plan.sh
│   └── update-claude-md.sh
├── specs/
│   └── <FEATURE_ID>/           ← one folder per feature
│       ├── spec.md             ← what & why (no tech detail)
│       ├── plan.md             ← technical architecture
│       ├── tasks.md            ← ordered implementation chunks
│       ├── data-model.md       ← entities & schema
│       ├── quickstart.md       ← generated setup guide
│       ├── research.md         ← pre-implementation research
│       └── contracts/
│           ├── api-spec.json   ← OpenAPI/REST contracts
│           └── signalr-spec.md ← realtime contracts
└── templates/
    ├── spec-template.md
    ├── plan-template.md
    ├── tasks-template.md
    └── CLAUDE-template.md

8 Slash Commands

/speckit.constitution  → Define project governance & tech decisions (immutable)
/speckit.specify       → Write spec.md: user stories, requirements, success criteria
/speckit.clarify       → Resolve ambiguities before planning
/speckit.plan          → Write plan.md: architecture, components, dependencies
/speckit.analyze       → Cross-validate all artifacts for consistency gaps
/speckit.tasks         → Write tasks.md: ordered, dependency-aware, parallelizable
/speckit.implement     → Execute tasks systematically (test-driven)
/speckit.checklist     → Generate quality validation checklist

Template Blueprints

spec.md structure

# Feature: <NAME>

## User Stories (prioritized)
- P1: As a <user>, I want to <action> so that <value>
  - INDEPENDENTLY TESTABLE: yes
  - MVP slice: yes

## Functional Requirements
- [] REQ-01: <specific capability>
- [] REQ-02: <specific capability>  ← NEEDS CLARIFICATION: <question>

## Key Entities
- Entity: <Name> — <description>

## Success Criteria (measurable, tech-agnostic)
- [] <metric>: <target>

plan.md structure

# Implementation Plan: <FEATURE>

## Summary
<Core requirement + proposed technical strategy>

## Technical Decisions
| Dimension | Decision | Notes |
|-----------|----------|-------|
| Language | TypeScript | — |
| Framework | React + Vite | NEEDS CLARIFICATION: Next.js? |
| Storage | PostgreSQL | — |
| Performance | <200ms p95 | — |

## Constitution Check ✓
- [] Follows naming conventions
- [] Uses approved dependencies
- [] Passes security review gate

## Project Structure
<source tree with file paths>

## Complexity Justification
| Decision | Why complexity is necessary |
|----------|---------------------------|

tasks.md structure

# Tasks: <FEATURE>

## Phase 1 — Project Init
- [] T001 Scaffold project structure

## Phase 2 — Foundation (BLOCKS all subsequent phases)
- [] T002 Set up database schema
- [] T003 [P] Configure auth middleware   ← [P] = parallelizable
- [] T004 [P] Set up API routes

## Phase 3 — P1 User Story: <name>
- [] T010 [P1] Build <component> — src/components/Foo.tsx
- [] T011 [P1] Write unit tests — src/tests/Foo.test.ts

## Implementation Strategy
- MVP First: complete foundation → validate one story → stop
- Incremental: add stories sequentially, validate each
- Parallel: multiple devs on different stories after foundation

Environment Variables

SPECIFY_FEATURE=my-feature   # override feature detection (non-Git repos)
GH_TOKEN=ghp_xxx             # GitHub API auth
GITHUB_TOKEN=ghp_xxx         # alternative GitHub auth

Use Cases

Apply with Claude Code

# 1. Init for Claude Code
specify init my-project --ai claude --here

# 2. Open project in Claude Code, then run slash commands:
# /speckit.constitution → /speckit.specify → /speckit.clarify
# → /speckit.plan → /speckit.analyze → /speckit.tasks → /speckit.implement

# 3. New feature on existing project
bash .specify/scripts/create-new-feature.sh my-new-feature
# Then: /speckit.specify → /speckit.plan → /speckit.tasks → /speckit.implement