# Interactive Questionnaire

> Generate a polished, self-contained HTML questionnaire file that the client fills out in-browser and submits via email or clipboard. Use this skill whenever the user says "make a client form", "build an intake form", "turn these questions into a form", "design approval form", "I need more buy-in from [client]", "something more polished than an email", "interactive questionnaire", or whenever they…

- **Type:** Skill
- **Install:** `agentstack add skill-chevis-zhou-agent-skills-interactive-questionnaire`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [Chevis-Zhou](https://agentstack.voostack.com/s/chevis-zhou)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [Chevis-Zhou](https://github.com/Chevis-Zhou)
- **Source:** https://github.com/Chevis-Zhou/agent-skills/tree/main/skills/interactive-questionnaire

## Install

```sh
agentstack add skill-chevis-zhou-agent-skills-interactive-questionnaire
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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:
```js
{ "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).

```html

  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](https://github.com/Chevis-Zhou)
- **Source:** [Chevis-Zhou/agent-skills](https://github.com/Chevis-Zhou/agent-skills)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-chevis-zhou-agent-skills-interactive-questionnaire
- Seller: https://agentstack.voostack.com/s/chevis-zhou
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.