build-personal-site

name

build-personal-site

description

Route and coordinate the personal website skill suite for creating, recreating, personalizing, adding content to, validating, editing, or preparing a static personal website or blog. Use when the agent needs to choose between theme search, style reference research, original build, website style recreation, personalization, post import, review, local edits, or publishing preparation, or when the user asks what step comes next in an existing site-building workflow.

Build Personal Site

Goal

Coordinate the personal site skill suite into a reliable workflow.

This is an orchestration skill, not an implementation skill. It should route to the right specialized skills, enforce quality gates, and keep the workflow moving until the current request reaches its natural stopping point.

Do not duplicate the detailed implementation rules from child skills. Load and follow child skills when their step is reached.

For user-facing "from idea to personal site" or one-click launch requests, prefer from-idea-to-personal-site. Use this skill as the lower-level route coordinator when the next step or child skill choice is the main problem.

Contract

Inputs:

• User request, site folder or desired output folder, references, identity materials, content materials, and optional publishing target.
• Current workflow state when the user asks what to do next.

Outputs:

• Chosen workflow route and executed child skills.
• A local static site, validated existing site, imported content, focused edit, or publishing preparation depending on the request.
• Handoff summary with site folder, preview/publish status, validation performed, and remaining manual steps.

Boundaries:

• Do not implement child-skill details directly when a specialized child skill applies.
• Do not run every child skill by default; choose the shortest chain that satisfies the request.
• Do not publish, push, create projects, bind domains, or change DNS unless explicitly requested.
• Do not skip review-static-site after generation, recreation, personalization, post import, or broad edits.

Success gate:

• The chosen child-skill chain reaches the user's natural stopping point: direction selected, site built, content added, site validated, edit completed, or deployment prepared/performed.
• Required quality gates pass or the user explicitly accepts documented limitations.

If gate fails:

• Route the failed gate to the smallest responsible child skill.
• Re-run the affected validation.
• Stop and report the blocker only when missing user content, missing credentials, unavailable assets, or external account actions prevent progress.

Child Skills

Use these skills as the workflow building blocks:

• search-blog-theme: discover and compare personal site/blog theme directions.
• find-style-references: search and inspect real websites/templates/screenshots for a chosen direction and produce a build-ready reference brief.
• make-personal-site: create an original zero-dependency static personal site.
• copy-website-style: recreate the style, layout, motion, and page types of a specific reference website.
• personalize-site: replace placeholder/demo/source identity with the user's own content.
• add-blog-posts: import Markdown, Obsidian notes, Word drafts, old HTML posts, images, math, links, and other writing into an existing site.
• edit-site-part: make focused local changes to a specific section, component, copy block, style detail, or interaction.
• review-static-site: validate static output for links, page types, browser rendering, encoding, placeholder residue, direct-open compatibility, and path correctness.
• publish-static-site: prepare or perform deployment to GitHub Pages, Cloudflare Pages, Netlify, or Vercel.

If a child skill name changes, prefer the locally installed skill with the matching purpose.

Child Skill Contract Matrix

Use this matrix to decide handoffs and repair loops:

Child skill	Required input	Expected output	Success gate	If gate fails
search-blog-theme	User taste, purpose, references, or keywords	3-5 directions, verified reference URLs, one recommendation	Direction is specific enough to build	Search more references, sharpen metaphor, or ask one preference question
find-style-references	Chosen style direction, site type, mood words, or examples	4-8 real references, browser observations, build-ready design brief	Multiple search angles and at least 3 strong references inspected when possible	Broaden search, inspect stronger references, or return to search-blog-theme
make-personal-site	Direction, content/profile hints, page scope, output folder	Plain static site with representative pages, assets, EDITING.md	Required page types, relative paths, UTF-8 source, local preview	Fix structure/paths/assets, then review-static-site
copy-website-style	Target URL/screenshot/template and scope	Static style recreation with page map, placeholders/user content, EDITING.md	Signature layout/motion/page types match requested fidelity	Reinspect target, iterate recreation, then review-static-site
personalize-site	Existing site plus user identity/content	Replaced identity, links, metadata, assets, placeholder/source cleanup	User content visible and residue removed	Re-inventory content locations or use edit-site-part for layout fit
add-blog-posts	Existing site plus source posts/assets	New post pages, updated indexes/data, copied assets, editing notes	Posts render, links/assets/math/rich content work	Fix conversion/index/assets or use edit-site-part for local presentation issues
edit-site-part	Existing site plus target page/region/change	Small scoped code/content/style/interaction edit	Same browser region shows requested change without unrelated breakage	Remap source and make smaller corrective edit
review-static-site	Static root, expected scope, optional forbidden strings/reference	Findings or fixes, audit/browser result, pass/fail state	No blockers remain	Route blocker to the smallest responsible child skill
publish-static-site	Validated deploy root plus chosen platform/mode	Deployment settings/configs, optional live URL, post-deploy check	Correct folder deployed and live URL works	Fix local blockers, deployment settings, or account/DNS steps

Operating Principles

• Route first, then execute. Decide the correct chain before making broad edits.
• Keep each step's output usable by the next step.
• Prefer plain HTML/CSS/JS and zero dependencies for this version unless the user explicitly asks for another stack.
• Do not turn a personal site or blog into a marketing landing page.
• Do not invent detailed personal facts when user data is missing.
• Replace copied source-site identity by default in style recreations.
• Use page-relative links and assets by default; avoid root-absolute site-local paths such as /assets/... or /posts/....
• Validate with review-static-site after any generation, recreation, personalization, post import, or broad edit.
• Stop at a local validated site unless the user explicitly asks to publish.
• Do not create repositories, push code, deploy, bind domains, or change DNS unless the user explicitly asks.

Intake

Collect only the information needed for the next decision. Do not over-interview the user.

Useful inputs:

• Desired output folder or existing site folder.
• Whether the user wants a new site, a recreation of a reference, content import, personalization, a local edit, validation, or publishing.
• Reference URLs, screenshots, templates, or theme words.
• User identity materials: name, bio, links, resume, projects, avatar/logo, old homepage, GitHub profile.
• Content materials: Markdown, Obsidian notes, Word documents, old posts, image folders, or pasted text.
• Publication target: GitHub Pages, Cloudflare Pages, Netlify, Vercel, or guidance only.

If the request is clear enough, proceed. Ask a concise question only when multiple routes would produce very different work.

Router

Choose the workflow based on the user's current state:

• Vague idea or "find me a style": use search-blog-theme, then find-style-references before an original build.
• Chosen direction and no specific target site: use find-style-references, then make-personal-site.
• Specific target URL/screenshot/template to closely match: use copy-website-style.
• Existing generated site that still has placeholders or copied identity: use personalize-site.
• Existing site plus new articles/notes/documents: use add-blog-posts.
• Existing site plus one small visual/copy/layout/interaction change: use edit-site-part.
• "Check this site", "is this good enough", "before publishing": use review-static-site.
• "Deploy", "publish", "GitHub Pages", "Cloudflare Pages", "Netlify", "Vercel": use publish-static-site, after review-static-site.

When the user asks for a complete one-click build, choose the shortest chain that handles the real inputs. Do not run every child skill just because it exists.

Route Examples

Use these examples to stabilize routing:

User request pattern	Route
"I want a distinctive personal blog, help me choose a style"	search-blog-theme
"Find real references for this chosen style before building"	find-style-references
"Make me a personal site in this chosen direction"	find-style-references -> make-personal-site -> review-static-site
"Build a complete personal blog from scratch"	search-blog-theme if needed -> find-style-references -> make-personal-site -> personalize-site if content exists -> review-static-site
"Use this URL as the reference and recreate it"	copy-website-style -> personalize-site -> review-static-site
"Copy this website but replace the person's content with mine"	copy-website-style -> personalize-site -> review-static-site
"Here is my generated site, replace placeholders with my bio/projects/links"	personalize-site -> review-static-site
"Add this Markdown/Obsidian/Word article to the site"	add-blog-posts -> review-static-site
"Change this one section/color/title/card/menu"	edit-site-part; add review-static-site only if shared structure or assets changed
"Check whether this site is ready"	review-static-site
"Deploy this to Cloudflare Pages/GitHub Pages/Netlify/Vercel"	review-static-site -> publish-static-site
"It works locally over HTTP but not by double-clicking index.html"	review-static-site; fix path gate failures before publishing

Standard Pipelines

Idea To Original Site

Use when the user has only a rough goal or style preference.

1. search-blog-theme if the visual direction is unclear.
2. find-style-references to ground the chosen direction in real websites/templates/screenshots.
3. make-personal-site to create the static site.
4. personalize-site if the user supplied identity/content or the site has placeholders that should be filled.
5. review-static-site as the hard QA gate.
6. Stop with local preview instructions unless publishing was requested.

Reference To Personal Site

Use when the user gives a target URL, screenshot, v0 template, Figma design, or existing website to match.

1. copy-website-style to recreate the layout, motion, page types, and interactions.
2. personalize-site to replace target identity and placeholder content.
3. add-blog-posts if the user supplied writing content.
4. review-static-site as the hard QA gate.
5. Stop with local preview instructions unless publishing was requested.

Content First Blog

Use when the user's strongest input is articles, notes, Markdown, Word files, or an old writing archive.

1. Use search-blog-theme only if no site/theme exists.
2. Use find-style-references if a new original visual system is needed.
3. Use make-personal-site if no static site exists yet.
4. Use add-blog-posts to import the content into the existing site's post system.
5. Use personalize-site if identity/profile content remains generic.
6. Use review-static-site as the hard QA gate.
7. Stop with local preview instructions unless publishing was requested.

Existing Site Improvement

Use when the user already has a generated site folder.

1. Inspect the site and EDITING.md if present.
2. Use personalize-site for identity/content replacement.
3. Use add-blog-posts for article imports.
4. Use edit-site-part for focused design or copy changes.
5. Use review-static-site when the change affects navigation, page types, assets, encoding, publishing readiness, or more than one page.

Publish Ready Site

Use when the user asks to publish or deploy.

1. Use review-static-site first.
2. Fix blockers or route to the relevant child skill if review finds issues.
3. Use publish-static-site only after the site passes the necessary local checks or the user accepts known risks.
4. Verify the live URL when deployment happens.

Quality Gates

The workflow is not done until the relevant gates pass or the user accepts an explicit limitation.

Theme gate:

• The visual direction or reference is specific enough to build.
• If the build is original and based on taste words, real style references have been searched from multiple angles and at least 3 strong references have been inspected when possible, or the user explicitly waived that step.
• The chosen approach matches the user's site type: blog, portfolio, research homepage, digital garden, notes, links, or hybrid.

Structure gate:

• Required page types exist, not only the home page.
• Blog-like sites include at least one article/detail page and a list/archive entry point.
• Navigation points to real generated pages.

Content gate:

• User-provided identity/content appears in the intended places.
• Placeholder-only content is clearly marked or replaced.
• Copied source-site identity is removed from style recreations unless the user owns it or has permission.

Path gate:

• Site-local links and assets are page-relative by default.
• Nested pages use correct ../ depth.
• HTML, CSS url(...), JavaScript-generated links, data files, cover images, fonts, and vendor assets avoid accidental root-absolute paths.
• Direct index.html opening should not lose CSS, JS, images, or navigation.

Encoding gate:

• HTML includes UTF-8 charset.
• Source files are valid UTF-8 and readable, not browser-recovered mojibake.
• Non-ASCII content remains readable in HTML, JS strings, JSON/data files, SVG text, and EDITING.md.

Browser gate:

• An actually available interactive browser tool is used first when exposed in the current turn's callable tool list. In Codex this may be the Browser/in-app browser plugin when routed into the turn; in other agents it may be an equivalent visible browser, browser-use tool, or devtools-backed browser.
• If no interactive browser tool is callable, the agent must not pretend browser validation happened. It should ask the user to enable or invoke the browser tool when that validation matters, or use Playwright/screenshots/static checks as fallback and state the limitation.
• Playwright or screenshots-only checks are fallback paths, not the default.
• Local HTTP preview works.
• Desktop and mobile layouts are usable.
• Representative page types have been opened.
• Core interactions work.
• Console and network do not show obvious broken local assets.

Publishing gate:

• review-static-site has run or been explicitly declined.
• The deploy root is known and contains index.html.
• The platform settings are clear.
• Remote actions are explicitly authorized.

Loop Behavior

Use a closed loop:

1. Build or modify with the chosen child skill.
2. Validate with the relevant gate.
3. If the gate fails, route to the smallest child skill that can fix the issue.
4. Re-run the affected validation.
5. Stop when the site is locally usable and the user's requested scope is satisfied.

Do not loop forever. If a blocker requires missing user content, missing credentials, unavailable assets, or an external account action, report the exact blocker and the next user action.

Handoff And Reporting

Keep user-facing reports short and action-oriented.

For a normal completed local build, report:

• The route used.
• The site folder and local preview URL or file path.
• The major files or page types created/changed.
• The validation performed.
• Any remaining placeholders or manual steps.

For a published site, also report:

• Platform and deploy mode.
• Deploy root.
• Live URL.
• Official platform guide used by publish-static-site.
• Post-deploy verification performed.

Do not expose long internal routing logs unless the user asks.