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