Communitygithub.com

Gyschuaner/from-idea-to-personal-site

检查、验证、质量审核或对生成的静态网站(个人博客、作品集、数字花园等)进行完整性检查,确保在交付或发布前无断链、渲染错误、控制台报错、占位符残留及源文本误转等问题。

from-idea-to-personal-site 是什么?

该技能专注于对构建后的静态网站目录(如 `site/`、`dist/`、`out/` 或 `public/`)进行全面质量验证,确保其达到可发布或可交付的标准。它适用于 Claude Code、Cursor、Codex 等 AI 智能体,作为生成工作流后的质量门禁。技能的核心检查包括:验证所有源文件均为有效 UTF-8 编码且易于阅读;检测本地链接、脚本、样式表和资源是否可正确解析;默认要求使用页面相对路径而非根绝对路径(如 `/assets/style.css`),以支持直接通过 `index.html` 本地预览。此外,它会在真实浏览器上通过本地 HTTP 服务器检查桌面和移动端布局、控制台错误、交互功能(如导航、主题切换、搜索)是否正常。同时,技能会扫描残留的占位符文本(如“TODO”、“lorem ipsum”)、来自参考站点的来源特定字符串(如原作者名、域名)、以及隐私敏感文件(如 `.env`、私钥)。对于可自动修复的简单问题,技能会直接修复;对于重大问题,它会路由至 `make-personal-site` 等其他技能,并生成按严重程度排序的报告。

兼容平台~Claude Code✓Codex CLI~Cursor
npx skills add https://github.com/Gyschuaner/from-idea-to-personal-site/tree/HEAD/.agents/skills/review-static-site

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

Review Static Site

Goal

验证用户最终编辑、发布或视为完工前的静态网站输出。

此技能是生成的HTML/CSS/JS站点的质量门禁。它不会选择主题、重新创建参考网站、迁移内容或部署站点。它验证生成的文件夹是否像真实的静态站点一样工作。

核心检查项:

  • 源文件为有效的UTF-8编码且人类可读。
  • 本地链接、脚本、样式表、图片及其他资源可正确解析。
  • 站点内部链接和资产默认使用页面相对路径,而非根绝对路径如 /assets/style.css。
  • 输出可直接从 index.html 打开进行手动预览,除非用户明确接受了仅服务器行为。
  • 生成的页面覆盖预期的页面类型。
  • 站点在真实浏览器中通过本地HTTP渲染。
  • 桌面和移动端布局可用。
  • 报告或修复控制台错误、失效交互、残留占位符和来自源站点的特有文本。

Contract

输入:

  • 静态站点根目录,如 site/、dist/、out/、public/、docs/ 或仓库根目录。
  • 可选的预期页面范围、本地预览URL、EDITING.md、参考URL/截图及禁止的源站点特有字符串。

输出:

  • 按严重程度排序的发现列表,或当验证作为构建/修复任务一部分时的修复结果。
  • 静态审计结果、浏览器页面/视口检查情况及更改的文件列表(如有)。
  • 明确的通过/失败状态,以指示是否可发布或交付。

边界:

  • 不选择主题、重新创建网站、迁移内容、个性化身份或部署。
  • 验证过程中不重新设计网站,除非视觉问题阻碍可用性且用户要求修复。
  • 不批准根绝对路径,除非显式使用了 --allow-root-absolute 且已说明其局限性。

成功门禁:

  • 无阻塞性问题残留:主要导航断链、缺少必需页面类型、源编码不可读、本地资源失效、控制台崩溃、移动端不可用或意外根绝对路径问题。
  • 警告要么已修复、已记录,要么被用户接受。

若门禁未通过:

  • 在验证作为构建任务一部分时,修复直接的本地问题。
  • 根据失败的面将较大问题路由至 make-personal-site、copy-website-style、personalize-site、add-blog-posts 或 edit-site-part。
  • 重新运行确定性审计及相关浏览器检查。

Use With

在以下场景后使用此技能:

  • make-personal-site 创建或重新设计了原始静态个人站点。
  • copy-website-style 将目标站点的样式重现为静态文件。
  • 用户指向一个现有静态输出文件夹并询问其质量是否足够。
  • 用户在发布前要求检查、验证、QA、审查、审计或测试静态站点。

如果用户提供的是框架源码项目,尽可能验证已构建的静态输出文件夹。除非用户明确要求,否则不要在此引入框架构建工作流。

Inputs

使用任何可用的输入:

  • 静态站点根文件夹,如 site/、dist/、out/ 或 public/。
  • 本地预览URL,如果服务器已在运行。
  • 预期页面范围:仅首页、完整个人站点、博客、作品集、笔记、链接、样式重现等。
  • EDITING.md、页面地图或由其他技能产生的交接笔记。
  • 验证样式重现时的参考URL或截图。
  • 已知不得残留的字符串,如原作者名、域名、邮箱、分析ID或旧的占位符文本。

如果站点根目录不明确,检查邻近文件夹并选择包含 index.html 和静态资产的文件夹。

Workflow

  1. 确定静态站点根目录和预期页面范围。
  2. 读取 EDITING.md 或从HTML文件和导航链接推断页面地图。
  3. 运行确定性文件审计脚本。
  4. 启动或复用静态根目录的本地HTTP服务器。
  5. 在真实浏览器中以桌面和移动宽度验证站点。
  6. 为每个生成的页面类型打开至少一个代表性页面。
  7. 测试核心交互,如导航、主题切换、搜索/筛选、复制按钮、移动菜单和分页。
  8. 检查浏览器控制台错误和缺失的网络资源。
  9. 审计相对路径兼容性、占位符、UTF-8可读性和源特有残留文本。
  10. 当用户要求将验证作为构建一部分时,修复直接缺陷;否则先报告发现。

Deterministic File Audit

在浏览器验证前使用捆绑脚本:

python scripts/static_site_check.py <site-root>

对于样式重现或复制站点清理,传递禁止的源特有字符串:

python scripts/static_site_check.py <site-root> --forbid "original-author" --forbid "original-domain.com"

脚本检查:

  • HTML、CSS、JS、JSON、Markdown、SVG、XML和文本文件的UTF-8解码。
  • 可疑的乱码和替换字符。
  • HTML文件中缺失 <meta charset="utf-8">。
  • 损坏的本地 href、src、srcset、poster、action 和 data-src 引用。
  • 根绝对引用如 /assets/...、/posts/...、/data/... 或 /images/...,除非显式允许。
  • CSS url(...) 资产引用,包括缺失或根绝对的本地URL。
  • HTML、JavaScript和JSON数据中的常见根绝对站点本地字符串。
  • 链接脱离站点根目录。
  • 常见占位符字符串。
  • 通过 --forbid 提供的禁止字符串。
  • 隐私敏感的部署根文件,如 .env、私钥、凭据文件和本地服务账户工件。
  • 源文本中的秘密赋值、已知令牌模式、私钥块和本地绝对文件系统路径。
  • 不应发布的临时文件、日志、备份和操作系统工件。
  • HTML页面数量和推断的页面类型。
  • 是否存在 EDITING.md。

文件审计仍应对供应商文件验证UTF-8可读性,但不应将第三方压缩供应商包中的类占位符词视为站点占位符内容。

将脚本错误视为阻塞性问题,除非用户只想进行快速探索性审查。将警告视为需要手动检查的项目。

如果站点有意设计为在自定义域根下使用根相对路径,则运行脚本时加上 --allow-root-absolute,并说明直接 file:// 打开和GitHub项目子路径部署不保证。除非用户明确接受此折衷,否则不要对生成的纯静态个人站点使用此例外。

Path Compatibility

生成的纯静态站点应在三种常见上下文中工作:

  • 直接从文件系统打开 index.html 进行快速手动预览。
  • 通过本地HTTP提供文件夹服务,用于浏览器自动化和控制台/网络检查。
  • 部署到可能从域根或子路径提供站点服务的静态主机。

默认规则:

  • 使用页面相对路径引用站点内部链接和资产。
  • 从根页面使用 assets/style.css、posts/example.html 和 about.html。
  • 从嵌套页面使用 ../assets/style.css、../blog.html 及同层相对链接。
  • 默认不使用 /assets/style.css、/posts/example.html、/data/posts.json、/images/foo.png 或 / 进行内部导航。

还需检查JavaScript生成的链接、搜索结果、标签筛选器、复制按钮、动态卡片、RSS/站点地图引用、图片封面、CSS url(...) 值、favicon、字体及KaTeX/数学供应商资产。仅HTML属性相对是不够的,如果JavaScript后来插入了根绝对路径。

根绝对路径仅在用户明确希望仅服务器根部署(如自定义域根)且理解直接文件打开和GitHub项目Pages子路径可能失效时才可接受。

Browser Validation

在最终交付前使用真实浏览器。通过HTTP而非 file:// 提供本地文件服务:

python -m http.server 8000

然后打开:

http://127.0.0.1:8000/

对于本地HTTP目标,优先使用实际可用的交互式浏览器工具作为首选验证路径。“可用”意味着该工具在当前回合的可调用工具列表中公开,而不仅仅是技能、插件列表或系统描述中提及。在Codex中,这可能是Browser/应用内浏览器插件(当用户或客户端已将其路由到当前回合时);在其他智能体中,它可能是等效的可见浏览器、浏览器使用工具或devtools支持的浏览器。它应打开本地URL、检查桌面/移动视口、执行交互并检查可见的控制台/网络问题。

如果当前回合中没有可用的交互式浏览器工具,则不要假装浏览器验证已进行。如果验证依赖于它,请要求用户启用或调用浏览器工具(使用其客户端的路由方法);对于Codex,这可能意味着发送一个显式提到 @browser 的请求。如果用户未重新路由或客户端没有此类工具,则回退到Playwright、截图、静态审计或shell检查,并说明这是回退而非完整的交互式浏览器验证。

当交互式浏览器工具实际上可调用时,不要默认使用Playwright、仅无头截图脚本、shell打开的浏览器窗口或静态截图生成。截图是有用的证据,但不能替代交互式浏览器验证。仅在以下情况下使用Playwright作为回退:无交互式浏览器工具可调用、用户明确要求使用Playwright或明确需要可重复的脚本化回归测试。

仅在任务需要用户的Chrome配置文件、现有标签页、扩展、经过身份验证的远程页面或Chrome特定行为时使用Chrome自动化。不要依赖Chrome扩展自动化来处理 file:// 页面;应使用本地HTTP。

尽管自动化应使用本地HTTP,但生成的源仍应通过使用相对路径和避免仅服务器假设来保持直接打开兼容性。如果应用/浏览器允许快速 file:// 冒烟检查,则直接打开根 index.html 并验证CSS、图片、导航和代表性子页面未损坏。如果文件自动化不可用,则依赖确定性根绝对路径审计,并说明直接打开是否已手动或自动检查。

浏览器检查:

  • 桌面首屏:构图、间距、排版、可见导航及明显溢出。
  • 移动首屏:导航行为、文本换行、内容优先级及水平溢出。
  • 内部导航:所有主要导航链接能正常渲染。
  • 页面类型覆盖:每个生成页面类型至少一次浏览器检查或截图。
  • 交互覆盖:主题切换、菜单、筛选器、搜索、复制按钮、分页、手风琴、标签页、悬停/点击状态或其他可见控件。
  • 控制台状态:无明显JavaScript错误。
  • 网络状态:无缺失的本地CSS、JS、图片或字体资产。
  • 可访问性基础:交互控件的焦点可见性、可读对比度、有意义的页面标题及在可行时非空图片alt文本。

对于小型站点,点击每个生成的页面。对于较大站点,对每种页面类型及 EDITING.md 中提到的任何路由进行抽样。

Page-Type Coverage

从文件名、路由、可见导航和 EDITING.md 推断页面类型。

典型页面类型:

  • 首页。
  • 关于或简介。
  • 博客、存档、分类、标签、笔记或列表页。
  • 文章或详情页。
  • 项目、作品集、出版物或工作页面。
  • 链接、好友、资源、现在、使用、花园、搜索、主题/设置或其他特殊页面。

如果生成的站点声称是博客但没有文章/详情页,则报告此问题。如果导航指向不存在的子页面,则将其报告为阻塞性问题。

Encoding And Source Readability

仅浏览器截图是不够的。源文件必须对未来的模型和人类可读。

要求:

  • HTML文件包含 <meta charset="utf-8">。
  • 非ASCII文本存储为UTF-8。
  • HTML、CSS注释、JavaScript字符串、JSON/数据文件、SVG文本和 EDITING.md 在源码形式下可读。
  • 无乱码、替换字符或意外的浏览器编码恢复。

如果终端显示乱码但浏览器看起来正确,在进行认定为损坏前,使用UTF-8感知读取进行确认。如果文件内容本身包含乱码,则从干净文本重写受影响的字符串,而不是叠加另一层编码转换。

Placeholder And Residue Audit

检查生成的站点是否仍包含:

  • TODO、FIXME、lorem ipsum、placeholder、replace me、your name、example.com 或示例/演示文本。
  • 虚假邮箱、假社交链接、空按钮或失效行动号召。
  • 样式重现中来自原始站点的作者名、域名、文章标题、邮箱、分析ID、社交链接、好友链接或私密URL。

如果用户仍需要这些占位符作为有意编辑标记,不要盲目移除。清楚地报告它们,或仅在用户提供了真实内容时替换。

Privacy And Local Residue

在发布前将以下文件视为阻塞性问题:

  • .env、.npmrc、.pypirc、私钥文件、凭据JSON文件、服务账户文件或密码保险库/导出文件位于可部署根目录内。
  • HTML、CSS、JavaScript、JSON、Markdown、SVG或文本文件中类似秘密的赋值、访问令牌、私钥块或API密钥。
  • 生成源中的本地绝对文件系统路径,如Windows驱动器路径、file:///...、/Users/...、/home/... 或 /mnt/...。

将日志、备份、临时文件和操作系统元数据视为警告,除非它们暴露了私有内容。在打包或发布前从可部署输出中移除它们。

Fix Policy

当用户要求“检查”、“审查”或“告诉我哪里有问题”时,首先报告发现,避免大规模编辑。

当验证是构建任务的一部分且用户预期修复时(例如在 make-personal-site 或 copy-website-style 之后),修复可以从审计结果中确定的明确本地问题。

对于自动修复,安全范围限于:

  • 移除尾随空格和空行。
  • 从相对路径中移除前导的 /,但仅当它们引用了站点本地资产且站点不是服务器根配置时。
  • 修复缺失的 <meta charset="utf-8">。

避免:

  • 重写占位符内容,除非用户提供了替换文本。
  • 在未要求验证时更改布局、样式或结构。
  • 移动文件或重写整个页面。

如果问题跨越多个页面且来源明确,考虑用单个编辑修复所有实例,但仅在修复是确定性且安全的时候。

对于视觉问题、缺失页面或框架级缺陷,路由到适当的技能。

Individual skills in this repo

This repo contains 10 individual skills — each has its own dedicated page.

Gyschuaner/from-idea-to-personal-site

Use this skill to add, import, or migrate one or more blog posts, notes, essays, articles, Markdown files, Word documents, or rich-content writing folders into an existing static personal website or blog while preserving the site's current article style, content structure, navigation, indexes, archives, tags, assets, math, links, tables, code blocks, embeds, and homepage entry points. Use it for pasted posts, local Markdown files, Obsidian notes, .docx drafts, old static HTML posts, exported blog content, or small-to-medium batches of posts after a site has already been created.

Gyschuaner/from-idea-to-personal-site

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.

Gyschuaner/from-idea-to-personal-site

Use this skill when the user wants to recreate, copy, clone, remix, or closely match the look, layout, motion, or interaction feel of a specific website, URL, screenshot, or template using plain HTML, CSS, and JavaScript. Use it to inspect public source as research, rewrite original code, avoid direct reuse of protected assets, and validate the result in a browser.

Gyschuaner/from-idea-to-personal-site

Use this skill to make focused, small-scope edits to a generated static website, personal blog, portfolio, digital garden, or style recreation. Use it when the user wants to adjust one page section, component, visual detail, copy block, responsive issue, or lightweight interaction without rebuilding the whole site. Typical requests include changing a hero block, card layout, sidebar, footer, button, mobile menu, spacing, color, typography, animation intensity, or a small piece of page copy.

Gyschuaner/from-idea-to-personal-site

Use this skill after a personal website or blog style direction is roughly known and before building an original site. It searches for real websites, templates, portfolios, blogs, screenshots, or design examples that match the chosen direction, inspects them with browser or screenshot tools when available, and turns the findings into a practical design reference brief for make-personal-site. Use it for requests like finding references for a natural technical blog, cozy research homepage, brutalist portfolio, digital garden, minimal notes site, or any named visual direction that still needs concrete examples.

Gyschuaner/from-idea-to-personal-site

Run the complete idea-to-personal-website or blog workflow. Use when the user wants a one-click or end-to-end pipeline from a vague idea, reference URL, template, personal materials, style direction, or writing drafts to concrete style references, a validated static personal site, and optionally a live deployment on GitHub Pages, Cloudflare Pages, Netlify, or Vercel.

Gyschuaner/from-idea-to-personal-site

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.

Gyschuaner/from-idea-to-personal-site

Use this skill to turn a generated static personal website, blog, portfolio, digital garden, or style recreation into the user's own site by replacing placeholder identity, profile copy, links, projects, featured items, contact details, metadata, and demo page content. Use it after make-personal-site or copy-website-style, or when a user provides an existing static site folder and personal materials such as a bio, resume, README, GitHub profile, old homepage, Markdown notes, or social links.

Gyschuaner/from-idea-to-personal-site

Publish, deploy, or prepare a finished static personal website, blog, portfolio, or style recreation for hosting on GitHub Pages, Cloudflare Pages, Netlify, or Vercel. Use when the user asks to publish a static site, configure deployment settings, add GitHub Pages workflows, choose a static hosting platform, prepare a repo for Pages/Cloudflare/Netlify/Vercel, verify a deployed URL, or explain how to deploy a site folder such as site/, dist/, out/, public/, or docs/.

Gyschuaner/from-idea-to-personal-site

Use this skill when the user wants to find, compare, choose, or adapt a visual theme for a personal blog, personal homepage, portfolio, research homepage, digital garden, or static website. Use it to turn references from v0, Figma, GitHub themes, existing websites, screenshots, keywords, or natural-language taste preferences into natural, practical theme recommendations.

相关技能