VVVLink Sitebuilder

Use this skill when the user wants to create, redesign, or

publish a website, landing page, portfolio, or any HTML page

that should be accessible online.

Before ANY work, announce to the user:

"Using vvvlink-site-builder to create and publish your site."

Quick Reference

• API Base: https://publish.vvvlink.com
• Site creation rules: See [website-development-rules.md](

references/website-development-rules.md)

• Full API docs: See [api-reference.md](

references/api-reference.md)

Direct Invocation

When the user invokes this skill directly (without a specific task),

show an intro and check for existing sites. Use Telegram formatting.

1. Load API key from ~/.vvvlink/config.json and call

GET /sites (if config exists)

1. Split sites by status: "live" and non-live ("uploading", etc.)
2. Show intro message based on result:

If user has live sites:

VVVLink Site Builder

Your sites:
1. my-site.vvvlink.com
2. cool-page.vvvlink.com

+2 drafts (uploading). Ask me to show or clean them up.

I can update any of these or create a new one.
What would you like to do?

Only show the drafts line if there are non-live sites.

If the user asks to see or manage drafts, list them with

subdomain, status, and offer to delete individual ones or

all at once via DELETE /sites/:siteId.

If no sites or no API key:

VVVLink Site Builder

I build and publish websites on vvvlink.com in seconds.

Describe what you need — a landing page, portfolio,
business site — and I'll design, build, and publish it.

Your site will be live with a unique URL right away.

When user picks an existing site to update, go to Step 10

(Updates) in the flow below.

Flow (strict order, no skipping)

Step 1: Announce and show progress

THIS IS THE MOST IMPORTANT RULE IN THIS SKILL.

The user sees your text output as a stream. While you write

text — they see it appearing live. When you make a tool call —

they see nothing until the tool returns and you write more text.

Therefore: WRITE TEXT BEFORE AND AFTER EVERY TOOL CALL.

In practice, your response should look like this (the user

sees each line appear as you stream it):

⚡ Building your site with VVVLink Site Builder...

🔍 Searching for photos of [topic]...
[tool call: curl image search]
📸 Found 5 great shots!

🎨 Designing layout with [palette] and [fonts]...
🏗️ Building hero section...
[tool call: write first part of HTML]
✨ Adding content sections...
[tool call: write rest of HTML]
📦 HTML ready!

🚀 Publishing to vvvlink.com...
[tool call: create site]
[tool call: upload file]
[tool call: publish]
[tool call: rename subdomain]

✅ Your site is live!
🌐 https://your-site.vvvlink.com

KEY RULES:

• Write at least one emoji + text line BEFORE each tool call
• The user must always see what you're doing RIGHT NOW
• NEVER make 2+ tool calls in a row without text between them
• If a tool call takes time, the preceding text is what the

user will see while waiting — make it informative

IMPORTANT: These progress rules apply ONLY when BUILDING a site

(multi-step process: photos → HTML → upload → publish).

For simple operations like listing sites or checking status —

just do it quickly, no need for multiple progress messages.

One short message before + result is enough.

Step 1.5: Ask for business details (if missing)

If the site looks like a business page (cafe, shop, studio,

agency, etc.) and the user did NOT provide key info, gently

ask ONCE before building. Keep it short — one message:

"📋 Before I start — want to add any of these to make it real?

📞 Phone / email / address

🕐 Opening hours

🔗 Social media links

Or I can build it now and you'll add details later."

If user says "just build it" or similar — proceed immediately.

Do NOT block the build. This is optional, not a gate.

Skip this step entirely for non-business sites (portfolios,

personal pages, experiments).

Step 2: Find photos for the site

Before writing any code, search for relevant photos:

# Search by keywords matching the site's topic
curl -s "https://publish.vvvlink.com/images/search?q=KEYWORD&count=5&orientation=landscape"

Pick 3-6 keywords based on the site content (e.g., "office",

"team", "technology"). Select the best photo for each section

(hero, about, features, etc.). Use the url field from

the response directly in tags.

Add &w=1600&h=900&fit=crop to URLs for hero images,

&w=600&h=400&fit=crop for cards.

Step 3: Create the site

Read and follow references/website-development-rules.md.

Build a high-quality static site using the photos from Step 2.

Output all files to ~/.vvvlink/sites//.

Step 4: Get API key

apiKey is SECRET. Never show it to the user, never log it,

never include in messages. It is only for Authorization headers.

UUID is public. It identifies the account. You may show it

to the user if asked.

Storage: ~/.vvvlink/config.json

{
  "uuid": "account-uuid",
  "apiKey": "SECRET-key-never-share"
}

Site files: ~/.vvvlink/sites//

Rules:

1. NEVER call /auth/create_new_user if ~/.vvvlink/config.json

exists. The apiKey is issued ONCE and cannot be recovered.

1. Only create a new account if config.json does not exist.
2. Protect ~/.vvvlink/config.json with chmod 600.

Procedure:

1. Read ~/.vvvlink/config.json → use .apiKey
2. If file does not exist → POST /auth/create_new_user {}

→ save response to config.json

# Load or create API credentials
VVVLINK_DIR="$HOME/.vvvlink"
VVVLINK_CONFIG="$VVVLINK_DIR/config.json"

if [ -f "$VVVLINK_CONFIG" ]; then
  VVVLINK_API_KEY=$(jq -r '.apiKey' "$VVVLINK_CONFIG")
else
  mkdir -p "$VVVLINK_DIR"
  RESP=$(curl -s -X POST https://publish.vvvlink.com/auth/create_new_user \
    -H "Content-Type: application/json" -d '{}')
  if echo "$RESP" | jq -e '.apiKey' > /dev/null 2>&1; then
    VVVLINK_API_KEY=$(echo "$RESP" | jq -r '.apiKey')
    echo "$RESP" | jq '{uuid: .uuid, apiKey: .apiKey}' \
      > "$VVVLINK_CONFIG"
    chmod 600 "$VVVLINK_CONFIG"
  else
    echo "Error: could not create account" >&2
    exit 1
  fi
fi

Step 5: Create site and upload

# Create site
curl -s -X POST https://publish.vvvlink.com/sites \
  -H "Authorization: Bearer $API_KEY"

# Upload each file (from ~/.vvvlink/sites/<subdomain>/)
curl -s -X PUT \
  "https://publish.vvvlink.com/sites/$SITE_ID/files/index.html" \
  -H "Authorization: Bearer $API_KEY" \
  --data-binary @~/.vvvlink/sites/$SUBDOMAIN/index.html

Upload ALL files: HTML, CSS, JS, images, fonts.

If POST /sites returns HTTP 429 with "Site limit reached",

the user has hit their plan limit. Handle this gracefully:

1. Call the upgrade endpoint to get a checkout URL:

curl -s -X POST https://publish.vvvlink.com/billing/upgrade \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"success_url": "https://vvvlink.com"}'

1. Show the user an upgrade message with the payment link.

In Telegram, use an inline link so the user can pay in

the built-in web view:

⚠️ *Site limit reached*

You've used all available sites on the Free plan\.

🚀 [Upgrade to Pro](PAYMENT_URL) to unlock up to 100 sites\.

_After upgrading, I'll publish your site right away\._

1. After the user pays and confirms, retry POST /sites.

The limit will be updated automatically.

If the upgrade endpoint returns "Already on Pro plan",

the user is already on Pro — this means they've genuinely

used all 100 sites. Tell them to delete unused sites first.

Step 6: Publish

curl -s -X POST \
  "https://publish.vvvlink.com/sites/$SITE_ID/publish" \
  -H "Authorization: Bearer $API_KEY"

Step 7: Choose subdomain BEFORE creating site

Do NOT create a site with a random name. Pick a good one first:

1. Analyze the site content (