stitch-scenario-skill-creator

Stitch Skill Creator

This skill guides the creation of new Stitch Scenario Skills. A Scenario Skill is a specialized "Prompt Architect" for a specific domain (e.g., stitch-ui-music-designer, stitch-ui-blog-designer).

Core Philosophy

All Stitch Skills created by this creator MUST adhere to the Stitch Design SOP:

Trigger Safety: The skill must ONLY trigger when the user explicitly mentions "Stitch".
Design First: Never execute. Always construct a high-quality prompt first.
Self-Contained: The skill should act as a specialized "Prompt Template" that encapsulates domain knowledge (e.g., a Music App needs a "Play Button", "Cover Art").

Workflow (Progressive Disclosure)

Keep this file concise. Use bundled references when you need full details:

Workflow: references/workflows.md
Output patterns: references/output-patterns.md

Quick start (Automated Creation)

Option A: Automated Creation (Recommended)

Use the bundled script to automatically generate the skill structure, SKILL.md (with Golden Template), and examples/usage.md.

# Usage: ./scripts/init_stitch_skill.py <scenario-name> --path <skills-directory>
./scripts/init_stitch_skill.py music-designer --path skills/

This will automatically:

Create skills/stitch-ui-music-designer.
Populate SKILL.md with the required SOP and Templates.
Create examples/usage.md.

Option B: Manual Creation (Only if needed)

Follow: references/workflows.md -> Manual creation.

Step 1: Define the Scenario

Identify the domain and name the skill following the strict naming convention: stitch-ui-<scenario>-designer.

Example Scenario: "Music Apps"
Skill Name: stitch-ui-music-designer (MUST start with stitch-ui-)
Example Scenario: "Login Pages"
Skill Name: stitch-ui-login-designer

Step 2: Create Directory Structure

mkdir -p skills/stitch-ui-<scenario>-designer/examples

Step 3: Write `SKILL.md` (The Golden Template)

You MUST use the following template for the new skill. It enforces the required SOP.

---

# <Scenario> Screen Designer

**Constraint**: Only use this skill when the user explicitly mentions "Stitch" or when orchestrating a Stitch design task.

This skill helps you construct high-quality prompts for <Scenario> flows to be used by the Stitch Orchestrator.

## Functionality
It encapsulates best practices for <Scenario> UI design and translates user intent into a structured Stitch prompt.

## Integration with Stitch Designer SOP
This skill is part of the **Stitch UI Orchestration** flow.
1.  **Orchestrator**: `stitch-ui-execute` calls this skill when a scenario-specific prompt is needed.
2.  **Guidelines**: You MUST apply principles from `stitch-ui-guide` (e.g., visual vocabulary, device constraints).
3.  **Output**: You do NOT execute. You return a prompt only.

## Prompt Template

When the user asks for a <Scenario> screen, use this template to construct the prompt:

```text
[Context]
[Device] <Scenario> screen for [App Name]. [Style] aesthetic.

[Layout]
Header: [...]
Body: [...]
Footer: [...]

[Components]
- [...]
- [...]
```

## Output Format (STRICT)

Return exactly one code block and no extra prose:

```text
[Context]
...

[Layout]
...

[Components]
...
```

## Usage in Orchestrator
This skill is designed to be called by `stitch-ui-execute`. It does NOT execute; it returns a prompt only.

Step 4: Write `examples/usage.md`

Provide at least 2 distinct examples of how this skill transforms a vague request into a detailed prompt.

Best Practices for New Skills

Domain Specificity: The value of a Scenario Skill is in its specific knowledge.
- Bad: "A page with text."
- Good (Music): "A player view with a scrubbing bar, album art, and waveform visualization."
Device Awareness: Ensure the template supports Mobile (default) and Desktop.
No Direct Execution: The Scenario Skill must not call any MCP tool. It produces the prompt that the Orchestrator uses.

References

When to use

Load this skill when the user needs to select and execute a verifiable, recoverable professional workflow for the current request . First extract the goal, inputs, constraints, delivery format, and acceptance criteria from the request; the description summary is: "A factory skill for creating new Stitch Scenario Skills. It enforces the "Design First, Execute Last" SOP and standard Stitch architectural patterns. Use this when you need to add support for a new domain e.g. "Music Apps" "Social Networks" to the Stitch ecosystem.".

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: preserve request identifiers and stage status; when the result is 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

Confirm the goal, inputs, constraints, available tools, success criteria, and failure boundaries; 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 change, the success criteria, and the safe exit path after failure.

Step 4: Execute actions

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

Step 5: Verify delivery

Output the results, verification evidence, incomplete 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 in place of required values.
All write, paid, publish, or irreversible actions are within the scope authorized by the user.
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

Treating a plan as a result: documentation or prompts are not the same as actual execution; the actual execution level must be stated.
Incorrect retry: a timeout or lost response may already have produced remote state; query first before deciding whether to retry.
Implicit scope expansion: batch, full-scale, publish, overwrite, and paid actions are not natural extensions of ordinary read/write operations.
Version drift: when referencing external resources, record the version, tag, or commit; do not treat a mutable branch as release evidence.
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, publishing, and irreversible actions require explicit authorization. If the request requires another skill, do not copy its content; 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 a 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 run, refusal of privilege escalation, and failure recovery, refer respectively to examples/happy-path.md、examples/boundary-refusal.md、examples/failure-recovery.md。