Interactive Questionnaire

Interactive Questionnaire Skill

Generates one self-contained .html file the client opens in any browser. No backend, no install, no login required. Submissions are sent via mailto link (opens the client's email app pre-filled) or copied to clipboard. Both paths land in your inbox — set your address in references/config.md.

Use this skill when a plain email questionnaire won't cut it — when you want visual polish, a project push, or stronger buy-in. Use a plain email intake when that's enough.

Visual direction: when styling goes beyond the default template (brand override set, or a novel layout is needed), run your design-direction skill before building so this skill inherits its upgrades automatically.

When to use

• Any stage of a project: kickoff, mid-project design approval, scope clarification, revision confirmation, content gathering
• When the client needs to make binary choices (A vs B, light vs dark, serif vs sans) that are clearer as tappable options than prose descriptions
• When reference URLs need to be shown visually (screenshot previews) rather than listed as bare links
• When the project needs a push, the client is slow to respond, or a plain email won't convey professionalism

Don't use this skill for: quick one-question checks (reply inline), pure message communication, or a default post-deposit email intake where comprehensive prose is fine.

Step 1 — Gather context

Before drafting, confirm or collect:

| Field | Required | Source | |---|---|---| | Client name(s) + email(s) | Yes | User or project SSOT | | Project name | Yes | User or project SSOT | | Form purpose (1 sentence) | Yes | e.g. "Design direction approval" | | Questions (the actual list) | Yes | User | | Reference URLs | Optional | Per question, if applicable | | "Why we're asking" context | Optional | Meeting notes, KB doc | | Brand override | Optional | Default is the neutral blue template | | Mobile-first flag | Optional | Only if the user explicitly says the client will use mobile |

If a required field is missing, ask once — briefly. If only optional fields are missing, proceed and flag what's missing at the end.

Step 2 — Classify each question

For each question, pick the right input pattern. See references/question-patterns.md for details.

Short version:

• A vs B → 2 radio cards, side-by-side (q-options--binary)
• A / B / C / D → stacked radio cards (q-options--stacked)
• Pick any that apply → checkboxes
• Open-ended → textarea with placeholder guidance
• Reference-linked choice → radio cards + reference card grid grouped with the question

Each question card has three parts: the question itself, an optional "why we're asking" blurb, and the input controls (plus optional reference cards and optional per-question note box).

Step 3 — Generate the HTML

Start from references/html-template.html. Fill in ALL placeholders:

| Placeholder | Fill with | |---|---| | {{PROJECT_NAME}} | Project title shown in header eyebrow | | {{CLIENT_FIRST_NAME}} | Used in greeting and success state | | {{FORM_PURPOSE}} | 1-sentence header title (e.g. "Design direction — 5 decisions") | | {{INTRO_CONTEXT}} | 2–3 sentence "why this form exists" blurb | | {{ESTIMATED_MINUTES}} | Honest time estimate (e.g. "5 minutes") | | {{QUESTION_BLOCKS}} | All rendered question cards, in order | | {{FORM_ID}} | Kebab-case slug: {client}-{purpose}-{YYYYMMDD} — used for localStorage namespace | | {{PAYLOAD_LABELS}} | A JSON object { "field_name": "Q1 — Label", ... } for every form field; drives the email/clipboard text payload |

Note on {{PAYLOAD_LABELS}}: This must be valid JS object literal syntax (not a JSON string — it's injected directly into script). Example:

{ "q_color": "Q1 — Color scheme", "q_color_note": "Q1 — Color note", "email": "Client email" }

Reference card rendering (inside .q-references block)

Screenshot service: thum.io (free, no API key, works without credentials).

  Reference sites
  
    
      
      ① {{CAPTION}}
    
  

The caption is the user's one-liner describing what the reference shows (e.g. "Bold layout, abstract + image mixed, sans serif"). Use ①②③④ circle numbers to cross-reference from question option sublabels.

Placeholder image on load failure: The template's JS automatically intercepts error events on .ref-card img and swaps in a browser-chrome mockup SVG. No changes needed to the HTML markup — it's handled automatically.

Mobile banner behavior

The template always includes the mobile banner markup. It's shown/hidden entirely via JS at runtime:

• Default (MOBILE_FIRST = false): banner appears on viewports Terminal: Run vercel --prod in the file directory to get your live URL, then paste it into the {{HOSTED_URL}} placeholder.

Do not paraphrase.

Output summary

Every successful run ends with these elements in this order:

1. A one-sentence summary of what the form covers
2. The HTML file
3. The email draft link (or fallback email body)
4. The deployment reminder (verbatim from Step 5)
5. (If any) a short "Missing optional fields" note

Notes and edge cases

• Accent color: Default --accent is #2563eb (blue). For client-branded forms, ask once: "house blue, or [client] brand?" and swap the :root CSS variables (--accent + --accent-soft).
• localStorage namespace: Must be unique per form — use {{FORM_ID}} slug. Prevents one client's answers from bleeding into another's.
• thum.io screenshots: Free, no API key. If a site blocks bots or the service times out, the JS placeholder handler fires automatically — no broken image icon.
• Self-contained constraint: No external CSS files, no build step. Fonts pull from Google Fonts CDN. All CSS and JS are inline in the .html file.
• Accessibility: radio/checkbox labels wrap the inputs so they're tappable targets. Minimum 44×44px hit areas on mobile.
• Video link: Template includes a commented-out video link block. Uncomment and fill {{VIDEO_URL}} if there's a walkthrough recording for the client.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Chevis-Zhou
• Source: Chevis-Zhou/agent-skills
• License: MIT

Install and usage instructions live in the source repository linked above.