Lazyweb Skill Pack

The Lazyweb Autorouter follows several strict design constraints to ensure portability and reliability:

• Host Neutrality: The routing text itself must not use host-specific tool names (e.g., it should not say "ask ONE AskUserQuestion" because AskUserQuestion is a Claude-only tool). Instead, it uses host-neutral phrasing like "ask the user one short clarifying question."
• Byte Budget: To ensure compatibility with various hosts, the rendered routing block must not exceed 1,800 bytes per host. If a new skill mode causes the total to exceed this, the CI will fail.
• Routing Invariant: The router uses a structural invariant where route: entries must be non-empty and trigger-shaped, while the root table remains category-shaped.
• Idempotent Lifecycle: The router follows a specific cadence: install-time offer $\rightarrow$ one-time runtime fallback offer $\rightarrow$ silent idempotent refresh on every update $\rightarrow$ clean uninstall.

The routing block contains a table that maps user requests to specific Lazyweb skills. The table is designed to be extremely lightweight (under 1,800 bytes) to avoid consuming excessive context window space.

Routing Logic:

• Intent → Skill: The left column describes what the user is asking for, and the right column provides the exact skill identifier.
• Action Preamble: Above the table, there is a host-specific instruction telling the agent how to invoke the skill (e.g., using a slash command in Claude Code or reading a specific file path in Cursor).
• Constraints: The block explicitly defines when not to route (e.g., backend/CLI/infra work) to prevent the agent from incorrectly using Lazyweb for non-UI tasks.
• Ambiguity Handling: If a request is ambiguous, the instructions tell the agent to ask a short clarifying question or to state its assumption and proceed.

| The user asks for… | Skill |
|---|---|
| Design research, best practices, competitive analysis, "what do top apps do" | `lazyweb-deep-design-research` |
| Quick examples / screenshots / UI references, no full report | `lazyweb-lite-design-research` |
| Feedback on / improvement of an existing screen or design | `lazyweb-design-improve` |
| Creative, unconventional, cross-category design ideas | `lazyweb-design-brainstorm` |
| Paywall redesign or paywall conversion optimization | `lazyweb-optimize-paywall` |
| Rewriting or stress-testing one paywall CTA (button copy only) | `lazyweb-paywall-cta` |
| A/B tests, experiments, pricing/trial/monetization strategy | `lazyweb-ab-test-research` |
| Anything UI-related that fits none of the above | `lazyweb` (the router skill picks the mode) |

When running install, the router follows a specific logic to ensure it doesn't corrupt user files:

1. Resolution: It identifies the target file based on the host mapping.
2. Rendering: It generates a block containing the version and skill information.
3. Validation: The block must be $\le$ 1800 bytes.
4. Injection Logic:
   • If the file is missing: It creates the file with the block.
   • If markers exist (<!-- LAZYWEB:ROUTER:BEGIN and <!-- LAZYWEB:ROUTER:END -->): It replaces the content between the markers.
   • If the file exists but markers are missing: It appends the block to the end of the file after a blank line.
   • If markers are corrupt (e.g., BEGIN exists without END): It refuses to write and exits with error code 2.
5. Atomicity: Writes are performed via a temporary file and moved (mv) to preserve original permissions.
6. Manifesting: The operation is recorded in ~/.lazyweb/router.manifest.json with a block_sha256 for future integrity checks.

The first section of the report is the Agent Instructions. It consists of one plain human sentence followed by a copy-pastable HTML block designed for a downstream coding agent.

Structure of the Handoff Block:

• Human Sentence: The recommended bet, stated as the thing to build first.
• AI Block Content:
  • TOP RECOMMENDATIONS: An ordered list of bets to do first.
  • INDEX ON: The control frictions the recommendation attacks.
  • DO NOT OVER-INDEX ON: Directional or off-category signals to ignore.
  • DIVE FURTHER: The next Lazyweb skill or MCP tool to use.
  • Evidence basis: Count of Lazyweb references, web captures, and date.

Implementation Note: The HTML should include a Copy button that uses the Clipboard API to allow the coding agent to easily grab the LAZYWEB REPORT — AGENT HANDOFF text.

<section id="agent-instructions" class="agent-instructions">
  <div class="ai-head"><span class="ai-badge">FOR THE CODING AGENT</span>
    <button class="ai-copy" type="button" onclick="...">Copy</button>
  </div>
  <p class="ai-human">{one human sentence: the recommended bet, stated as the thing to build first}</p>
  <pre class="ai-block">LAZYWEB REPORT — AGENT HANDOFF
Use this report as a starting point for {TASK}.

TOP RECOMMENDATIONS (do first):
1. {recommended bet, one imperative line}
2. {runner-up bet}
3. {runner-up bet}

INDEX ON: {the control frictions the recommended bet attacks}
DO NOT OVER-INDEX ON: {directional-not-measured signals, off-category references}
DIVE FURTHER: {next Lazyweb skill or MCP tool} — {why}

Evidence basis: {N Lazyweb references + M web captures (+ experiments if used)} · {DATE}</pre>
</section>

The lazyweb-design skill handles product screen work (paywalls, landing pages, dashboards, etc.) by classifying the user's intent into one of three objectives. You must pick the objective INTENT-FIRST, not based on whether an image is currently available.

Important: For optimize and improve, you MUST have a screenshot. If you cannot capture one on the user's behalf, ask the user to upload one. If neither is possible, stop and inform the user. Never silently fall back to create if an image is missing for an optimize request.

// Example objective selection logic
if (user_wants_new_screen) {
  objective = "create";
} else if (user_wants_better_metrics) {
  objective = "optimize";
} else {
  objective = "improve";
}

To avoid corrupting large image files (like screenshots) by passing them as base64 strings through an LLM, the system uses a two-call presigned upload pattern. This ensures bytes are moved out-of-band via curl rather than through the model's context window.

The Workflow:

1. Request Upload: Call lazyweb_request_image_upload to get a temporary upload URL and a storage key.
2. Upload Bytes: Use curl to PUT the local file directly to the provided upload_url. This step uses the presigned URL for authentication, so no Lazyweb credentials are required in the shell command.
3. Resolve URL: Call lazyweb_resolve_image_upload using the key to obtain a signed image_url.
4. Use Image: Pass the resulting image_url to downstream tools like synthesize, start_mockup, render, compare_image, or find_similar.

# 1. Get upload details (via MCP tool)
# {upload_url, key} = lazyweb_request_image_upload({mime_type: 'image/png'})

# 2. Upload the file via curl
curl -fsS -X PUT -H "content-type: image/png" --data-binary @current-state.png "$upload_url"

# 3. Resolve the final URL (via MCP tool)
# {image_url} = lazyweb_resolve_image_upload({key})

# 4. Use the image_url in subsequent tool calls

To prevent unexpected changes to user configuration files, lazyweb-router install follows a strict consent model. It will never write to a file without explicit permission, obtained via:

• Interactive TTY Prompt: A preview of the target files and the rendered block is shown. The user must confirm. If no input is received within 30 seconds, it defaults to No.
• The --yes flag: Used for non-interactive environments or when pre-approved by the setup command.
• Existing Manifest Entry: If a user has previously approved a block for a specific file, subsequent refresh operations (updates) are considered authorized and do not require new consent.

If a user declines an installation, a router_declined=1 flag is written to ~/.lazyweb/config, and the router will respect this refusal in future automatic offers. Manual lazyweb-router install commands will always bypass this flag.

When using the lazyweb-design-create skill, all generated reports must adhere to four mandatory operating principles. These principles prioritize evidence-based claims over convenience and ensure high-confidence design recommendations.

1. Show, don't tell

Every assertion (patterns, anti-patterns, recommendations) must be accompanied by real screenshots rendered beside the claim.

• Snap-carousels: Use .deck snap-carousels for multiple references instead of bullet lists.
• Quantification: Use specific counts (e.g., "7 of 14 references") instead of prevalence adjectives like "most" or "dominant".
• No ASCII: Never use ASCII/box-drawing for layouts; use generated images or HTML/CSS mock-frames.

2. Be opinionated

• Single Recommendation: Lead with exactly ONE recommended bet, marked with a Recommended flag in the options carousel.
• Ranking: Avoid flat menus; the order of options must represent the ranking. Runners-up must explicitly state when to prefer them or when to skip them.

3. Maximize confidence with evidence

• Safe Bets: Backed by prevalence counts.
• Bold/Wild Bets: Backed by mechanism proof from outliers or cross-category references, combined with evidence of absence (e.g., "0 of 14 in-category references do this").
• Experimentation: Include learnings from lazyweb_search_ab_tests where available.

4. Be truth-seeking

• Evidence Strength: Label evidence as measured (real lift), directional (visual prevalence), or single source / outside this category within figcaptions or the .build-prompt.
• Avoid Overclaiming: Do not use comparative-performance verbs (e.g., "outperforms") without measurement.
• Corpus Banner: If evidence is single-source, thin (< 8 references), or context-mismatched, include a one-line .corpus banner immediately after Agent Instructions.
• Search Evidence: When claiming an absence, show the evidence-of-search (queries run × screens reviewed + closest near-miss).