用 AI 编程助手配合 AstroWind 构建网站：AGENTS.md 与 Skills 技能体系实战指南-平芜编程栈

前端
UI组件

【免费下载链接】astrowind

⭕️ AstroWind: A free template using Astro v7 and Tailwind CSS v4. Astro starter theme.

项目地址：https://gitcode.com/GitHub_Trending/as/astrowind

AstroWind 是一套基于 Astro v7 与 Tailwind CSS v4 的开源静态网站模板，它在仓库根部随附了AGENTS.md指令文件和.agents/skills/技能目录，让 Claude Code、Cursor、GitHub Copilot 等任何 AI 编程助手都能"读懂"项目的约定：技术栈、目录布局、命令规范、组件模式与验证流程。本文以该模板自带的指南文档为核心，结合仓库中真实存在的指令文件与技能文件，讲解如何用 AI 助手完成新增页面、新增博客、改品牌色、配置表单、部署上线等日常营销站点工作，并给出让 AI 产出保持可审查性的实操习惯。

AstroWind 为 AI 编程助手提供了什么

营销站点的多数工作并不难，只是冗长：一个新页面要和已有页面风格一致、一个区块要从某页挪到另一页、一篇博客要带上正确的 front matter、一个部署参数没人记得住。AI 编程助手恰好擅长这类工作——前提是它了解项目的约定。AstroWind 把约定放在两个地方，让同一个助手既能创建项目、也能改品牌、还能讲解模板原理，而不用靠猜。

AGENTS.md：项目约定的总入口

仓库根目录的 AGENTS.md 描述了技术栈、目录布局、常用命令、代码规则与验证清单。大多数编码 Agent 会自动拾取AGENTS.md（可查阅所用工具的文档）；仓库中的 CLAUDE.md 则只有一句话——"See AGENTS.md for all project documentation and AI agent instructions"，即单纯指向AGENTS.md，避免维护两份重复内容。

该文件实际包含以下关键信息，值得逐项了解：

部分	内容要点
Project Overview	基于Astro v7 + Tailwind CSS v4 + TypeScript 5.9 + MDX + Sharp的免费开源模板，产出完全静态、面向性能/SEO/无障碍优化的站点
Skills	在执行项目专属任务（禁用博客、Open Graph 图片、base path、CMS、部署、Header 定制等）前，先检查`.agents/skills/`中是否有现成技能并遵循它
Quick Reference	`npm run dev`（localhost:4321）、`npm run build`（产物输出到`./dist/`）、`npm run preview`、`npm run check`（astro check + ESLint + Prettier）、`npm run fix`；Node.js 要求 ≥ 22.22.3
Architecture	目录结构、`~/`路径别名、`astrowind:config`虚拟模块配置系统（`src/config.yaml`导出`SITE`、`I18N`、`METADATA`、`APP_BLOG`、`UI`、`ANALYTICS`）
Tailwind CSS v4	CSS-first 配置（`src/assets/styles/tailwind.css`）、class 式暗色模式、`twMerge`类合并
Content Collections	`src/content.config.ts`中基于 Content Layer API 的`glob()`加载器，博客文件位于`src/data/post/`
Verification Checklist	改动后必须验证：`npm run build`成功、`npm run check`通过、浏览器目检（首页/博客/暗色模式/移动端菜单）、结构化数据与实际站点一致

值得注意的是，AGENTS.md还记录了模板的两个设计决策：@astrojs/partytown是默认关闭的可选第三方脚本方案（astro.config.ts中hasExternalScripts = false，保证基础模板不携带外部脚本）；Astro 原生 CSP 在本版本中有意未开启，因为它与默认开启的<ClientRouter />视图过渡不兼容。

.agents/skills/：把重复任务写成菜谱

.agents/skills/目录下每个 Markdown 文件对应一类高频任务，按"配方"形式编写：改哪些文件、按什么顺序、要验证什么。AGENTS.md会指示助手在动手做任何项目专属改动之前，先查找匹配的技能文件，因此你甚至不需要在提示词里点名它们。你也可以直接阅读这些文件——它们很短，本身就是一份不错的模板手册。

仓库中实际存在 16 个技能文件（.agents/skills/目录），文档重点列出的几个如下：

技能文件	用途
add-page.md	用 widget 组合新页面并带上元数据
add-blog-post.md	写一篇带正确 front matter 与图片处理的博客
styling.md	颜色、字体与 Tailwind token
configure-contact-form.md	把联系表单接到后端或表单服务
deploy-cloudflare.md	部署到 Cloudflare Pages

此外还有add-component.md、add-structured-data.md、content-at-build-time.md、customize-header.md、deploy-with-base-path.md、disable-blog.md、set-open-graph-image.md、setup-decap-cms.md、use-shadcn-tokens.md、use-widgets.md、write-landing-page.md，覆盖从 widget 目录到结构化数据、从 base path 部署到 shadcn token 的各类场景。

与 AI 编程助手配合良好的提示词

以下指令属于 Claude Code、Cursor 或 GitHub Copilot 这类助手能够端到端完成的任务类型，完成后用npm run check和一次构建来确认即可：

"Add a/careerspage with a hero, a list of open positions as feature cards and a call to action, using the same header as the rest of the site."
"Turn the pricing section of the sales landing page into a comparison table with three plans."
"Write a blog post from these notes, with a cover image fromsrc/assets/images/, the categoryProductand the tagsrelease,changelog."
"Change the brand colors to#0f766eand#f59e0b, in light and dark mode, and show me the pages where the contrast may be a problem."
"Disable the blog and remove it from the menus and the footer."
"Deploy this site under/handbookon GitHub Pages."
"Add FAQ structured data to the pricing page."
"Replace the testimonials on the home page with a logo strip and a single quote."

这些请求之所以能稳定落地，是因为每个请求都映射到一到两个技能文件加上 widget 目录，而不是让助手自由发挥引入新风格。以其中三个为例说明底层机制：

"加一个/careers页面"—— add-page.md 给出标准模板：在src/pages/新建.astro文件，用PageLayout（自带 Header + Footer）或裸Layout，用src/components/widgets/下的Hero、Features等组件组合页面，widget 统一接收id、title、subtitle、tagline等标准化 props，图标使用tabler:icon-name格式（来自@iconify-json/tabler）。页面按文件名自动路由。

"把价格区块改成三档对比表"—— use-widgets.md 的目录中，Comparisonwidget 专门做功能矩阵或"我们 vs 他们"表格，核心 props 为columns[{ title, subtitle?, highlight?, callToAction? }]、rows[{ label, description?, values, group? }]，mode支持features/versus；而Pricingwidget 支持hasRibbon、highlight、billingLabels等订阅卡细节。把整个价格区块换成Comparison组件即可。

"改品牌色为#0f766e和#f59e0b"—— styling.md 说明所有主题 token 定义在src/assets/styles/tailwind.css的@theme块中，并映射到src/components/CustomStyles.astro的 CSS 变量（--aw-color-primary、--aw-color-secondary、--aw-color-accent、--aw-color-text-heading等，需同时维护:root与.dark两套）。该技能还专门提醒：演示页把高亮词包在text-accent dark:text-white里，是因为默认紫色 accent 在暗色背景上对比度不足；改色时要留意这类对比度问题，正好对应提示词中"show me the pages where the contrast may be a problem"的要求。

让 AI 生成的代码保持可审查的习惯

文档给出了五条实操习惯，配合源码可以落到具体动作上：

指向一个演示页面。"像产品落地页那样，但是给服务的"——给助手一个可复制的具体结构。这正是模板被设计出来的用法：widget 组件（use-widgets.md 中的目录与 demo 对照）保证了新页面天然贴合站点既有风格。

要求跑检查。npm run check依次执行astro check、ESLint 和 Prettier；npm run build能捕获坏掉的 import 和非法 front matter。让助手在汇报前把两个都跑一遍，失败时展示输出给你看。这一要求有明确的命令依据：AGENTS.md的 Quick Reference 表和 Verification Checklist 都列出了这些命令。

审查 diff 而不是摘要。助手喜欢慷慨地写总结，但多数任务的 diff 很短，那才是该读的东西。审查时重点找：硬编码颜色（应该是 token，即CustomStyles.astro中的--aw-color-*变量）、指向#的链接、以及被留在页面里的演示内容。

内容决策留给自己。助手擅长结构与机制；标题、报价、证据是你的工作——真实的 testimonials、真实的数字、真实的截图。

一个任务一个会话。先一个页面，再一篇博客，再一次部署。长会话会跑偏，短会话能收尾。

添加你自己的 AGENTS.md 规则

这些文件就是普通 Markdown，且属于你的仓库，可以随意适配：

为团队反复做的事新增技能：怎么加案例研究、怎么发 release note、怎么更新价格表。沿用现有文件的结构：步骤（steps）、涉及文件（files involved）、验证（verification）。参考 add-blog-post.md 的写法：步骤 → front matter 字段表 → URL 规则 → 自动获得的能力（title/meta/Open Graph/JSON-LD/RSS）→ 注意事项。
往AGENTS.md加你自己的规则：命名规范、语气语调、哪些页面禁止改动、分支与 review 流程。
结构性变更要同步更新技能：当你加了新的内容集合、换了部署目标，要在同一个 pull request 里更新受影响的技能文件。一份过时的菜谱比没有更糟。

这里有一条值得注意的更新原则：由于CLAUDE.md只是指向AGENTS.md的指针（见 CLAUDE.md），你只需维护AGENTS.md一份真相源，所有 Claude Code 用户会自动获得最新约定。

不用 AI 助手也能用上这套体系

本文一切内容都不是必需的。技能文件同时也是模板最短的文档：读一遍 widget 目录和落地页配方（use-widgets.md 与 write-landing-page.md）大约花十分钟，就覆盖了入门指南和品牌定制指南长篇讲解的大部分内容；模板深度解析则适合想彻底弄清内部机制的人。这套"人可读、Agent 可执行"的双重设计，是 AstroWind 让 AI 协作保持高质量的关键——约定的载体本身，就是最好的文档。