Communitygithub.com

Portfolio Forge

Transform personal information into an exceptionally aesthetic, production-ready personal website. Content document as the single source of truth → taste-skill generates section reference images → adversarial per-image review iteration → Codex Frontend App Builder high-fidelity replication → headless per-section QA → reversible Cloudflare Pages deployment.

What is Portfolio Forge?

Portfolio Forge is a meticulously designed AI agent skill that empowers developers and users to craft a stunning, production-ready personal website or portfolio from scratch. The core innovation is a proven six-stage pipeline that starts with a content intake interview to clarify the user's identity, audience, and visual preferences. It then generates high-aesthetic reference images for each page section, followed by an adversarial review process where each image is rigorously challenged for typography, breathing space, and originality before being high-fidelity replicated using Codex's Frontend App Builder. The skill enforces a 'content document as single source of truth' policy to prevent hallucinated content, and before deployment, it performs a headless QA phase using Puppeteer to take real screenshots of each section and compare them against the reference images. Finally, deployment is reversible and non-destructive, always starting on an independent `*.pages.dev` domain, giving the user full control over any domain changes. This skill is designed for use with Claude as the orchestrator (handling interviews, writing, review, QA) and Codex as the execution engine (image generation and frontend building), paralleling tasks to keep iterations fast while maintaining a relentless focus on visual quality and user agency.

Works with✓Claude Code✓Codex CLI~Cursor
npx skills add https://github.com/Heng-xiu/xiuxiu-agent-skills/tree/HEAD/skills/portfolio-forge

Ask in your favorite AI

Open a new chat with this agent skill pre-loaded.

Documentation

What does Portfolio Forge do?

Mold "a person's information" into a production-ready, exceptionally aesthetic personal website. The core is a validated pipeline: Content Document (Single Source of Truth) → Reference Images → Adversarial Review → High-Fidelity Replication → Per-Section QA → Reversible Deployment.

Inspired by the "use Codex to build a personal website in two hours" four-step method (organize content → taste generates reference images → generate assets → replicate), this skill solidifies three truly quality-determining, undocumented steps: content document anti-hallucination, adversarial per-image review, and pre-launch headless QA.

When to Trigger

  • "Build a personal website," "build a portfolio," "turn my information into a website"
  • "personal website," "portfolio," "help me create a landing page"
  • "I want a personal page for external use," "In the AI era, a personal website is a resume"
  • Even just saying "Help me build a site," "Make a page for my stuff"

Prerequisites (Check First Time Use)

This pipeline requires three external tools. Install them first if missing (see workflows/reference-image-gen.md and workflows/frontend-replication.md for installation):

  1. taste-skill's imagegen-frontend-web — Generates high-aesthetic section reference images. Install to ~/.claude/skills/ and ~/.codex/skills/.
  2. Codex's build-web-apps plugin (includes Frontend App Builder skill) — High-fidelity replication. codex plugin add build-web-apps@openai-curated.
  3. Chrome + puppeteer-core — Headless QA for per-section screenshots.

Core Principles

  1. Content Document is the Single Source of Truth: Before building, compile the person's profile / positioning / style / color palette / section structure into a CONTENT.md file. Any AI-generated gibberish in reference images that contradicts this document must be overridden by the document. This is the foundation against hallucinations.
  2. Adversarial Per-Image Review: Reference images are not for replication; they are for challenging. For each image, ask: "Is the font size blown? Does it have breathing space? Does the composition fall into AI clichés? Are there hallucinated words? Are images consistent across sections?" If it fails, regenerate that single image. This step decides whether the result is "decent" or "truly beautiful."
  3. Real Assets First: Use real photos and project screenshots. AI is only for "style reference images" and "stylized assets," never for faking faces or screenshots. If the user provides photos, use them directly; do not generate new ones.
  4. Per-Section QA Means Completion: Replication is not delivery; it is acceptance. Use Puppeteer to scroll through the page, take screenshots of each section, and compare them side-by-side with the reference images. If something is off, return to the replication stage for iteration.
  5. Reversible Deployment, No Touch of Existing Assets: Always deploy first to an independent *.pages.dev. Before touching the user's existing domain, check the binding relationship, and treat "whether to switch domains" as the user's decision, never make it autonomously.
  6. Prioritize Human-Readable Copy (User feedback from 2026-07): Default the website body and promotional copy to be written for a non-technical audience — avoid technical stack terms (frameworks, databases, service providers) in the body; instead, explain "what this thing does and who it helps"; keep proper nouns only when the interview confirms the audience is technical. For installation/user instructions, prioritize "give this passage to your AI" type instructions, not terminal commands.

Workflow (Six Stages)

Stage 0: Clarify Positioning (Interview Convergence)

Follow workflows/content-intake.md. Use AskUserQuestion to converge on key decisions: who the site is for, positioning, visual style, language scale, asset sources, selected works, primary CTA, deployment target. For style options, refer to references/design-style-library.md (style is the most important input when taste generates images).

Stage 1: Content Document (Single Source of Truth)

Organize the interview results + externally fetched data (existing website, Substack, social media) into CONTENT.md, following the format in references/content-doc-template.md. This document is the basis for all subsequent stages.

Stage 2: Generate Section Reference Images

Follow workflows/reference-image-gen.md. Split the single page into 6–8 sections, generate one image per section using imagegen-frontend-web (run in the background via codex exec), and save to refs/.

Stage 3: Adversarial Review + Iteration (The Core)

Follow workflows/adversarial-design-review.md. Use Read to look at each image yourself and challenge it first, then present to the user for review. Regenerate failing single images. This step will go through several rounds — that's normal; do not skip it.

Stage 4: High-Fidelity Replication

Follow workflows/frontend-replication.md. Feed the "finalized reference images + CONTENT.md + real assets" as a complete package to Codex Frontend App Builder, aiming for 1:1 replication, data-driven + animations + RWD. For dynamic layers, select from references/motion-effects-library.md (11 battle-tested effect recipes) and write each into the replication prompt — iron rule: motion should serve the theme, respect prefers-reduced-motion, and limit to at most one major effect per page.

Stage 5: Per-Section QA

Follow the first half of workflows/headless-qa-and-deploy.md. Use Puppeteer to scroll through the section, take per-section screenshots, and compare against reference images using references/qa-checklist.md for verification. If not up to standard, return to Stage 4.

Stage 6: Deployment + Smoke Test

Follow the second half of workflows/headless-qa-and-deploy.md. Deploy to Cloudflare Pages on an independent *.pages.dev → online headless smoke test (HTTP status + asset loading + real first-screen capture) → hand back domain decisions to the user.

Sub-Agent / Tool Design

The heavy lifting of this pipeline is outsourced to Codex (image generation, replication), while Claude handles interviews, writing, adversarial review, QA verification, and deployment orchestration.

  • Image Generation / Replication: codex exec --skip-git-repo-check --full-auto "<prompt>", run in the background with run_in_background: true, and verify upon completion.
  • External Data Fetching: WebFetch (existing websites, Substack profiles and posts).
  • Screenshot QA: Headless Chrome or puppeteer-core (per-section screenshots, see workflow notes).
  • Deployment: wrangler pages.

Parallel Strategy: 7–8 reference images are generated sequentially in a single codex exec run (the imagegen skill outputs one per invocation); for regeneration, only rerun the images that need changes.

External Communication Tone

  • Full Traditional Chinese throughout, with technical terms and identifiers kept in the original.
  • At each stage, first say "What I'm going to do," then actively report completion, without waiting to be asked.
  • Adversarial review should be direct: which image is wrong and why, be clear, and give specific directions for modification.
  • After delivery/deployment, proactively report four things: branch, commit hash, whether merged, and whether worktree has been cleaned.
  • Before touching the user's existing domain/external assets, hand back the decision-making power to the user.

Individual skills in this repo

This repo contains 1 individual skill — each has its own dedicated page.

Related Skills