Communitygithub.com

IncomeStreamSurfer/astro-builder-skill

使用 Astro 搭配 Tailwind CSS、內容集合與可選的 Turso 資料庫,建立完整、SEO 最佳化的網站。每當使用者想要建立網站、打造能在 Google 排名靠前的站點、啟動 Astro 專案、製作登陸頁面、建立商業網站、創建部落格或任何 SEO 相關的網路專案時,請使用此技能。即使使用者只說「幫我建立一個網站」或「我需要一個商業網站」,此技能也能處理。

astro-builder-skill 是什麼?

這個技能能夠建立完整的、可直接部署的 Astro 網站,並針對 Google 搜尋排名進行最佳化。每個網站都包含適當的 meta 標籤、結構化資料、語意化 HTML、最佳化圖片、Sitemap,以及經過研究、非佔位符的真實內容。技能結合了 Astro 的靜態優先架構、React 的互動式元件(透過 Astro Islands)、Tailwind CSS 的全客製化樣式,以及可選的 Turso/Drizzle 邊緣資料庫來處理動態資料。工作流程分為五個階段:探索與研究、專案設定、建立每個頁面(含設計與 SEO)、內容集合與資料庫設定、以及部署準備。它特別強調高品質的設計,要求遵循 `taste-skill.md` 中的規則,避免產生千篇一律的 AI 輸出,並在建立前進行深入的利基研究,以確保內容策略與 SEO 成效。此技能支援 Vercel 與 Netlify 部署,並在 Astro v5 中正確處理靜態與伺服器渲染路由。

相容平台✓Claude Code~Codex CLI~Cursor✓Gemini CLI
npx skills add https://github.com/IncomeStreamSurfer/astro-builder-skill/tree/HEAD/skill

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

Astro SEO 網站建置工具

您可以建立完整、可直接部署的 Astro 網站,這些網站專為在 Google 上獲得排名而設計。每個網站都配有適當的 meta 標籤、結構化資料、語意化 HTML、最佳化圖片、Sitemap,以及經過真實研究、非佔位符的內容。

您產生的每個前端都必須是優質且非通用的。在撰寫任何 UI 程式碼之前,請先閱讀 references/taste-skill.md — 其中包含防止產生通用「AI 垃圾」輸出的設計規則。

技術棧

  • Astro — 靜態優先框架,預設零 JavaScript,非常適合 SEO
  • React — 透過 Astro Islands 實現的互動式元件(表單、導航、動畫)
  • Tailwind CSS — 所有樣式。不使用 shadcn 預設值 — 根據 taste-skill 規則自訂所有內容
  • Astro Content Collections — 適用於部落格文章、服務、推薦的型別安全 Markdown/MDX 內容
  • Turso + Drizzle — 邊緣 SQLite 資料庫(可選,用於表單/動態資料)

工作流程概覽

每個專案都遵循下列順序。請勿跳過任何步驟。

第一階段:探索與研究

  1. 詢問使用者關於他們的利基、業務和目標
  2. 詢問他們是否需要資料庫(用於聯絡表單、潛在客戶、預約等)
  3. 研究該利基 — 哪些內容排名靠前、哪些關鍵字重要、存在哪些內容缺口
  4. 提出網站結構提案,包含頁面清單、內容策略和關鍵字目標
  5. 在開始建置前取得使用者核准

第二階段:專案設定

  1. 建立 Astro 專案
  2. 安裝並設定整合(React、Tailwind、sitemap)
  3. 設定基礎佈局、SEO 元件和設計系統

第三階段:建立每個頁面

  1. 閱讀 references/taste-skill.md 以了解設計規則
  2. 如果使用者想要生成圖片,請閱讀 references/image-generation.md 並為每個頁面生成圖片
  3. 使用真實、經過研究的內容建立每個頁面
  4. 在每個頁面上進行完整的 SEO 設定 — meta 標籤、OG 標籤、結構化資料、語意化 HTML
  5. 連接互動式元件(表單、導航等)

第四階段:內容集合與資料庫

  1. 設定 Astro 內容集合,用於部落格文章、服務等
  2. 如果需要資料庫:設定 Turso、建立 schema、建置 API 路由
  3. 如果需要,為資料庫資料建立管理儀表板

第五階段:部署準備

  1. 產生 Sitemap、robots.txt
  2. 設定部署(Vercel/Netlify)
  3. 對每個頁面進行最終 SEO 稽核

第一階段:探索與研究

詢問使用者

在撰寫任何程式碼之前,了解專案:

  1. 您的利基/業務是什麼? — 「我在都柏林當水電工」或「我在網上賣手工蠟燭」
  2. 網站的主要目標是什麼? — 潛在客戶開發、電子商務、作品集、部落格、SaaS 登陸頁面
  3. 您想要多少頁面? — 小型(5-10 頁)或內容豐富型(15-30 頁以上,含部落格)
  4. 您需要資料庫嗎? — 用於儲存表單提交、預約、使用者資料等。如果需要的話,設定 Turso。
  5. 您想要生成的圖片嗎? — 「我可以使用 Gemini 為您的網站生成自訂圖庫圖片。如果您想要,請將您的 GEMINI_API_KEY 新增到 .env 檔案中。」
  6. 您有網域嗎? — Sitemap/標準 URL 需要。如果尚未購買,請使用佔位符。
  7. 有任何設計偏好嗎? — 顏色、風格、現有品牌標誌

研究利基

使用網路搜尋來找出:

  • 目前排名靠前的內容 — 針對目標關鍵字的前 5-10 個結果
  • 內容缺口 — 哪些問題未被很好地解答
  • 長尾關鍵字 — 競爭較少的特定片語
  • 如果是本地商家,本地 SEO 信號
  • 競爭對手的網站結構 — 他們有哪些頁面,缺少了什麼

提議網站結構

根據研究,建立具體的提案。以水電工為例:

建議頁面:
1. 首頁 — 「都柏林水電工 | 24/7 緊急水電服務」
2. 服務 — 所有服務概覽
3. 服務/緊急水電 — 目標登陸頁面
4. 服務/浴室翻新 — 目標登陸頁面
5. 服務/鍋爐維修 — 目標登陸頁面
6. 關於我們 — 信任信號、團隊、資格
7. 部落格 — 持續的 SEO 內容
8. 部落格/[slug] — 針對長尾關鍵字的個別文章
9. 聯絡我們 — 表單 + 地圖 + 電話
10. 服務地區 — 本地 SEO 頁面
11. 客戶推薦 — 社會證明

目標關鍵字:都柏林緊急水電工、我附近的水電工都柏林、都柏林鍋爐維修...
內容策略:每週發布針對「如何修理[常見問題]」查詢的部落格文章

在繼續之前,取得使用者的同意。


第二階段:專案設定

閱讀 references/astro-setup.md 以了解確切的命令和設定。

1. 建立專案

npm create astro@latest [專案名稱] -- --template minimal --install --no-git
cd [專案名稱]

2. 安裝整合

npx astro add react tailwind sitemap
npm install @astrojs/check typescript
npm install @fontsource/geist-sans @fontsource/geist-mono  # 根據 taste-skill 使用優質字型

3. 如果需要資料庫

閱讀 references/turso-setup.md 以了解完整的 Turso 設定。

npm install @libsql/client drizzle-orm

4. 專案結構

src/
├── components/
│   ├── SEOHead.astro
│   ├── Header.astro
│   ├── Footer.astro
│   ├── Navigation.tsx    # React island
│   └── ContactForm.tsx   # React island
├── content.config.ts     # 內容集合 schema(不在 content/ 中)
├── content/
│   ├── blog/
│   ├── services/
│   └── testimonials/
├── layouts/
│   └── BaseLayout.astro
├── lib/
│   ├── turso.ts          # 如果有資料庫
│   └── utils.ts
├── pages/
│   ├── index.astro
│   ├── about.astro
│   ├── contact.astro
│   ├── blog/
│   │   ├── index.astro
│   │   └── [...slug].astro
│   └── api/              # API 路由(如果有資料庫)
├── styles/
│   └── globals.css
└── middleware.ts
astro.config.mjs

第三階段:建立每個頁面 — 設計 + SEO

在撰寫任何頁面之前,請閱讀以下兩份文件:

  • references/seo-checklist.md — 每個頁面的 SEO 規則
  • references/taste-skill.md — 防止通用輸出的設計規則

SEOHead 元件

建立 src/components/SEOHead.astro — 放在每個頁面的 <head> 中。處理:

  • 標題標籤(每個頁面唯一,主要關鍵字,少於 60 個字元)
  • Meta 描述(唯一,含行動呼籲,少於 160 個字元)
  • 標準 URL
  • Open Graph 標籤
  • Twitter Card 標籤
  • JSON-LD 結構化資料

請參閱 references/seo-checklist.md 以了解確切的元件程式碼。

內容撰寫規則

  • 首先為人類書寫,其次才是搜尋引擎。
  • 每個頁面針對一個特定的關鍵字叢集。 主要關鍵字出現在標題、H1、第一段、meta 描述、URL 別名中。
  • 正確的標題層級。 一個 H1。章節使用 H2。子章節使用 H3。切勿跳過層級。
  • 內部連結。 每個頁面連結到 2-3 個以上的其他頁面。使用描述性錨文字。
  • 圖片替代文字。 每張圖片都獲得帶有自然關鍵字的描述性替代文字。
  • 內容長度。 服務頁面:800-1500 字。部落格文章:1500-3000 字。首頁:500-1000 字。
  • Schema 標記。 每個頁面都獲得適當的 JSON-LD。

設計規則(來自 taste-skill)

這些規則對於您建立的每個頁面都是不可協商的:

  • 排版: 使用 Geist、Satoshi、Outfit 或 Cabinet Grotesk。絕對不要使用 Inter。標題:text-4xl md:text-6xl tracking-tighter leading-none。
  • 顏色: 最多 1 個強調色,飽和度 < 80%。不要使用紫色/藍色 AI 漸層。中性基底(Zinc/Slate)。
  • 佈局: 當 DESIGN_VARIANCE > 4 時,不要使用置中英雄區。使用分割畫面、不對稱或左對齊佈局。
  • 卡片: 僅在層級傳達層次結構時使用。不要使用通用的三欄卡片佈局。
  • 間距: 使用 min-h-[100dvh] 而不是 h-screen。使用 Grid 而不是 flexbox 數學。使用 max-w-7xl mx-auto。
  • 狀態: 每個互動式元件都需要載入中、空白和錯誤狀態。
  • 無 AI 垃圾: 不要使用表情符號、不要用「張三」、不要用「某某公司」、不要使用「無縫」或「釋放」之類的填充詞。

用於互動性的 Astro Islands

  • 靜態內容(標題、文字、圖片) — .astro 元件,零 JavaScript
  • 互動式元素(表單、行動導航、捲動動畫) — React .tsx 搭配 client:visible 或 client:load
  • 動畫: 對於運動效果(MOTION_INTENSITY > 5),在獨立的 React island 中使用 Framer Motion。彈簧物理:type: "spring", stiffness: 100, damping: 20。

閱讀 references/tailwind-components.md 以了解元件模式(導航、表單、常見問題等)。


第四階段:內容集合與資料庫

Astro Content Collections

閱讀 references/content-collections.md 以了解完整設定。內容集合取代了 CMS — 內容以 Markdown 檔案形式存在於 src/content/ 中,並帶有型別安全的 schema。

重要: 在 src/content.config.ts 中定義 schema(而不是 src/content/config.ts — 舊路徑在 Astro v5+ 中會拋出 LegacyContentConfigError)。每個集合都必須有一個 loader(使用來自 astro/loaders 的 glob())。

在 src/content.config.ts 中定義 schema:

  • 部落格文章: title、description、pubDate、image、tags、author、draft
  • 服務: title、description、icon、order、featured
  • 推薦: name、role、quote、rating

在頁面中使用 getCollection() 和 getEntry() 查詢集合。

Turso 資料庫(如果需要的話)

閱讀 references/turso-setup.md 以了解完整設定。Turso 處理動態資料 — 表單提交、潛在客戶、預約、電子報註冊。

  1. 在 src/lib/turso.ts 中建立資料庫客戶端
  2. 使用 Drizzle ORM 定義 schema
  3. 在 src/pages/api/ 中建立用於表單處理的 API 路由
  4. 建立管理儀表板以檢視提交的資料

管理儀表板(如果使用資料庫)

使用 React islands 搭配 Tailwind 樣式的表格和卡片,在 /admin 建立。使用:

  • 用於基本驗證的中介軟體
  • 用於從 Turso 獲取資料的 API 路由
  • 乾淨、有品味的資料呈現(根據 taste-skill 規則 — 不要使用通用的卡片網格)

第五階段:部署準備

Sitemap 與 Robots.txt

@astrojs/sitemap 會自動產生 Sitemap。在 astro.config.mjs 中設定 site。

動態 robots.txt 位於 src/pages/robots.txt.ts:

import type { APIRoute } from 'astro';

const getRobotsTxt = (siteURL: string) => `User-agent: *
Allow: /
Disallow: /admin
Sitemap: ${siteURL}sitemap-index.xml`;

export const GET: APIRoute = ({ site }) => {
  return new Response(getRobotsTxt(site?.toString() || ''));
};

部署設定

閱讀 references/deployment.md 以了解 Vercel/Netlify 設定。

對於具有 API 路由或 Turso 的網站,請新增 adapter,但保留預設的靜態輸出。使用 export const prerender = false; 標記個別的伺服器路由:

import vercel from '@astrojs/vercel';

export default defineConfig({
  // 不要使用 output: 'hybrid' — 已在 Astro v5 中移除。
  // 預設為 'static'。伺服器渲染的路由會個別選擇退出。
  adapter: vercel(),
});

在每個 API 路由或伺服器渲染的頁面中:

// src/pages/api/contact.ts
export const prerender = false; // 此路由在伺服器上執行

export const POST: APIRoute = async ({ request }) => {
  // ...
};

最終 SEO 稽核

根據 references/seo-checklist.md 稽核每個頁面:

  • 每個頁面有唯一的標題、描述、標準 URL
  • 所有圖片都有替代文字
  • JSON-LD 驗證通過
  • 內部連結可正常運作
  • 行動裝置響應式(測試 taste-skill 行動覆蓋規則)
  • Sitemap 包含所有頁面
  • robots.txt 正確

重要注意事項

  • 不要使用 output: 'hybrid' — 它已在 Astro v5 中移除。請使用預設的 'static' 輸出。對於伺服器渲染的路由(API 端點、表單處理器),請在每個檔案中新增 export const prerender = false;。
  • React islands 需要 hydration 指令 — client:load 或 client:visible。
  • 內容集合是基於檔案的。 部落格文章和服務作為 .md 檔案存在於 src/content/ 中。Turso 僅用於動態資料(表單提交)。
  • 建置前先研究。 利基研究階段決定了 SEO 品質。
  • 真實內容取勝。 撰寫實質、有幫助的內容。不要使用 lorem ipsum。
  • 始終追求優質設計。 遵循 taste-skill 規則。每個頁面都應該看起來像價值萬元的代理商作品,而不是通用的 AI 輸出。
  • 圖片生成是可選的。 如果使用者提供了 GEMINI_API_KEY,則根據 references/image-generation.md 生成自訂圖片。如果沒有,則使用帶有適當替代文字的樣式化佔位符 div。

相關技能