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):
- taste-skill's
imagegen-frontend-web— Generates high-aesthetic section reference images. Install to~/.claude/skills/and~/.codex/skills/. - Codex's
build-web-appsplugin (includes Frontend App Builder skill) — High-fidelity replication.codex plugin add build-web-apps@openai-curated. - Chrome + puppeteer-core — Headless QA for per-section screenshots.
Core Principles
- Content Document is the Single Source of Truth: Before building, compile the person's profile / positioning / style / color palette / section structure into a
CONTENT.mdfile. Any AI-generated gibberish in reference images that contradicts this document must be overridden by the document. This is the foundation against hallucinations. - 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."
- 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.
- 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.
- 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. - 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 withrun_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.