instant-share

Files (18)

• SKILL.md
• DESIGN.md · references/
• create_artifact.sh · scripts/
• from_template.sh · scripts/
• gen_images.py · scripts/
• list_artifacts.sh · scripts/
• list_tunnels.sh · scripts/
• mark_ready.sh · scripts/
• reap.py · scripts/
• secure_server.py · scripts/
• share.sh · scripts/
• stop.sh · scripts/
• validate_artifact.sh · scripts/
• verify.sh · scripts/
• blog.html · templates/
• file-download.html · templates/
• news-article.html · templates/
• research-report.html · templates/

SKILL.md (first lines)

# Instant Share

Share interactive web artifacts with verified URLs, admin controls, and automatic expiration. Supports static pages, React apps, multiplayer games, and sophisticated web applications.

---

## STOP - READ THIS FIRST

**Before you do ANYTHING with this skill, understand these rules:**

1. **ALWAYS use create_artifact.sh first** - This creates the artifact.json manifest (required)
2. **NEVER send a link until you see "Verified working"** in share.sh output
3. **NEVER mention, promise, or construct URLs yourself** - Only use URLs from share.sh output
4. **Read DESIGN.md before creating content** - No emojis, no purple, no gradients

**Where artifacts live:** `create_artifact.sh` creates directories inside the current conversation's sandbox automatically (via `$INSTANT_SHARE_ARTIFACT_DIR`, set by the harness). You do NOT need to pass paths — just run the scripts and the artifact lands in `sandbox/<this-conversation>/artifact_<id>/`. Everything you build for this thread stays scoped to it.

**Why create_artifact.sh is mandatory:**
- Creates `artifact.json` - the manifest that tracks name, purpose, status, URLs, and metadata
- Creates the proper directory structure with correct permissions
- Enables validation before sharing (share.sh checks for artifact.json)
- Without artifact.json, you're just sharing random files with no tracking

If you skip create_artifact.sh or send links before verification, **you will break things**.

---

## Agent Response Protocol (MANDATORY)

When a user asks you to share something, follow this EXACT conversational pattern:

```
User: "Create a shareable report about X"

Agent: "I'll create that report for you."
       *runs create_artifact.sh to create artifact directory*
       *writes content to $ARTIFACT/index.html*
       *runs share.sh and WAITS for output*
       *reads share.sh output, finds "Verified working" and the URL*

Agent: "Here's your report: [URL from share.sh output]"
```

**CRITICAL:** You must NOT send any message containing a URL until AFTER share.sh completes and shows "Verified working".

### What "Verified working" looks like:

```
============================================================
VERIFIED LIVE URL:

   https://example-words.trycloudflare.com/?key=TOKEN

============================================================

Status: Verified working
```

Only the URL shown in this output block is safe to send.

---

## Common Mistakes (DO NOT DO THESE)

### Mistake 1: Sending link before verification
```
WRONG:
Agent: "Here's your link: https://..."  <- Sent BEFORE running share.sh
Agent: *runs share.sh*                  <- Too late, link may be broken

RIGHT:
Agent: *runs share.sh*
Agent: *waits for "Verified working"*
Agent: "Here's your link: https://..."  <- Safe, URL is from output
```

### Mistake 2: Constructing URLs yourself
```
WRONG:
Agent: *sees tunnel URL in logs*
Agent: "Your link is https://xxx.trycloudflare.com/?key=abc"  <- NEVER construct URLs

RIGHT:
Agent: *copies exact URL from share.sh "VERIFIED LIVE URL" output*
```

### Mistake 3: Skipping create_artifact.sh (no artifact.json)
```
WRONG:
Agent: *writes HTML to random temp file*
Agent: share.sh /tmp/myfile.html         <- No artifact.json = validation fails

RIGHT:
Agent: ARTIFACT=$(create_artifact.sh --name "Report" --purpose "For user")
       # ^^^ This creates artifact.json with name, purpose, timestamps, status
Agent: *writes content to $ARTIFACT/index.html*
Agent: share.sh "$ARTIFACT" --background  <- Validates artifact.json exists
```

**artifact.json is the source of truth.** It stores:
- Artifact name and purpose
- Creation/update timestamps
- Status (building/ready)
- Public URL and admin URL (after sharing)
- Verification status

Without it, the artifact system cannot track or validate your share.

### Mistake 4: Using --html shortcut
```
WRONG:
Agent: share.sh --html "<h1>Hello</h1>"   <- Bypasses artifact system

RIGHT:
Agent: ARTIFACT=$(create_artifact.sh --ready --name "Quick Share")
Agent: echo "<h1>Hello</h1>" > "$ARTIFACT/index.html"
Agent: share.sh "$ARTIFACT" --background
```

From Deibler/edmund-harness, MIT.

More from Deibler/edmund-harness