specsfy-specialist-astro

Name: specsfy-specialist-astro
Author: promovaweb

github.com/promovaweb开发87161 次安装1 周前更新

关于 specsfy-specialist-astro

面向 Astro 项目开发者的专业技能，适用于页面、布局、内容或端点开发与维护。重点包括服务端优先渲染、按需水合、明确校验，以及在目标运行环境中测试。

复制下面的命令，在终端中运行。

$npx skills add https://github.com/promovaweb/specsfy --skill specsfy-specialist-astro

安装后在 Claude Code 中输入/specsfy-specialist-astro确认已加载。

附带文件agents/openai.yamlreferences/standards.md

当项目包含 astro.config 或 astro 依赖，且任务涉及页面、布局、.astro 组件、内容集合、端点或交互岛时使用。
也用于决定输出模式（静态/服务器）、选择合适的 client:* 指令，或诊断发送到客户端的 JS 是否大于预期。
如果问题涉及在交互岛中水合的 React/Vue/Svelte 组件的内部逻辑，则不要使用；应使用 $specsfy-specialist-react（或同类专家）处理组件本身的行为，同时由本专家负责决定何时以及如何水合组件。
对于网站的地标、标题和键盘导航问题，与 $specsfy-specialist-web-accessibility 配合使用；当症状是 Core Web Vitals 未达到 SLO 时，与 $specsfy-specialist-performance-engineering 配合使用。

提出建议前，先了解 Astro 版本、输出模式（static/server）、适配器、已启用的集成和内容来源（Markdown、MDX、远程 CMS）。
将每个变更的路由分类为静态（构建时已知）、按需（每次请求时服务器渲染）或端点（具有明确 GET/POST 的 HTTP 契约）。
默认保持 HTML 静态且不包含 JS；仅为需要交互的组件添加水合，并针对具体情况使用限制最严格的 client:* 指令。
使用内容集合和明确的 schema（Zod）对内容建模；将无效 frontmatter 视为构建错误，而非可容忍的数据。
按路由定义缓存、headers、资源和图片（astro:assets），并确保与所选输出模式一致。
测试 astro check、生产构建、schema 中的无效内容，以及每个交互岛独立水合后的行为。
在实际目标适配器上测量发送到客户端的 JS 负载和 Core Web Vitals，而不只是在开发服务器上测量。

使用满足交互需求的最小水合指令：页面首屏以下的内容使用 client:visible，低优先级内容使用 client:idle，只有交互必须立即就绪时才使用 client:load；切勿默认对所有内容使用 client:load。
不要向交互岛传递超过其渲染所需的数据——交互岛的每个 prop 都会作为 JSON 序列化到 HTML 中，并计入负载。
保持布局和 .astro 组件以服务器为先；.astro 组件永远不需要 client:* 指令，因为它不会水合——只有嵌入的框架组件（React/Vue/Svelte）会水合。
在边界处使用明确的 schema 校验所有内容（frontmatter、路由参数、端点 body）；将重复 slug 或路由冲突视为构建错误，而非静默处理。
只有在按请求个性化、会话或数据新鲜度确有必要时，才选择 server 输出（SSR）；否则，static 更快、更便宜，也更容易缓存。
确保 canonical、sitemap 和结构化数据（JSON-LD）与每个页面的最终 URL 保持一致，包括动态生成的内容。
不要假设 edge 适配器支持完整的 Node API（fs、process）；使用仅限服务器端的依赖前，先确认目标适配器的运行时。

在页面的每个孤岛上都“以防万一”应用 client:load——会增加发送的 JS，即使 client:visible 或 client:idle 已经足够。
将完整的数据对象（例如整个数据库记录）作为属性传给只显示两个字段的孤岛——每个额外字节都会被序列化并发送到浏览器。
Content collection 没有 Zod schema，却“相信” frontmatter 是正确的——缺失字段只会在生产环境中作为 bug 暴露，而不会在构建时发现。
整个网站都使用 server 输出，而实际上只有一个路由（例如经过身份验证的 dashboard）需要 SSR——不需要 SSR 的页面也会失去静态缓存。
混淆此 skill 与已水合框架的职责：React 孤岛中的状态 bug 属于 $specsfy-specialist-react，而不是孤岛配置问题。

在认为更改已就绪之前，运行 astro check、项目测试套件和完整的生产构建。
在禁用 JavaScript 的情况下检查服务器返回的 HTML（页面仍应可导航且可读），然后分别验证每个孤岛的水合。
检查内部链接、错误页面（404/500）、优化后的图片，以及网站公开提供的 RSS、sitemap 和元数据。
在 adapter 的实际 runtime 中进行预览（不能只用 astro dev），测量更改前后每个路由的 JS 负载和 Core Web Vitals。
未检查生成的 HTML 前，不得声称页面是“静态”或“零 JS”；没有证据支持的绝对化表述是禁止的。