stitch-extract-static-html

Extract a static HTML snapshot

Quick start

1. "Save the empty-list state of the store appointment web page; first give a locally reviewable result."
2. "Export a static snapshot of the operations dashboard with ECharts; keep the existing scope and sources."
3. "When the app cannot run, construct a static fallback with explicit demo data; mark the missing inputs and verification status."

For designers, frontend developers, and teams maintaining this process. Designers provide intent and assets, developers provide engineering/tooling, and the team preserves sources and acceptance status during handoff.

Capability boundaries

✅ Good at handling

• Save the empty-list state of the store appointment web page.
• Export a static snapshot of the operations dashboard with ECharts.
• When the app cannot run, construct a static fallback with explicit demo data.

⚠️ Requires assets

• A local URL or static entry point with authorized access.
• Viewport, target state, and output file path.
• Existing Node/Puppeteer/tsx tooling; the login page requires a legitimate demo session.

❌ Inapplicable scenarios and handoff

• Automatic upload to Stitch → stitch-upload, provide the reviewed file.
• Preserve the full backend and interactive functionality → target project build/deploy process.
• Bypass login or access someone else's session → use a test account with permissions and a sanitized page.

Workflow

1. Check installed dependencies and the target URL, and choose Puppeteer based on a runnable page; if an authorized browser state exists, use browser capture, and do not repeatedly ask about an already-determined strategy.
2. Fix the route, viewport, and theme; the authentication script uses only an authorized test identity, reads credentials from the environment, and does not write them to source code or logs.
3. Run scripts/snapshot.ts; use --inline-canvas, --html-class, --viewport as needed; when dependencies are missing, first output the exact command and the tooling to be added, and do not install silently.
4. Use extract_inline_html.ts and post_process.ts only for a static fallback; mark it as a simulated state and do not pass it off as a running page.
5. Check the output for residual external links, srcset, CSSOM, fonts, and charts; verify by opening it offline, and stop the service started for this run.

Order by dependency: source verification → local artifacts → authorized external operations → verification handoff. For multiple tasks, do the current main path first; when information is missing, first output a draft of assumptions, then precisely list what is missing and what it is for, without using vague prompts like "please provide more context."

Security and result verification

Do not read unrelated account configurations and do not collect user passwords; credentials are provided only by the environment or an authorized connector. Examples use only demo data; before uploading, replace customer names, phone numbers, and order numbers with demo values, and check the HTML, screenshots, and file metadata. Do not write keys, session cookies, full base64 content, or signed download URLs into reports/repositories. Do not fabricate unverified parameters, visual effects, or business figures; the output notes sources, decision rationale, what was actually executed, and what has not yet been verified.

• Local assets do not go beyond --base-dir or follow out-of-bounds symlinks.
• CSSOM snapshots preserve media rules and do not rewrite existing style.
• Static output missing resources are explicitly listed; no claim is made that events and interfaces are preserved.

Customizable: URL, viewport, html-class, wait, inline-canvas, output path. Value-added checks: CSSOM preservation; canvas static conversion; same-origin asset and out-of-bounds checks.

FAQ

Q1: What is the main deliverable? The input demo HTML appointment list has no appointments yet; the static output preserves these three nodes and contains no business events; remote writes 0.

Q2: When should another entry point be used instead? Automatic upload to Stitch → stitch-upload, provide the reviewed files; preserve the full backend and interactive functionality → the target project build/deploy process; bypass login or access someone else's session → use a test account with permissions and a desensitized page.

Q3: What happens if input is missing? First provide a clearly marked local-assumptions draft, and list "needs to be provided: an authorized local URL or static entry point; viewport, target state, and output file path; existing Node/Puppeteer/tsx tooling; the login page requires a legitimate demo session". Write operations that depend on these inputs are not executed.

Q4: How is completion determined? Local assets do not go beyond --base-dir or follow out-of-bounds symlinks; the CSSOM snapshot preserves media rules and does not rewrite existing style; static output missing resources are explicitly listed, and no claim is made that events and interfaces are preserved.

Q5: How is it customized? URL, viewport, html-class, wait, inline-canvas, output path; when not provided, existing project values are used and assumptions are noted.

Q6: Is it automatically uploaded, installed, or deployed? Only actions covered by the current request and existing authorization are performed; without a remote receipt, do not claim upload success; without runtime verification, do not claim deployment. Additional installation or scope expansion requires explaining the specific impact first.

Reference as needed

• When performing detailed mapping, API, or templates, read Extended workflow。
• When encountering failures/abnormal input, read Anti-patterns and Gotchas。
• When involving edge cases, compatibility, customization, and authorization, read In-depth FAQ。
• When complete input/output and verification scenarios are needed, read Local application example。
• The local implementation basis is the source code accompanying the current skill and the pinned upstream snapshot; the structure follows the Agent Skills specification. The tool's current behavior is subject to the actual schema; when not connected, do not claim that online behavior has been verified.

When to use

When the user needs to select and execute a verifiable, recoverable professional workflow for the current request , load this skill. First extract the goal, input, constraints, delivery format, and acceptance criteria from the request; the description summary is: extract static HTML from a local front-end page and inline retrievable assets; trigger when there is a need to save a specified UI state, perform offline inspection, or prepare upload files for Stitch. The result does not include interactive logic, nor does it automatically upload..

Rules

• Read before write: first confirm the current state and real capabilities, then perform actions that change external state.
• Least privilege: use only the files, tools, accounts, and network scope required to complete the current step.
• Evidence first: when run results, resource IDs, versions, hashes, or test output are missing, clearly mark them as NOT_VERIFIED。
• Idempotency first: preserve the request identifier and phase state; when results are unclear, query first rather than blindly retrying.
• Privacy and security: logs, examples, receipts, and error messages must not contain tokens, cookies, keys, or personally sensitive data.

Workflow

Step 1: Clarify intent

Confirm whether this skill matches the goal; if it is only an adjacent need, hand it off to a more precise skill.

Step 2: Run prechecks

Confirm the goal, inputs, constraints, available tools, success criteria, and failure boundaries; when any key condition is unknown, stop at the read-only stage.

Step 3: Form a plan

List the tools to be called, the objects that will change, the success criteria, and the safe exit method after failure.

Step 4: Execute actions

Execute in minimal sufficient steps and record evidence at key state changes; keep an associable state or receipt for every external call.

Step 5: Verify delivery

Output the results, verification evidence, unfinished items, risks, and clear next steps, and state facts, inferences, and unverified items separately.

Validation checklist

• The skill trigger conditions are consistent with the user's intent, and adjacent tasks were not misrouted to this skill.
• The inputs, target objects, versions, and output locations are all clear, and no guessed values were used to replace required values.
• All writes, payments, publications, or irreversible actions are within the scope of user authorization.
• The results have been verified with independent checks; "the command succeeded" or "the file exists" alone does not count as complete acceptance.
• The output includes actual evidence, failed/skipped items, remaining risks, and executable next steps.

Gotchas

1. Treating the plan as the result: Documentation or prompts are not the same as actual execution; the actual execution level must be indicated.
2. Retrying on error: A timeout or lost response may already have produced remote state; query first before deciding whether to retry.
3. Implicit scope expansion: Batch, full-scale, publication, overwrite, and payment are not natural extensions of ordinary read/write operations.
4. Version drift: When referencing external resources, record the version, tag, or commit; do not treat a mutable branch as release evidence.
5. Stale evidence: Caches, old screenshots, and historical tests cannot prove the current environment; refresh key evidence before delivery.

Non-applicability and boundaries

Do not exceed the scope given by the user; writes, payments, publications, and irreversible actions require explicit authorization. If the request requires a different skill, do not copy its body text; hand off by skill name and preserve the current task context.

Progressive disclosure

• When inputs/outputs, states, and authorization points need to be determined, read references/workflow-contract.md。
• When self-checking before delivery is needed, read references/validation-checklist.md。
• When encountering timeouts, partial success, or recovery scenarios, read references/error-recovery.md。
• For first runs, privilege-escalation refusal, and failure recovery, refer respectively to examples/happy-path.md、examples/boundary-refusal.md、examples/failure-recovery.md。