agent-pages

name	agent-pages
description	把当前会话中的主题/资料生成为一个独立可浏览的 HTML 页面（结构清晰、化繁为简、由浅入深，强调图形/表格/动效与精致的 UI/UE），落地到你的画廊仓库并自动 commit + push + 在浏览器中打开。常规入口是 `/agent-pages <主题或说明>`。

Agent Pages Skill

把一个主题/资料生成为一份独立 HTML 页面（适合分享、阅读、复盘），并发布到你的站点仓库（一个独立 git 仓 AGENT_PAGES_PATH，部署到 GitHub Pages；首次由 setup.sh 从插件 templates/ 脚手架而来）。

执行链路：setup.sh（仅首次：脚手架站点 + 写配置）→ new-page.sh（同步 + 算路径）→ 评估素材 → 从零设计并写出 HTML → publish.sh（登记 data.json + commit + push + 打开）。脚本负责确定性的脏活，页面设计这件创造性的事由你来做。

When To Use This Skill

常规使用方式是输入以 /agent-pages 开头的命令：

• /agent-pages <主题> — 用该主题生成 HTML 页面（分类由你从固定分类集里推断）
• /agent-pages 分类=engineering <主题> — 显式指定分类（落到画廊的 engineering/ 下）
• /agent-pages 续写 <已有文件名> — 在已有页面上迭代/补充

其他自然语言（"帮我做个 H5"、"生成一个网页"等）可以先理解为普通请求，避免在用户未确认前直接开始写文件和发布。

路径与配置（插件提供，去硬编码）

agent-pages 以 Claude Code 插件分发。运行时有两个固定位置（在本 skill 文本里会被替换成真实绝对路径，直接用即可，不要把任何路径写死在脑子里）：

• 脚本在插件里：${CLAUDE_PLUGIN_ROOT}/scripts/（setup.sh / new-page.sh / publish.sh）
• 配置 + 状态在插件持久数据目录：${CLAUDE_PLUGIN_DATA}/config.env（跨插件更新存活），由 setup.sh 写入，含 AGENT_PAGES_PATH（站点 git 仓目录）/ AGENT_PAGES_REPO / AGENT_PAGES_BRANCH / AGENT_PAGES_SITE_BASE_URL / AGENT_PAGES_NAME

调用任何脚本前，先把配置路径显式传给它们（脚本据此 source 配置）：

export AGENT_PAGES_CONFIG_FILE="${CLAUDE_PLUGIN_DATA}/config.env"

• 站点根 = $AGENT_PAGES_PATH（一个独立 git 仓，部署到 GitHub Pages；页面写在这里、从这里 push）。
• 首页标题来自 data.json.site.title，默认 Agent <Pages/>；末尾形如 <Pages/> 的 token 会按 code/等宽风格渲染。
• data.schema.json 是 data.json 的结构契约；data.json.categories 是相对固定的分类选项，手动维护时不要偏离其中的字段。

目录结构：两级，按分类组织 —— <category>/<yyyyMMdd>-<slug>.html，例如 engineering/20260604-server-components.html。category 必须是 data.json.categories 里的某个 slug。

工作流

Step 0 — 首次使用先 setup（仅一次）

若 ${CLAUDE_PLUGIN_DATA}/config.env 不存在，说明站点还没初始化。先跑一次 setup（站点目录默认 $HOME/agent-pages，可先与用户确认目录/标题/repo）：

"${CLAUDE_PLUGIN_ROOT}/scripts/setup.sh" \
  --config "${CLAUDE_PLUGIN_DATA}/config.env" \
  --templates "${CLAUDE_PLUGIN_ROOT}/templates" \
  --path "$HOME/agent-pages"
  # 可选：--name "<标题>" --repo "<git-url>" --site "<public-url>"

它会从插件 templates/ 拷出站点脚手架（index.html/data.json/data.schema.json/CNAME.example）、git init、把配置+状态写进 config.env，并提示用户建 GitHub repo + 开 Pages。配置已存在则跳过本步，直接进 Step 1。

Step 1 — 准备（同步 + 解析路径）

解析命令意图：

1. 主题（topic）：命令未给则从会话上下文归纳，并向用户确认一次。
2. 分类（category）：显式 分类=xxx 优先；否则从 data.json.categories 的固定分类集里挑一个最贴合主题的 slug（如 engineering / product / design / research / learning / operations）；实在难归类才用 other，或向用户确认。
3. slug：从主题提炼，kebab-case、英文为主、简短可识别。

然后调用脚本（它会校验分类、同步仓库、用系统时钟取当天日期、解析并去重目标路径，输出 JSON）：

export AGENT_PAGES_CONFIG_FILE="${CLAUDE_PLUGIN_DATA}/config.env"
"${CLAUDE_PLUGIN_ROOT}/scripts/new-page.sh" --category "<category-slug>" --slug "<slug>"

从返回 JSON 读取 targetPath / relPath / dateHuman / category / isNewCategory。

• new-page.sh 会拒绝不在 data.json.categories 里的分类；选 slug 前先读一遍该列表。
• isNewCategory=true → 告知"将新建分类目录 "（首次往该分类发页面时正常）。
• 不要自己用 LLM 记忆里的日期，一切以脚本返回的 date/dateHuman 为准。

Step 2 — 评估内容充分性

判断上下文能否支撑一份"可读、可分享"的精华页面。素材稀薄（只有一个主题名）时先问用户：

• A — 用户补充资料（贴文档、链接、要点）
• B — 授权使用 WebSearch / WebFetch 联网调研
• C — 由你基于已有知识生成大纲版本，标注 TODO 待补

不要在素材稀薄时硬写，否则页面会沦为"占位符 H5"。

Step 3 — 设计与构建 HTML

⚠️ 每次都从零设计，不要参考历史页面

• 禁止 读取画廊里的 index.html 或任何 <category>/*.html 去"借鉴"主题/配色/版式/组件/动效/DOM 结构。
• 禁止 沿用上一次会话刚生成的风格——哪怕主题相近。
• 每次都基于当前主题独立、原创地推导设计语言：主题决定情绪，情绪决定配色/字体/版式/动效。
• 不小心瞄到旧页面，立刻清空印象，按本次主题重新设计。

设计增强 Skill（按检测结果依次使用）：

1. 若本会话已加载 /ui-ux-pro-max:ui-ux-pro-max，先调用它获取整体设计方向、配色、版式、组件、动效和字体建议。
2. 若可检测到 design-taste-frontend，再调用它做 anti-slop 设计读法、审美方向校准和前置质量检查。
3. 若可检测到 frontend-design，再调用它强化差异化视觉方向、细节完成度和避免通用 AI 页面。

没有检测到上述 Skill 时不要阻塞；仍然必须按下面的页面质量基线从主题出发独立设计。

页面质量基线（硬要求，全满足才算合格）：

1. 结构清晰：明确的 hero、章节分层、TOC（适用时）、footer。
   • 导航：长内容/多章节页面不要把所有锚点塞进顶部 Navbar（移动端必塌）。改用侧边栏目录（desktop 常驻 / mobile 抽屉），点击平滑滚动 + 当前章节高亮（IntersectionObserver）。短页面（≤3 节）可省侧栏。
2. 化繁为简，由浅入深：先给一句话结论，再展开"是什么 → 为什么 → 怎么用 → 边界"。
3. 图形化表达：能用图就别只用字 —— SVG/Canvas/CSS art、<table> 对比矩阵、时间线/流程图/雷达图；必要时 Mermaid 或 Chart.js（CDN）。
4. 动效：合理的 CSS transition / scroll-driven / IntersectionObserver 入场动画，动效服务阅读节奏，禁止满屏花哨。
5. UI/UE：
   • 字体：英文 Inter / IBM Plex / JetBrains Mono；中文 system stack 或 Noto Sans SC（按需 CDN）。
   • 配色：2-3 个语义色 token + neutral 灰阶，避免随手 #fff/#000。
   • 间距：一致的 spacing scale（4/8/16/24/32/48/64）。
   • 响应式（硬要求）：桌面优先，向下适配 1440 / 1024 / 768 / 375 四档不破版；用 clamp()/minmax()/auto-fit 平滑过渡；移动端触控目标 ≥ 44×44px；图表/表格窄屏给降级方案（横向滚动/卡片化）；至少在 375 宽跑一遍确认无横向滚动。
   • 暗色模式：优先 prefers-color-scheme；做不到也要保证日间模式精致。
6. 可独立运行：单文件 HTML（CSS/JS 内联或全走 CDN），双击即可打开，外链用稳定 CDN（jsDelivr/unpkg/Google Fonts）。
7. 无障碍最低线：语义化标签（<header> <main> <section> <article>）、对比度足够、图像有 alt。
8. 标题克制：HTML <title> 用短标题，建议中文 ≤ 18 个字、英文 ≤ 60 个字符；只写核心主题，不塞副标题、营销句、长解释或多段分隔符。

代码风格：注释/class/变量名用 English，正文文案用中文（除非主题本身是英文内容），不要中英混杂的标识符，不要无意义 placeholder。

用 Write 把页面写到 Step 1 返回的 targetPath。

Step 4 — 发布（登记 data.json + commit + push + 打开）

页面写好后调用 publish.sh，它会：把条目登记进画廊 data.json（包含分类选项、页面列表与标签，首页从该 JSON 渲染左侧分类/标签筛选和年份列表）、只 commit 页面 + index.html + data.json、push（失败自动 rebase 重试一次）、本地 open。

发布时分类与 Step 1 一致，并补充标签：

• --category 传 Step 1 用的同一个分类 slug（页面已落在该分类目录下；省略时 publish.sh 会从父目录名推断）。必须来自 data.json.categories，不确定时用 other，不要擅自造新分类。
• 根据主题提炼 1-4 个短标签，中文/英文均可，但同一画廊内尽量保持命名一致。
• 用逗号分隔传给 --tags，例如 "React,Server Components,架构"。

export AGENT_PAGES_CONFIG_FILE="${CLAUDE_PLUGIN_DATA}/config.env"
"${CLAUDE_PLUGIN_ROOT}/scripts/publish.sh" \
  --file "<relPath 或 targetPath>" \
  --title "<人读得懂的中文/英文标题>" \
  --date "<dateHuman, YYYY-MM-DD>" \
  --category "<category-slug>" \
  --tags "<tag1,tag2,tag3>"

• --title 用页面 <title> 的人读短标题，不要直接塞英文 slug，也不要超过标题长度约束。
• 从返回 JSON 读 commit / liveUrl / pushStatus / indexStatus。
• pushStatus=push-failed → 告知用户远端冲突，提示手动处理，不要反复硬推。

校验：发布后 Read 一遍画廊 data.json，确认新条目在 entries 顶部附近、href 相对路径可达、category 来自既有分类且与所在目录一致、tags 为主题标签；必要时再打开 index.html 确认分类和标签筛选能显示。

Step 5 — 报告

给用户简短反馈：

• 本地路径（file://... 形式）+ liveUrl（若配置了 AGENT_PAGES_SITE_BASE_URL）
• "已登记到 data.json，可在首页按标签筛选"
• commit SHA
• 页面亮点 1-2 条（用了什么图示/动效）
• 已知 TODO（如有）

续写模式

/agent-pages 续写 <已有文件名>：

1. 先取站点目录：. "${CLAUDE_PLUGIN_DATA}/config.env" 拿到 $AGENT_PAGES_PATH，在其下 find 该文件（模糊匹配 slug）。
2. 多结果 → 列给用户选。
3. Read 原文，用 Edit 增量修改；保持原页面设计语言（配色/字体/间距 token），不要风格漂移。
4. 重新发布时加 --no-index（续写通常不新增索引条目）：

   export AGENT_PAGES_CONFIG_FILE="${CLAUDE_PLUGIN_DATA}/config.env"
   "${CLAUDE_PLUGIN_ROOT}/scripts/publish.sh" --file "<file>" \
     --title "<title>" --date "<原日期>" --no-index --message "feat(<category>): update <slug> - <what changed>"
   

   publish.sh --no-index 不会修改 data.json。若续写改了页面标题或标签，保留 --no-index 完成页面更新后，再手动维护 data.json 中对应条目的 title / tags。

反模式 / 不要做的事

• ❌ 参考画廊里 index.html 或任何历史页面的主题/配色/字体/版式/动效——每次从主题出发独立设计。
• ❌ 用户没说 /agent-pages 就自动造页面。
• ❌ 素材稀薄就硬写，通篇 <p>TODO</p>。
• ❌ 自作主张联网调研（必须先问授权）。
• ❌ 套通用 "AI landing page" 模板（hero + 3 列 feature + CTA）。
• ❌ 用 <div> 堆整个页面（语义化标签是底线）。
• ❌ 引入大量本地依赖文件（必须单文件 + CDN）。
• ❌ 用 LLM 记忆里的"今天日期"（一律用 new-page.sh 返回的日期）。
• ❌ 把路径写死（脚本走 ${CLAUDE_PLUGIN_ROOT}/scripts/，配置/站点路径走 ${CLAUDE_PLUGIN_DATA}/config.env）。
• ❌ 绕过 publish.sh 手动 git add -A（会带进无关改动；脚本只 add 页面 + index + data.json）。

约束优先级（继承全局）

显式规则 > 正确性 > 业务边界 > 可维护性 > 性能 > 简洁。

本 skill 里"正确性"的含义是：页面内容不能虚构。涉及外部事实（版本号、API 签名、人物、数据）不确定就标 TODO 或停下问用户，宁可留白也不要发布错误信息。