make-personal-site

name	make-personal-site
description	Use this skill when the user wants to create, implement, redesign, or update a zero-dependency personal website, personal blog, homepage, portfolio, research homepage, or digital garden using plain HTML, CSS, and JavaScript. Use it after a theme direction has been chosen, or when the user wants a no-framework site that can be opened directly in the browser and deployed as static files.

Make Personal Site

Goal

Create or redesign a personal website as plain static files: HTML, CSS, and optional vanilla JavaScript.

This skill is the implementation step after a visual direction has been chosen. It turns a theme recommendation, user profile, notes, sample posts, project descriptions, or existing static site folder into a working personal site.

Core promise:

• No framework.
• No build step.
• No package install.
• No runtime dependency.
• Open index.html directly for manual preview.
• Use page-relative links and assets so direct file opening, local HTTP, and static hosting all work.
• Deploy the folder to static hosting.

For automated browser QA, serve the static folder over local HTTP instead of opening file:// URLs.

Contract

Inputs:

• Theme direction, user profile materials, page needs, sample content, or an existing static folder.
• Optional references that should guide style without requiring a high-fidelity replica.
• Desired output folder and static constraints.

Outputs:

• A plain static site folder with HTML, CSS, optional vanilla JavaScript, local assets, and representative page types.
• EDITING.md for future edits when a new site or material redesign is created.
• Local preview instructions and validation summary.

Boundaries:

• Do not closely recreate a specific target website; use copy-website-style.
• Do not import large writing archives; use add-blog-posts.
• Do not publish or configure hosting; use publish-static-site.
• Do not introduce frameworks, package installs, backends, CMS, auth, or databases unless the user explicitly asks.

Success gate:

• Required page types exist and navigation points to real relative paths.
• The site works as plain static files with no build step.
• Source is UTF-8-readable, placeholders are clear, and review-static-site can pass or only report accepted limitations.

If gate fails:

• Fix missing page types, paths, assets, encoding, placeholders, or browser issues inside this skill.
• Use personalize-site when the failure is missing user identity/content.
• Use review-static-site again after fixes.

Short Pipeline

Follow this pipeline for original personal site work:

1. Clarify the site purpose, theme direction, available content, and page scope.
2. Decide the static page map and placeholder strategy before coding.
3. Build the shared shell first: header, navigation, main layout, footer, global CSS variables, and shared interactions.
4. Implement the home page and every requested or implied page type.
5. Use the user's content or clearly replaceable placeholders; do not invent detailed personal identity.
6. Add an editing guide for future model/user edits.
7. Verify direct-open path compatibility with relative links and assets.
8. Validate locally over HTTP in a real browser.
9. Verify links, assets, page types, and UTF-8 source readability before final delivery.

Use When

Use this skill when the user:

• Wants a plain HTML/CSS/JS personal site, blog, homepage, portfolio, research homepage, or static website.
• Asks to implement a theme direction produced by search-blog-theme.
• Wants a simple no-framework site that is easy to inspect, edit, and deploy.
• Wants to redesign an existing static site while keeping it dependency-free.
• Provides loose visual references, but does not require a high-fidelity replica.

Do Not Use When

Do not use this skill when:

• The user only wants to search for themes or compare visual references. Use search-blog-theme.
• The user wants to closely recreate a specific website's look, layout, motion, or interaction feel. Use copy-website-style.
• The user wants to migrate many posts, convert Obsidian notes, repair frontmatter, or move large content archives. Use add-blog-posts.
• The user only wants deployment, DNS, GitHub Pages, Cloudflare Pages, Cloudflare Pages Direct Upload, Netlify, or Vercel help. Use publish-static-site.
• The user explicitly asks for a framework project such as Next.js, Astro, Hugo, Jekyll, Quartz, or React.
• The user asks for a backend, database, authentication, CMS, comments system, or dynamic server behavior.

Inputs

Use whatever the user provides. Do not block if some details are missing.

Useful inputs include:

• Theme direction: private code archive, research log dashboard, digital garden, bento portfolio, field notebook, personal operating system, etc.
• User profile: name, short bio, role, location, social links, avatar, resume, publications, projects.
• Page needs: home, about, blog, projects, notes, publications, contact.
• Sample content: 1-3 posts, project descriptions, Markdown snippets, older HTML pages.
• Existing site folder: current HTML/CSS/JS files to preserve or refactor.
• Loose references: v0, Figma, GitHub themes, framework templates, screenshots, or mood references.

Reference Rule

References may come from any stack. Treat them as visual and structural references, not implementation choices, unless the user explicitly asks to use that framework.

For a plain static site, translate references like this:

• React, Next, or Astro components -> repeated HTML sections with reusable CSS classes.
• Tailwind utility classes -> normal CSS rules in assets/style.css.
• Framework routes -> linked .html files.
• Content collections or CMS data -> static HTML lists or small JSON files.
• Theme configuration -> CSS custom properties.
• Simple interactions -> vanilla JavaScript only when useful.

If the user wants to closely match a specific website, hand off to copy-website-style instead of treating it as a loose reference.

Default Site Structure

For a new site, prefer this structure unless the user asks otherwise:

site/
  index.html
  EDITING.md
  about.html
  blog.html
  projects.html
  posts/
    first-post.html
  assets/
    style.css
    script.js
    images/
  data/
    posts.json
    profile.json

For an existing site, preserve the user's current structure when practical. Do not rename or reorganize large parts of the site unless it clearly improves the requested work.

Page Expectations

Create only the pages needed for the user's request. For a complete personal site starter, include:

• Home: identity, short intro, theme-specific hero area, recent posts, selected projects.
• About: bio, interests, skills, contact, social links, optional CV/publications.
• Blog index: post list with title, date, tags, and summary.
• Post page: readable article layout with title, date, tags, content, and navigation back to the blog index.
• Projects: project cards or rows with description, stack, links, and outcome.

Keep the first screen useful. Do not create a marketing landing page when the user asked for a personal website or blog.

For a complete personal site or blog starter, do not stop at a single homepage. Create working representative page types, even when the content is placeholder-only:

• At least one article/detail page for a blog.
• A list or archive page when posts, notes, projects, or publications are part of the site.
• A profile/about page when the home page links to identity or background details.
• Any special page implied by the chosen concept, such as notes, links, garden, now, uses, publications, or experiments.

For large future content collections, create the structure and a few representative placeholder entries rather than inventing a full archive.

Path Compatibility Rule

Generated plain static sites must work when the user directly opens index.html, when served over local HTTP, and when deployed to common static hosts.

Default rules:

• Use page-relative paths for all site-local links and assets.
• From root pages, link CSS/JS/images as assets/style.css, assets/script.js, assets/images/avatar.png, and pages as about.html or posts/example.html.
• From nested pages such as posts/example.html, link shared assets as ../assets/style.css and root pages as ../blog.html or ../index.html.
• Do not use root-absolute site-local paths such as /assets/style.css, /assets/script.js, /posts/example.html, /data/posts.json, /images/foo.png, or / unless the user explicitly accepts server-root-only behavior.
• Apply the same rule to CSS url(...), favicons, Open Graph images, cover images, fonts, KaTeX/math vendor assets, RSS/sitemap links, and JavaScript-generated URLs.
• When moving or adding a page, recalculate paths based on that page's folder depth instead of copying links from a root page.

Avoid server-only assumptions:

• Do not rely on fetch("data/posts.json") or other local file fetches for core navigation, post lists, or homepage content if direct-open preview is part of the promise.
• If repeated data is useful, either render essential content directly in HTML or store data in a local JavaScript object loaded with a relative <script src="assets/script.js">.
• Optional enhancements may use data files only when the page still reads and navigates correctly without that fetch.

Style Rules

Let the selected theme guide the visual language, but keep the site readable and maintainable.

• Put site-wide styling in assets/style.css.
• Use CSS custom properties for colors, spacing, borders, and type choices.
• Use semantic HTML where possible: header, nav, main, article, section, footer.
• Use responsive layout rules so pages work on mobile and desktop.
• Make article pages calmer than the home page if the theme is visually intense.
• Prefer system fonts unless the user asks for a specific font or the theme strongly needs one.
• Do not rely on remote assets unless the user provides them or they are clearly acceptable.
• Do not let decorative effects block reading, navigation, or accessibility.

Interaction Rules

Use vanilla JavaScript only when it adds clear value.

Good uses:

• Mobile navigation toggle.
• Theme toggle.
• Lightweight tag or post filtering.
• Small progressive effects that do not affect core reading.

Avoid:

• Heavy animation frameworks.
• Canvas-heavy decoration unless the user explicitly asks.
• Effects that require a dev server or package install.
• Continuous flicker, aggressive glitching, or scroll effects that hurt reading.

Respect prefers-reduced-motion for animated themes.

Static Simplification Rule

When a loose reference has complex or framework-dependent features, translate them into simpler static equivalents:

• 3D globe -> topic map, status panel, project constellation, or static visual block.
• Animated bento grid -> responsive CSS grid with subtle hover states.
• Terminal simulator -> themed navigation and log-style content, not a fake command line unless useful.
• Knowledge graph -> tags, related posts, topic index, or manually curated links.
• Dynamic search -> simple filter input, static tag pages, or no search for the first version.
• CMS-driven posts -> posts/*.html plus data/posts.json.

Prefer a clean static version that captures the user's desired feel over an overbuilt copy of the reference.

Existing Site Rule

When modifying an existing site:

• Inspect the current file structure before editing.
• Preserve user content and unrelated files.
• Keep changes scoped to the requested pages and assets.
• Reuse existing visual conventions when they already work.
• Avoid replacing the entire site unless the user asks for a full redesign.
• If the site already has style.css or script.js, extend them carefully instead of creating conflicting duplicates.

Content Rule

For small amounts of content, write static HTML directly.

For repeated content such as posts or projects, use either:

• Static repeated HTML when the list is short.
• A local JavaScript data object plus vanilla JavaScript rendering when it improves maintainability.
• A small JSON file only when the site is allowed to require local HTTP/static hosting for that feature, and the core page still works without it.

Do not invent detailed personal facts. Use placeholders clearly when user data is missing.

Keep placeholders easy to find and replace. Prefer storing repeated content in a clearly named place such as data/*.json, a documented data block in assets/script.js, or a repeated HTML section with stable class names.

Mark placeholder-only text, demo posts, sample projects, and mock links clearly in the files or EDITING.md so the user or a future model can replace them before publishing.

Editing Guide Rule

When creating a new site or materially redesigning an existing one, include EDITING.md in the output folder.

EDITING.md is primarily for a future model or agent that will modify the generated site later. Keep it concise but concrete. Explain:

• Folder hierarchy and what each file/folder is for.
• File formats used by the site: HTML, CSS, JS, JSON/data blocks, and images.
• Page map: which generated file is home, about/profile, blog/list, article/detail, projects, notes, links, or other page types.
• Shared layout regions: header, navigation, mobile nav, main content, footer, sidebars, overlays, or theme controls.
• Where each major homepage region lives in index.html, using nearby section/class names.
• Where each subpage template lives and how internal links connect to it.
• Where repeated content is stored and its expected object/markup format.
• How to change site title, tagline, avatar/logo, navigation, featured posts, project lists, link lists, images, colors, and theme variables.
• Which content is placeholder-only and should be replaced before publishing.

Encoding Integrity Rule

Generated source files must be valid UTF-8 and human-readable in source form, not only correct-looking in browser screenshots.

For pages or editing guides containing Chinese, Japanese, Korean, accented Latin text, or other non-ASCII content:

• Include <meta charset="utf-8"> in HTML files.
• Write files as UTF-8.
• Verify source readability with a UTF-8-aware reader before final delivery.
• Check generated HTML, CSS comments, JavaScript string data, JSON/data blocks, and EDITING.md.
• Do not leave mojibake, replacement characters, or text that is only readable after accidental browser encoding recovery.

If the shell or terminal displays mojibake but the browser looks correct, confirm with a UTF-8-aware file read before deciding the file is broken. If the file content itself contains mojibake, rewrite the affected strings from clean source text rather than layering another encoding conversion on top.

Validation

Before finishing, check as much of this as practical:

• Required files exist.
• index.html can be opened directly for manual preview.
• Navigation links point to existing relative paths.
• CSS and JS paths are relative and valid.
• Nested pages use correct ../ paths for shared assets and root-level pages.
• No accidental root-absolute site-local paths such as /assets/..., /posts/..., /data/..., or /images/... remain.
• Images and local assets resolve.
• Pages are readable on desktop and mobile widths.
• Browser console has no obvious JavaScript errors when a preview is available.
• No build command is required.
• For multi-page sites, click through generated internal pages and verify they render with the shared shell.
• Validate at least one browser pass or screenshot for every generated page type, such as home, about/profile, blog/list/archive, article/detail, projects, notes, links, or special interactive pages.
• Verify generated source files are UTF-8-readable and free of mojibake in the source, especially HTML files, JavaScript data strings, JSON/data files, and EDITING.md.

Automated validation, browser screenshots, interaction tests, and console checks should use a local static HTTP server such as:

python -m http.server 8000

Then open:

http://127.0.0.1:8000/

When an interactive browser tool is actually exposed in the current turn's callable tool list, use it as the first-choice way to open the local URL, inspect desktop/mobile layouts, click through page types, and check interactions. 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 in the current turn, do not pretend the browser pass happened. If the build quality depends on it, ask the user to enable or invoke the browser tool using their client's routing method; for Codex, that may mean sending a request that explicitly mentions @browser. If the user does not re-route or the client has no such tool, fall back to Playwright, screenshots, static audits, or shell checks and state the limitation. Screenshots may be captured as evidence after the interactive browser pass or as fallback evidence when no browser tool is callable.

Do not require a framework dev server.

Also perform a direct-open compatibility check when practical: open the generated index.html directly, or use source/static audit to confirm that direct opening will not lose CSS, JavaScript, images, or navigation due to root-absolute paths or file-fetch-only content.

For a dedicated final QA pass before handoff or publishing, use review-static-site on the generated static folder.

What To Tell The User

Keep the final response concise and practical.

Tell the user:

• What files were created or changed.
• How to open the site locally.
• Any important design translation decisions.
• What remains as the next natural step, such as content migration or publishing.

Do not over-explain internal implementation steps.