stitch-upload-to-stitch

Upload Local Assets to Stitch

Quick Start

1. "Upload the redacted store appointment page HTML; provide local reviewable results first."
2. "Upload brand DESIGN.md for the system to create; preserve the existing scope and sources."
3. "Upload the user-provided presentation PNG; flag missing inputs and verification status."

For designers, front-end developers, and teams maintaining this workflow. Designers provide intent and assets, developers provide engineering/tools, and the team preserves sources and acceptance status during handoff.

Capability Boundaries

✅ Good At

• Uploading redacted store appointment page HTML.
• Routing brand DESIGN.md to MCP upload_design_md。
• Uploading user-provided presentation PNG.

⚠️ Requires Assets

• A real projectId.
• A reviewed local file in a supported format.
• Credentials and upload authorization read via platform_secret_provider() .

❌ Not Applicable and Handoff

• Remotely applying a design system → stitch-manage-design-system.
• Generating an upload file from code → stitch-code-to-design.
• Publicly deploying a website → target deployment workflow, delivering an HTML asset package.

Workflow

1. Verify the file path, size, type, and target project, and ensure authorization covers these contents.
2. Image/HTML scripts use the credential chain via platform_secret_provider() , with environment first and user configuration as fallback; the CLI does not accept key or service root URL parameters.
3. Markdown does not go through the private REST script; after reading the file, encode it in-process and call the current MCP upload_design_md。
4. Private REST is pinned to https://stitch.googleapis.com and sent once only; redirects and automatic retries are prohibited.
5. Reconcile using the project resource name from get_project , the pure project ID fromlist_screens , and theget_screen from name: projects/{project}/screens/{screen} .

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 an assumption draft, 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 or collect user passwords; credentials are provided only by the environment or authorized connectors. Use only demo data in examples; before uploading, replace customer names, phone numbers, and order numbers with demo values, and check HTML, screenshots, and file metadata. Do not write keys, session cookies, full base64 text, or signed download URLs into reports/repositories. Do not fabricate unverified parameters, visuals, or business figures; outputs should note sources, decision rationale, what was actually executed, and what has not yet been verified.

• argv/logs/reports do not contain keys, base64, or full responses.
• PNG/JPG/JPEG/WEBP map to screenshot, HTML/HTM map to htmlCode; Markdown uses upload_design_md。
• REST only accepts the current results[].screen response and outputs the validated screen name.

Customizable: title, generated-by, file path. The service root URL is not customizable. Value-added checks: configure credentials; hand off small output IDs; no automatic retries or redirects.

FAQ

Q1: What is the main result delivered? Local HTML requests use htmlCode, text/html, and DOCUMENT; after remote execution, only screen/instance identifiers that have passed type, format, and project ownership validation are delivered. Full offline inputs, requests, and simulated receipts are in the local application example; request construction does not mean upload succeeded.

Q2: When should a different entry point be used instead? Remotely applying a design system → stitch-manage-design-system; generating an upload file from code → stitch-code-to-design; publicly deploying a website → the target deployment process, delivering an HTML asset package.

Q3: What happens when inputs are missing? First provide a clearly marked local assumption draft, and list "needs to be supplied: the real projectId; a reviewed local file in a supported format; the STITCH_API_KEY and upload authorization injected through the runtime environment." Write operations that depend on these inputs are not executed.

Q4: How is completion determined? argv/logs/reports contain no keys, base64, or full responses; the local REST and remote Markdown paths are separated; the returned screen name has been reconciled read-only.

Q5: How is it customized? title, generated-by, file path; the service root address is fixed to the official Google origin.

Q6: Does it automatically upload, install, or go live? Only actions covered by the current request and existing authorization are executed; without a remote receipt, do not claim upload succeeded, and without runtime verification, do not claim it is live. Additional installation or scope expansion requires first explaining the specific impact.

Reference as needed

• When executing detailed mappings, APIs, or templates, read Extended Process。
• When encountering failures or abnormal inputs, read Anti-patterns and Gotchas。
• When edge cases, compatibility, customization, and authorization are involved, read In-depth FAQ。
• When complete inputs, outputs, and verification scenarios are needed, read Local Application Example。
• The local implementation basis is the source code accompanying this 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 to have verified online behavior.

When to use

When the user needs to execute a generation or write operation after explicit inputs, budget, and delivery constraints are established load this skill. First extract the goal, inputs, constraints, delivery format, and acceptance criteria from the request; the description summary is: securely upload authorized local images or HTML to a specified Stitch project, and route Markdown to the remote upload_design_md; it is not triggered when only generating local files, retrieving a project, or deploying a website..

Rules

• Read before write: first confirm the current state and real capabilities, then execute 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 outputs are missing, clearly mark them as NOT_VERIFIED。
• Idempotency first: retain request identifiers and stage status; when results are unclear, query first and do not retry blindly.
• 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

Validate the input, model/tool capabilities, output path, budget cap, and approval status; if 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 be changed, the success criteria, and the safe exit method after failure.

Step 4: Execute actions

Execute upon one approval and record the request identifier; for ambiguous results, query first rather than resubmit; retain an associable status or receipt for every external call.

Step 5: Verify delivery

Verify artifact existence, format, hash/identifier, cost status, and quality gates, and state facts, inferences, and unverified items separately.

Validation checklist

• The skill trigger conditions are consistent with user intent, and adjacent tasks were not misrouted to this skill.
• The input, target object, version, and output location are all clear, and no guessed values were used to replace required values.
• All write, paid, publish, or irreversible actions are within the scope of user authorization.
• The results have been verified with independent checks; "command succeeded" or "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: A document or prompt is not equal to actual execution; the actual execution level must be indicated.
2. Retrying after errors: A timeout or lost response may already have produced remote state; query first before deciding whether to retry.
3. Implicit scope expansion: Batch, full-volume, publish, overwrite, and paid operations are not a natural extension of ordinary reads and writes.
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

Paid, publish, overwrite, upload, or external write actions must use the explicit authorization for the current task; do not automatically expand the number of attempts and the budget. If the request requires another skill, do not copy its body text; hand off by skill name and preserve the current task context.

Progressive disclosure

• When input/output, state, and authorization points need to be determined, read references/workflow-contract.md。
• When pre-delivery self-check is needed, read references/validation-checklist.md。
• When encountering timeouts, partial success, or recovery scenarios, read references/error-recovery.md。
• For first runs, refusal of overreach, and failure recovery, refer respectively to examples/happy-path.md、examples/boundary-refusal.md、examples/failure-recovery.md。