Static Page Deploy (AI-Powered)

AI 生成静态页面 → 用户审核 → GitHub 推送 → Cloudflare Pages 自动部署 → .pages.dev 上线

When This Skill Triggers

Also trigger when: user describes a website/page they want + mentions deploy/host/上线/发布/展示页.

Architecture

用户描述需求
  ↓
AI 生成 HTML（内联 CSS，单文件可运行）
  ↓
show_widget 预览 → 用户确认
  ↓
mcp__github 推送到 GitHub
  ↓
Cloudflare Pages 自动部署
  ↓
projects.json 记录项目状态
  ↓
返回 https://xxx.pages.dev

适用场景与限制

✅ 适用场景（推荐）

本技能主要面向个人静态页展示类需求：

❌ 不适用场景（不推荐）

> ⚠️ 重要提醒：如果你做网站的主要目的是搜索引擎获客（SEO），本技能不建议使用。.pages.dev 二级域名在 Google/百度中的权重极低，几乎无法获得自然流量。此时建议购买独立域名（如 yourname.com）并配合专业建站工具。

Project State: projects.json

Maintained at ~/.workbuddy/skills/static-page-deploy/projects.json:

{
  "project-name": {
    "github_repo": "owner/repo",
    "cf_project": "project-name",
    "url": "https://project-name.pages.dev",
    "deployed_at": "2026-07-27",
    "description": "Product showcase for Riotouch IFP"
  }
}

Read this file first to determine if a project exists (Mode B) or is new (Mode A).

Two Modes

Mode A: AI Generate + First-Time Deploy

Full pipeline: requirements → AI generate → preview → confirm → GitHub → Cloudflare → live.

Mode B: Update Existing Project

Look up project in projects.json → push changes → verify deployment.

🆕 新手引导：账号注册与凭证获取

> 如果你从未使用过 GitHub 或 Cloudflare，请先完成以下注册步骤。整个过程大约 10 分钟。

1. GitHub 账号注册

GitHub 是代码托管平台，你的网站文件将存储在这里。

注册步骤：
1. 打开 https://github.com/signup
2. 输入邮箱地址（建议使用常用邮箱）
3. 创建密码
4. 选择用户名（将成为你的 GitHub 身份标识）
5. 完成人机验证
6. 验证邮箱（查收邮件点击确认链接）

创建 Personal Access Token（部署必需）：

注册完成后，需要创建一个 Token 让 AI 能帮你推送代码：

1. 登录 GitHub，点击右上角头像 → Settings
2. 左侧滚动到底部 → Developer settings
3. 点击 Personal access tokens → Tokens (classic)
4. 点击 Generate new token (classic)
5. 填写 Note：static-page-deploy
6. 勾选权限：repo（完整仓库控制）
7. 点击 Generate token
8. 立即复制保存！ 页面关闭后无法再次查看

> ⚠️ 重要：Token 只显示一次，请妥善保存。不要分享给他人。

2. Cloudflare 账号注册

Cloudflare 提供免费的静态网站托管服务（.pages.dev）。

注册步骤：
1. 打开 https://cloudflare.com/
2. 点击 Sign up
3. 输入邮箱和密码
4. 验证邮箱

创建 API Token（部署必需）：

1. 登录 Cloudflare，点击右上角头像 → My Profile
2. 顶部导航选择 API Tokens
3. 点击 Create Token
4. 选择 Edit Cloudflare Pages 模板
5. 权限：Pages:Edit + Account:Read
6. 点击 Create Token
7. 立即复制保存！

获取 Account ID：

1. 登录 Cloudflare Dashboard
2. 左侧选择 Workers & Pages
3. 右侧 Account ID 显示在页面右侧
4. 复制保存

3. 凭证清单

完成注册后，你将拥有：

> 💡 提示：首次部署时，AI 会向你索要这些凭证。之后可以保存在环境变量中避免重复输入。

Mode A: Step by Step

Step 0: Check for Existing Project

Read projects.json. If the user mentions a project name that exists → Mode B.

If new project, proceed.

Step 1: Collect Requirements

Ask the user for:

1. Purpose: What's this page for? (portfolio, product showcase, landing page, etc.)
2. Content: What content should it have? (text, images, features list, etc.)
3. Style: Any style preferences? (minimal, corporate, colorful, dark mode, etc.)
4. Language: Chinese, English, or bilingual?

If the user is vague, make reasonable assumptions and confirm:
"I'll create a clean, modern landing page with the content you described. Sound good?"

Step 2: AI Generate HTML

Generate a complete, self-contained HTML file:

Requirements:
- Inline all CSS in <style> (single file, no external dependencies)
- Responsive design (mobile-friendly)
- Modern, clean aesthetic
- Use placeholder images from https://picsum.photos/ or https://placehold.co/ if needed
- Semantic HTML5 structure
- If user provides specific content/text, use it verbatim

Output format:

<!DOCTYPE html>
<html lang="zh-CN">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>...</title>
  <style>
    /* All CSS inlined */
  </style>
</head>
<body>
  <!-- Content -->
</body>
</html>

Save to a temporary directory: ~/.workbuddy/skills/static-page-deploy/tmp/{project-name}/index.html

Step 3: Preview & Confirm

Use show_widget to render the HTML inline for the user to preview.

Say: "Here's a preview of your page. Want to deploy it, or should I change something?"

Wait for user confirmation before proceeding to any external action.

Step 4: Collect Credentials

4a. GitHub Token
- Check conversation context or environment
- If missing: ask user for token
- Scope: repo
- Generate: https://github.com/settings/tokens

4b. Cloudflare API Token
- If missing: ask user for token with Pages:Edit + Account:Read
- Generate: https://dash.cloudflare.com/profile/api-tokens

4c. Cloudflare Account ID
- Auto-discover via Cloudflare API: GET /accounts with the token
- If multiple accounts found, ask which one

4d. GitHub Username
- Auto-discover: GET /user with GitHub token
- Use the login field

Step 5: Create GitHub Repository

Use mcp__github__create_repository:

{
  "name": "{project-name}",
  "description": "{description}",
  "private": false,
  "auto_init": true
}

If repo already exists, ask user to confirm reuse.

Step 6: Push Files to GitHub

Use mcp__github__create_or_update_file for each file:

mcp__github__create_or_update_file(
  owner: "{owner}",
  repo: "{repo}",
  path: "index.html",
  content: "{base64-encoded-content}",
  message: "Initial commit: AI-generated static site",
  sha: null  // for new files
)

For full sites (CSS/JS/images), push each file individually via the same tool.

Also push _headers for security:

/*
  X-Frame-Options: DENY
  X-Content-Type-Options: nosniff
  Cache-Control: public, max-age=3600

Step 7: Create Cloudflare Pages Project

Use WebFetch to call Cloudflare API:

POST https://api.cloudflare.com/client/v4/accounts/{account_id}/pages/projects
Authorization: Bearer {cf_token}
Content-Type: application/json

{
  "name": "{project-name}",
  "production_branch": "main",
  "source": {
    "type": "github",
    "config": {
      "owner": "{owner}",
      "repo_name": "{repo}",
      "production_branch": "main"
    }
  }
}

Step 8: Authorize & Verify

Tell user:

Almost done! One manual step:
1. Go to https://dash.cloudflare.com/{account_id}/pages/view/{project-name}
2. Click "Connect GitHub" to authorize
3. This can't be automated — Cloudflare requires browser session

After user confirms:
1. Wait ~30 seconds
2. Check deployment: GET /accounts/{id}/pages/projects/{name}/deployments?per_page=1
3. Verify: curl -sI https://{name}.pages.dev → 200

Step 9: Save Project State

Append to projects.json:

"project-name": {
  "github_repo": "owner/repo",
  "cf_project": "project-name",
  "url": "https://project-name.pages.dev",
  "deployed_at": "2026-07-27",
  "description": "..."
}

Step 10: Summary

Deployed successfully!

Project:   {project-name}
GitHub:    https://github.com/{owner}/{repo}
Live URL:  https://{name}.pages.dev

Next time, just say "update {project-name}" and I'll push changes.

Mode B: Update Existing Project

1. Look up project: Read projects.json, find by name
2. Get new files: Either AI-generate new version or use local files
3. Push to GitHub: Use mcp__github__create_or_update_file (with SHA for updates)
4. Verify deployment: Check Cloudflare deployment status
5. Report: URL + status

If Cloudflare Pages doesn't auto-deploy:

POST /accounts/{id}/pages/projects/{name}/deployments
Body: {}

Decision Tree

User wants to deploy
  |
  +-- Project exists in projects.json?
  |     |
  |     +-- YES → Mode B (update)
  |     |     1. Look up project details
  |     |     2. Get updated files
  |     |     3. Push via mcp__github
  |     |     4. Verify deployment
  |     |
  |     +-- NO → Mode A (new)
  |           1. Check for local files
  |           2. If no files → AI generate
  |           3. Preview → confirm
  |           4. Collect credentials
  |           5. Create repo via mcp__github
  |           6. Push files via mcp__github
  |           7. Create CF Pages project
  |           8. User authorizes
  |           9. Verify + save state

Critical Pitfalls

1. production_branch Must Be "main"

After creating or updating a Pages project, ALWAYS set production_branch to "main". Cloudflare sometimes auto-creates a cloudflare/workers-autoconfig branch and points the project there. If this happens, the deployed content will be stale or empty.

PATCH /accounts/{id}/pages/projects/{name}
{
  "production_branch": "main",
  "source": {
    "type": "github",
    "config": {
      "owner": "{owner}",
      "repo_name": "{repo}",
      "production_branch": "main"
    }
  }
}

2. Project Names: Lowercase + Dashes Only

Cloudflare API rejects uppercase letters and most special characters.
- Valid: my-site, barry-portfolio, cool-project-123
- Invalid: MySite, barry_site, -start-dash, end-dash-

3. GitHub Authorization Cannot Be Automated

After creating a Pages project with GitHub source, the user MUST manually authorize Cloudflare to access their GitHub repo. This is a browser-based OAuth flow that cannot be done via API.

4. Always Preview Before Deploy

Never skip the preview step. User must confirm before any external action (GitHub push, CF create).

5. Token Security

• Never log or display tokens in conversation
• Don't save tokens to projects.json or any file
• Ask user to provide tokens each session (or use environment variables)

6. Separate Repos for Worker vs Pages

If the user has both a Cloudflare Worker and Pages, use separate GitHub repos. Sharing a repo causes the Worker's cloudflare/workers-autoconfig branch to conflict.

Cloudflare API Reference

All endpoints: https://api.cloudflare.com/client/v4

Auth: Authorization: Bearer {cf_token}

GitHub MCP Reference

Use mcp__github tools (load via ToolSearch first):

File Structure

~/.workbuddy/skills/static-page-deploy/
├── SKILL.md              # This file
├── projects.json         # Project state (created on first deploy)
├── references/
│   └── troubleshooting.md
└── tmp/                  # Temporary AI-generated files
    └── {project-name}/
        ├── index.html
        ├── style.css    # Optional: separate CSS
        └── script.js    # Optional: separate JS

Bonus: After First Deployment

Once the site is live, optionally suggest:

1. Add _headers file for security and cache control:

/*
  X-Frame-Options: DENY
  X-Content-Type-Options: nosniff
  Cache-Control: public, max-age=3600

2. Add _redirects file for clean URLs:

/about  /about.html  200
/faq    /faq.html    200

3. Connect a custom domain in Cloudflare Dashboard → Pages → Custom domains

4. Enable Cloudflare Analytics for visitor insights