| name | use-agent-pages |
| description | agent-pages 的引导纲要（bootstrap doctrine）。会话开始时自动注入，用以说明 /agent-pages 的入口、何时建议它、以及生成页面时的硬约束。在真正开始写页面 / 发布之前，先按本文挑入口；完整工作流见 agent-pages:agent-pages skill。 |
Using agent-pages
agent-pages 把当前会话中的主题/资料生成为一份独立可浏览的单文件 HTML 页面（结构清晰、化繁为简、由浅入深，重图形/表格/动效与精致 UI/UE），并发布到用户自己的站点仓库（一个独立 git 仓，部署到 GitHub Pages；首次由 setup.sh 从插件 templates/ 脚手架而来）。
本文档只负责入口判断——告诉你何时该用、何时只是建议、以及不可逾越的红线。具体的「准备 → 评估素材 → 从零设计 → 发布 → 校验」执行链路在 agent-pages:agent-pages skill 里，进入流程后以它为准。
入口（何时进入流程）
正常入口是用户输入以 /agent-pages 开头的命令：
| 命令 | 含义 |
|---|
/agent-pages <主题> | 用该主题生成页面（分类由助手从固定分类集里推断） |
/agent-pages 分类=<slug> <主题> | 显式指定画廊分类（页面落到 <slug>/ 目录下） |
/agent-pages 续写 <已有文件名> | 在已有页面上迭代/补充 |
收到上述命令，即调用 agent-pages:agent-pages skill 按其工作流执行。
何时建议（不要直接动手）
当用户的请求做成一份自包含 HTML 工件，会比一长段 Markdown 更清楚时，先用一两句话建议 /agent-pages <主题>，并询问是否采用——不要未经确认就开始写文件/发布。典型适合场景：
- 并排对比的探索 / 方案规划、带注解的代码评审
- 设计系统 / 组件变体、交互原型、图示与调研地图
- 幻灯片/报告式表达、事故/状态/PR 复盘、小型自定义评审/编辑 UI
不要为以下场景建议：快速问答、简短解释、常规小改、或用户明显只想要纯文本。
硬约束（红线）
- 不自动造页面：用户没用
/agent-pages 也没确认，就不要写文件、不要发布。
- 不虚构：涉及外部事实（版本号、API、人物、数据）不确定时标
TODO 或停下问，宁可留白也不发布错误信息；素材稀薄先问用户（补料 / 授权联网 / 出大纲版），不要硬写成占位符页面。
- 每次从零设计：禁止读画廊里
index.html 或任何历史页面去「借鉴」配色/版式/动效；主题决定设计语言。
- 按分类组织：页面落在
<category>/<yyyyMMdd>-<slug>.html；category 必须是 data.json.categories 里的 slug（没有「项目」概念了）。难归类才用 other，不要擅自造新分类。
- 日期以脚本为准：用
new-page.sh 返回的日期，不要用 LLM 记忆里的「今天」。
- 路径不硬编码：脚本走插件目录
${CLAUDE_PLUGIN_ROOT}/scripts/；配置/站点路径走插件持久数据 ${CLAUDE_PLUGIN_DATA}/config.env。配置不存在 → 站点尚未初始化，先跑 setup.sh（见下）。
- 发布只用 publish.sh：不要在站点里
git add -A；脚本只会 stage 页面 + index.html + data.json。
配置与脚本在哪
- agent-pages 以插件分发(marketplace 安装)。脚本在插件里
${CLAUDE_PLUGIN_ROOT}/scripts/(setup.sh / new-page.sh / publish.sh)。
- 配置 + 状态在插件持久数据目录
${CLAUDE_PLUGIN_DATA}/config.env(跨更新存活)：AGENT_PAGES_PATH(站点 git 仓目录) / AGENT_PAGES_REPO / AGENT_PAGES_BRANCH / AGENT_PAGES_SITE_BASE_URL / AGENT_PAGES_NAME。
- 首次使用：若
config.env 不存在,先跑一次 setup.sh——它从插件 templates/ 把站点脚手架拷到 AGENT_PAGES_PATH(默认 $HOME/agent-pages)、git init、写配置。站点是用户自己的独立 git 仓,部署到 GitHub Pages。
- 调脚本前
export AGENT_PAGES_CONFIG_FILE="${CLAUDE_PLUGIN_DATA}/config.env",脚本据此读配置。
- 本插件（agent-pages）分发能力 + 站点模板：
agent-pages:agent-pages 工作流 skill、use-agent-pages 本文、session-start hook、scripts/、以及 templates/。站点内容在用户自己的独立站点仓 $AGENT_PAGES_PATH，配置/状态在 ${CLAUDE_PLUGIN_DATA}/config.env——都不在插件目录内（插件目录是临时的）。
