How to use
- Copy the installation command and review the source package before installing it in your own agent environment.
- Check the source document for required tools, credentials and supported hosts.
- Describe your input and desired deliverable; review the output against the source material.
npx skills add https://github.com/terrylica/cc-skills --skill interactive-json-formBefore you start
- Installation does not include a model subscription, API allowance or permission to access your files.
- Repository stars and installation counts describe activity, not an independent quality or security test.
Rendered from the source repository. Headings, examples, code, tables, links, and referenced images are preserved.
Interactive JSON Form — decision/survey pages with a client-side JSON round-trip
Self-Evolving Skill: This skill improves through use. If instructions are wrong, parameters drifted, or a workaround was needed — fix this file immediately, don't defer. Only update for real, reproducible issues.
A single self-contained `.html` file that presents extensive explanations, lets a small known audience (e.g. a CEO + data scientists) pick options, rank them, and comment, then hands their input back as a downloadable / copyable / re-importable JSON — with no server, no submit endpoint, and no tracking. Published privately on your own host behind a noindex header + an unguessable path, so it is reachable by whoever has the linkTelus-direct door) but blocked from crawlers/indexing.
When to use this skill
- You need a few named humans to make structured choices + free-form comments
on a set of options, and you want their answers back as machine-readable JSON you ingest directly.
- Mobile-friendly, re-openable (import a prior JSON to resume), zero tooling for
the responder, and no backend to stand up.
- The audience is small and known → a downloadable JSON they send you beats a
hosted collector; a public form would over-expose.
When NOT to use it
- Anonymous mass surveys / thousands of respondents (use a real survey backend).
- You need server-side aggregation in real time (add a collector, or use Lark Base
— see ../../lark-automation for the Base decision-harness alternative).
- Multi-page sitemap sites with no JS → use the sibling `page-template` skill.
Why this over Lark Base / Forms / cards (decided by research 2026-07-13)
Lark Base grids truncate long text (row-height/width are NOT API-settable), Forms are read-only after submit with no create API, and cards are one-shot with a 30-day window + a callback webhook. A self-contained HTML page has none of those limits: full text wraps natively, edits are unlimited, and the JSON round-trip is pure client-side. The cost is that responses come back as files, not a live table — acceptable for a small known audience.
The pattern (what makes it work)
- Data-driven options. An
OPTIONSarray at the top of the inline<script>
is the single source of truth; the DOM is generated from it. To reskin for a new decision, edit that array only.
- `collect()` → JSON. Reads every control (respondent, per-option vote/rank/
comment, overall) into a versioned object {schema, respondent, role, firstPick, overallComment, choices:[{id,title,vote,rank,comment}]}.
- Three return paths, all client-side:
- Download:
Blob+URL.createObjectURL+a[download]→ a.jsonfile. - Copy:
navigator.clipboard.writeText(withexecCommandfallback). - Import:
<input type=file>→FileReader→hydrate()repopulates the
form. Import→export is byte-identical (resumable editing) — assert this.
- `schema` version string on every payload so the ingester can evolve.
- `beforeunload` guard warns on unsaved edits.
- Self-contained: inline
<style>+<script>, no external requests, no
fonts/CDN, <meta name="robots" content="noindex, nofollow, noarchive, nosnippet">, <meta name="referrer" content="no-referrer">.
Start from `templates/index.html` in this skill — it is the working page (built for the ODB × time-bar decision) with the mechanism intact; swap the OPTIONS array + the two intro .note blocks and you have a new page.
Verify before you ship (headless, local)
Render + exercise the JS with Playwright against file:// (no login needed): fill the form via page.evaluate (the radios are visually hidden labels — set .checked + dispatch change rather than page.check), call collect(), then reload a fresh page, hydrate() the JSON, collect() again, and assert the two JSON strings are identical. Screenshot fullPage:false and eyeball it. See the local-shot.mjs pattern.
Publish privately on your own host (no web-server config change, no restart)
The pattern, not a particular server: point a hostname at a static docroot behind a web server that already emits `header X-Robots-Tag "noindex, nofollow, noarchive, nosnippet"` globally. A static file dropped into a subdirectory is then served instantly with noindex over the existing TLS chain — no config edit, no reload, so co-hosted services on the same door are untouched.
Substitute your own values for $SITE_HOST (the public hostname), $SSH_HOST (its ssh alias), $DOCROOT (the server's static root) and $WEB_USER (the account the web server runs as).
# 1. upload the built page
scp -q your-page.html "$SSH_HOST:/tmp/page.html"
# 2. drop it at an UNGUESSABLE path (docroot is usually server-owned → sudo)
ssh "$SSH_HOST" 'set -e
P="<slug>-$(openssl rand -hex 16)" # unguessable path segment
D="'"$DOCROOT"'/$P"
sudo mkdir -p "$D"; sudo cp /tmp/page.html "$D/index.html"
sudo chown -R '"$WEB_USER:$WEB_USER"' "$D"; rm -f /tmp/page.html
echo "URL: https://'"$SITE_HOST"'/$P/"'
# 3. TRUE external reachability. An on-LAN 200 does NOT prove the WAN chain when
# split-DNS short-circuits the hostname to a LAN address — verify from a host
# that is genuinely outside your network.
ssh <some-external-host> 'curl -sS -o /dev/null -w "EXTERNAL %{http_code} TLS=%{ssl_verify_result}\n" https://'"$SITE_HOST"'/<PATH>/'Crawler-blocking layers (this skill's default): (a) global X-Robots-Tag noindex header (already on the door), (b) page <meta robots noindex>, (c) an unguessable path with no inbound links. A 4th layer — User-Agent blocking — needs a Caddy @bots matcher in the edge-route registry (edge-routes.toml + generate-edge-config.py); it is a production config change, so treat it as optional hardening, not default.
If your edge config is generated from a registry rather than hand-edited, change the registry and regenerate — that is the durable path, and it keeps the door reproducible.
Publishing as an Orca artifact (orca artifacts share|update <file>)
Measured on share.onorca.dev, 2026-10-28. The page is served in a cross-origin content frame (*.orcausercontent…) under Content-Security-Policy: sandbox allow-downloads allow-forms allow-modals allow-popups allow-scripts.
- No browser storage. Without
allow-same-origin,localStoragethrows, so Download, Copy and Import are the only ways to keep answers. Say so on the page. - No Clipboard API. The frame's permissions policy forbids
clipboard-write. Callingnavigator.clipboard.writeTextlogs a policy violation, and theexecCommand("copy")fallback can returntruewhile copying nothing. A page that says "Copied" here may be lying. Checkdocument.permissionsPolicy ?? document.featurePolicywithallowsFeature("clipboard-write")first. Where it is blocked, select the whole answer text and ask the reader to press ⌘C / Ctrl+C, or on touch screens (matchMedia("(pointer: coarse)")) to touch and hold, then choose Copy. Never claim success you cannot verify. Downloads do work. - Safari and Firefox can't download from the frame (Chrome can). WebKit, and Gecko the same way, count
<a download href=blob:…>(alsotarget=_blankanddata:) inside the frame as navigating the frame. The share page'sframe-srcforbids that, loggingRefused to load blob:null/… frame-src, so nothing downloads. A page-levelframe-src blob:does not help, because the parent's policy governs.window.open(blobUrl, "_blank")does work, since pop-ups are allowed: whenwindow.self !== window.topand the browser is not Chromium (!navigator.userAgentData), open the answers in a new tab and tell the reader to use Share or File > Save. Chrome downloads normally. Firefox also requests/favicon.icoby itself, which adefault-src 'none'CSP blocks with a console error, so inline adata:icon. Test all three engines (webkit.launch(),firefox.launch()) on the share URL. A local top-level page hides this bug. - Short file names. Orca prints the original file name, twice and unwrapped, in its share header. A phone's browser zooms the whole page out to fit it: 27 characters fit a 375px phone, 37 need 439px, and 87 need 741px. Keep the name short, under 28 characters including
.html, and explain the page in its<h1>. There is no title flag. - Test the frame, not just the file. A local overflow check run inside the content frame passes even when the top page is too wide. Emulate a phone (
isMobile: true) on the share URL and compare the top page'sinnerWidthandscrollWidthto the viewport. Serve the local build with the sandbox header above to reproduce the storage behaviour. To prove what a real click copies, read the clipboard back from an unsandboxed page on the same origin. orca artifacts update <file>keeps the URL. Renaming the file meansunsharethe old one andsharethe new one, which gives a new URL. Artifacts expire after 30 days.
Ingesting responses
The JSON is exactly collect()'s output. Consume it directly; key on schema for versioning and respondent/role to attribute. Merge multiple respondents' files by choices[].id.
Hard rules
- One file, no external network requests, no tracking,
noindexin<meta>. - Never a real submit/collector endpoint unless the user explicitly opts in
(it turns a private artifact into a hosted service + a data-handling duty).
- Never publish to the door by hand-editing the live web-server config — drop
a static file into the docroot (config-free) or change the registry + regen.
- Always verify the import→export round-trip is byte-identical before shipping.
Post-Execution Reflection
After this skill completes, reflect before closing the task:
- Locate yourself. — Find this SKILL.md's canonical path before editing.
- What failed? — Fix the instruction. If the deploy recipe drifted (docroot,
header, sudo), fix it here AND cross-check edge-routes.toml.
- What worked better than expected? — If a new control type (multi-select,
drag-rank) recurs, fold it into templates/index.html.
- What drifted? — Keep the JSON schema, the deploy commands, and the
crawler-block layers aligned with reality.
- Log it. — Evolution-log entry with trigger, fix, evidence.
Do NOT defer. The next invocation inherits whatever you leave behind.

