Communitygithub.com

Astro Islands Architect

コンテンツ重視のサイトをAstroで構築する際、SSG/SSR/ハイブリッドの選択、クライアントディレクティブ(idle/visible/load/media)の選定、型安全なスキーマによるコンテンツコレクションの構築、同一プロジェクト内でのReact/Vue/Solid/Svelteコンポーネントの統合、Next.jsからの移行などを支援します。

Astro Islands Architect とは?

このスキルは、Astroを使用してマーケティングサイト、ブログ、ドキュメントポータルなどのコンテンツ重視のサイトを構築する際のアーキテクチャパターンを提供します。Astroの「デフォルトでHTMLを配信し、必要な部分だけJavaScriptでハイドレートする」というアイランドアーキテクチャを最大限に活用するための具体的な実装方法を学べます。主な機能として、5種類のクライアントディレクティブ(client:load、client:idle、client:visible、client:media、client:only)の適切な使い分け、Zodスキーマによる型安全なコンテンツコレクションの定義、複数フレームワーク(React、Vue、Svelte)の同時利用、サーバーアイランド(Astro 4+)、画像最適化、ビュートランジション、MDXレイアウトなどをカバーしています。また、client:loadの乱用やクライアントコンポーネントでのデータフェッチなど、よくあるアンチパターンとその修正方法も提示しており、品質ゲートチェックリストも含まれています。このスキルは、Claude CodeやCursorなどのAIエージェントで利用でき、SPAには適さないフレームワークの選択に関する判断基準も示しています。

対応~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/curiositech/windags-skills/tree/HEAD/skills/astro-islands-architect

お気に入りのAIに質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

ドキュメント

Astro Islands Architect は何をしますか?

Astro は「デフォルトで HTML を配信し、JS が必要な部分だけをハイドレートする」フレームワークです。マーケティング、ドキュメント、コンテンツ重視のサイトでは、React/Next.js よりも劇的にバンドルサイズを削減できます。肝心なのは、どのコンポーネントを静的(static)にし、どのコンポーネントをアイランド(island)にするかです。

使用するケース

  • マーケティングサイト、ブログ、ドキュメントポータル — コンテンツが製品そのもの。
  • クライアント JS が過剰な Next.js マーケティングサイトからの移行。
  • マルチフレームワーク — React コンポーネントライブラリを Vue や Svelte コンポーネントと併用。
  • MDX と型安全なフロントマターによるヘビーなコンテンツ作成。
  • SPA を使わずにページ間のビュートランジションを実現。

中核機能

ページ構造

---
// src/pages/blog/[slug].astro — フロントマターはビルド/SSR 時に実行されます
import { getCollection, getEntry } from 'astro:content';
import Layout from '../../layouts/Default.astro';
import Newsletter from '../../components/Newsletter.tsx';

export async function getStaticPaths() {
  const posts = await getCollection('blog');
  return posts.map((p) => ({ params: { slug: p.slug }, props: { post: p } }));
}

const { post } = Astro.props;
const { Content } = await post.render();
---
<Layout title={post.data.title}>
  <h1>{post.data.title}</h1>
  <article><Content /></article>

  {/* アイランド — このコンポーネントだけが JS を配信します */}
  <Newsletter client:visible />
</Layout>

--- で囲まれた部分はサーバーコードです。<...> 内では、デフォルトは静的 HTML です。client:* ディレクティブを持つコンポーネントがアイランドになります。

クライアントディレクティブ — 適切なものを選択する

ディレクティブハイドレートのタイミング使用例
client:loadページ読み込み時ファーストビューのインタラクティブ要素(カート、検索)。
client:idleブラウザがアイドル状態になった時重要でないインタラクティブ要素(チャットウィジェット)。
client:visibleビューポートにスクロールされた時ファーストビューより下のコンテンツ(ニュースレター登録、コメント)。
client:media="(min-width: 768px)"メディアクエリに一致した時デスクトップ専用ウィジェット。
client:only="react"SSR をスキップし、クライアントのみでレンダリングマウント時にブラウザ API が必要なコンポーネント。

client:idle は、ほとんどの重要でないアイランドの適切なデフォルトです。client:load は大きなハンマーのようなもので、控えめに使いましょう。

コンテンツコレクション

// src/content/config.ts
import { defineCollection, z } from 'astro:content';

const blog = defineCollection({
  type: 'content',                    // markdown/MDX ファイル
  schema: z.object({
    title: z.string().max(120),
    description: z.string().max(160),
    date: z.coerce.date(),
    tags: z.array(z.string()).default([]),
    draft: z.boolean().default(false),
    cover: z.object({ src: z.string(), alt: z.string() }).optional(),
  }),
});

export const collections = { blog };

これで getCollection('blog') は完全に型付けされます。フロントマターのミスは本番環境ではなくビルド時に検出されます。

const posts = (await getCollection('blog'))
  .filter((p) => !p.data.draft)
  .sort((a, b) => +b.data.date - +a.data.date);

マルチフレームワーク

npx astro add react vue svelte
---
import ReactSearch from '../components/Search.tsx';
import VueChart from '../components/Chart.vue';
import SvelteToggle from '../components/Toggle.svelte';
---
<ReactSearch client:idle />
<VueChart client:visible />
<SvelteToggle client:load />

各フレームワークのランタイムは個別にバンドルされ、そのフレームワークを使用するページでのみ読み込まれます。ほとんどが静的であるドキュメントサイトの場合、ほとんどのページに React JS をまったく配信しないということも可能です。

サーバーアイランド(Astro 4+)

<Layout>
  <Header />
  <PersonalizedRecommendations server:defer>
    <p slot="fallback">読み込み中...</p>
  </PersonalizedRecommendations>
  <Footer />
</Layout>

server:defer は、ページの残りの部分をすぐにレンダリングし、遅延コンポーネントの HTML を別のリクエストでストリーミング配信します。パーソナライズされたコンテンツなど、ページ全体を SSR にする必要がない場合に便利です。

画像最適化

---
import { Image } from 'astro:assets';
import cover from '../assets/cover.jpg';
---
<Image src={cover} alt="カバー写真" widths={[400, 800, 1200]} sizes="(max-width: 768px) 400px, 1200px" />

Astro は srcset を生成し、Sharp でリサイズを実行し、必要なものだけを配信します。画像は完全な最適化のために src/assets/ に配置してください。public/ は未処理のまま配信されます。

ビュートランジション

---
import { ViewTransitions } from 'astro:transitions';
---
<html>
  <head>
    <ViewTransitions />
  </head>
  ...
</html>
<a href="/about" transition:name="hero">About</a>

SPA なしでページ間のトランジションを実現します。ブラウザがほとんどの処理を行い、Astro は要素のマッチングを調整します。

MDX とコンポーネント

---
title: 私の投稿
date: 2026-04-30
---

import Callout from '../../components/Callout.astro';

# {frontmatter.title}

<Callout type="warn">
これはサーバーサイドでレンダリングされる警告です。JS は不要です。
</Callout>

MDX 内でインポートされたコンポーネントは、アイランドでない限り、ビルド/SSR 時に実行されます。

ハイブリッド SSR

// astro.config.mjs
import { defineConfig } from 'astro/config';
import cloudflare from '@astrojs/cloudflare';

export default defineConfig({
  output: 'hybrid',
  adapter: cloudflare(),
});
---
// src/pages/api/search.ts — エッジで実行

export const prerender = false;

export async function GET({ request }) {
  const url = new URL(request.url);
  const q = url.searchParams.get('q') ?? '';
  const results = await search(q);
  return new Response(JSON.stringify(results), { headers: { 'content-type': 'application/json' } });
}

prerender = false はルートを SSR に設定し、サイトの残りの部分は静的のままです。

アンチパターン

あらゆる場所で client:load を使う

症状: Lighthouse の JS バンドルサイズが肥大化。Astro のハイドレーション戦略が無意味になる。 診断: 開発者が最も馴染み深い client:load をデフォルトで使ってしまっている。 修正: デフォルトは client:idle または client:visible にする。client:load はファーストビューのインタラクティブ要素に限定する。

クライアントコンポーネントでデータをフェッチする

症状: すべてのページにローディングスピナーが表示され、SEO に悪影響。 診断: データフェッチが Astro のフロントマターではなく React コンポーネントに移動している。 修正: --- のフェンス内でフェッチし、サーバーサイドでレンダリングし、データをプロパティとしてアイランドに渡す。

型付けされていないフロントマター

症状: ビルドは成功するが、本番環境でタイトルに undefined が表示される。 診断: コンテンツコレクションのスキーマがなく、フロントマターの typo に気づかなかった。 修正: zod スキーマで defineCollection を使用する。フロントマターのミスはビルド時に検出される。

public/ と src/assets/ を画像の格納場所として混在させる

症状: 一部の画像は最適化されるが、他の画像は元のサイズで配信される。 診断: public/ はそのまま配信され、src/assets/ のみが Sharp で処理される。 修正: 画像を src/assets/ に移動する。<Image> を常に使用する。public/ は OGP 画像やファビコンのみに使用する。

Astro を SPA として使おうとする

症状: ハイドレーションと常に戦うことになり、ページ全体がインタラクティブになるまでアイランドが肥大化する。 診断: 仕事に適したフレームワークではない。Astro はコンテンツに優れており、SPA には Next/Remix が必要。 修正: ほとんどのページがインタラクティブな場合は Next/Remix を使用する。マーケティングとドキュメントには Astro を使用する。

client:only の過剰使用

症状: ページ読み込みのたびにレイアウトシフト(CLS)が発生し、コンテンツが表示される前に「ちらつき」が生じる。 診断: SSR をスキップすると、ブラウザは JS が実行されるまで空のプレースホルダを表示する。 修正: client:only は、コンポーネントが本当にサーバーサイドでレンダリングできない場合にのみ使用する。最終的なサイズに近いプレースホルダを提供する。

品質ゲート

  • デフォルトのクライアントディレクティブは client:idle または client:visible であり、client:load は用途ごとに正当性が説明されている。
  • すべてのコンテンツが defineCollection を介して型付けされたスキーマを持っている。
  • 画像は src/assets/ に配置され、<Image> コンポーネントを使用している。
  • マルチフレームワーク統合(@astrojs/react など)は、実際に存在するコンポーネントに対してのみ追加されている。
  • 最も遅い代表的なページで LCP が 2 秒未満。
  • ページごとに初回読み込み JS バジェットが設定されており、CI がリグレッションで失敗する。
  • MDX では静的な部分に Astro コンポーネントを使用し、アイランドはインタラクティブな部分のみに使用している。
  • ビュートランジションが主要なナビゲーションパス全体でテストされている。

対象外

  • 完全な SPA — Next.js、Remix、TanStack Start の方が適している。
  • Astro プラグイン/インテグレーションの作成 — 別のスキル(現時点では専用スキルなし)。
  • Vite 側のビルドチューニング — Astro は内部で Vite を使用。チャンクサイズ、HMR、プラグインライフサイクルの問題は vite-build-optimizer を参照。
  • ヘビーなクライアントステートアプリ(ダッシュボード、リアルタイムツール) — アイランドが役立つ範囲を超えて JS が多すぎる。
  • ネイティブモバイル — Astro はウェブのみ。

Individual skills in this repo

This repo contains 20 individual skills — each has its own dedicated page.

curiositech/windags-skills

Expert in 2000s-era music visualization (Milkdrop, AVS, Geiss) and modern WebGL implementations. Specializes in Butterchurn integration, Web Audio API AnalyserNode FFT data, GLSL shaders for audio-reactive visuals, and psychedelic generative art. Activate on "Milkdrop", "music visualization", "WebGL visualizer", "Butterchurn", "audio reactive", "FFT visualization", "spectrum analyzer". NOT for simple bar charts/waveforms (use basic canvas), video editing, or non-audio visuals.

curiositech/windags-skills

Expert legal research agent for finding and scraping expungement data state by state. Knows authoritative sources, URL patterns, Firecrawl configuration, and 2026 legal landscape.

curiositech/windags-skills

Expert in 3D computer vision labeling tools, workflows, and AI-assisted annotation for LiDAR, point clouds, and sensor fusion. Covers SAM4D/Point-SAM, human-in-the-loop architectures, and vertical-specific training strategies. Activate on '3D labeling', 'point cloud annotation', 'LiDAR labeling', 'SAM 3D', 'SAM4D', 'sensor fusion annotation', '3D bounding box', 'semantic segmentation point cloud'. NOT for 2D image labeling (use clip-aware-embeddings), general ML training (use ml-engineer), video annotation without 3D (use computer-vision-pipeline), or VLM prompt engineering (use prompt-engineer).

curiositech/windags-skills

Implement WCAG 2.2 AA/AAA compliance with automated testing, keyboard navigation, screen reader support, and focus management. Activate on: accessibility audit, WCAG compliance, keyboard navigation, screen reader, aria attributes, axe-core, focus trap. NOT for: design-level accessibility review (use design-accessibility-auditor), color contrast only (use css-in-js-architect).

curiositech/windags-skills

Time-blind friendly planning, executive function support, and daily structure for ADHD brains. Specializes in realistic time estimation, dopamine-aware task design, and building systems that actually work for neurodivergent minds.

curiositech/windags-skills

Designs digital experiences for ADHD brains using neuroscience research and UX principles. Expert in reducing cognitive load, time blindness solutions, dopamine-driven engagement, and compassionate design patterns. Activate on 'ADHD design', 'cognitive load', 'accessibility', 'neurodivergent UX', 'time blindness', 'dopamine-driven', 'executive function'. NOT for general accessibility (WCAG only), neurotypical UX design, or simple UI styling without ADHD context.

curiositech/windags-skills

>- Apply crisis decision-making research to agent routing, uncertainty triage, and coordination failure analysis in time-pressured systems. Use when diagnosing handoff failures, analytical paralysis, or expert judgment under incomplete information. NOT for routine coding, simple CRUD design, or static single-agent tasks with complete information.

curiositech/windags-skills

Extend and modify the admin dashboard, developer portal, and operations console. Use when adding new admin tabs, metrics, monitoring features, or internal tools. Activates for dashboard development, analytics, user management, and internal tooling.

curiositech/windags-skills

Conversation patterns and interaction protocols for multi-agent systems. Covers request/response, pub/sub, blackboard, delegation chains, debate, critique, consensus, fan-out/fan-in, supervisor-worker, and peer negotiation. Deep analysis of AutoGen conversation patterns, CrewAI delegation, LangGraph state passing, and FIPA-ACL performatives. Teaches how to design what agents say to each other and in what order. Activate on: "agent conversation", "agent protocol", "multi-agent debate", "agent delegation", "supervisor worker pattern", "agent voting", "consensus protocol", "fan-out fan-in", "agent negotiation", "blackboard pattern", "agent dialogue", "conversation topology", "agent handoff". NOT for: wire format or serialization (use agent-interchange-formats), orchestration infrastructure (use agentic-infrastructure-2026), single agent behavior (use agentic-patterns).

curiositech/windags-skills

Meta-agent for creating new custom agents, skills, and MCP integrations. Expert in agent design, MCP development, skill architecture, and rapid prototyping. Activate on 'create agent', 'new skill', 'MCP server', 'custom tool', 'agent design'. NOT for using existing agents (invoke them directly), general coding (use language-specific skills), or infrastructure setup (use deployment-engineer).

curiositech/windags-skills

AI-powered calendar management and agent-based scheduling coordination. Covers calendar APIs (Google Calendar, CalDAV/iCal), AI scheduling assistants (Reclaim, Clockwise, Motion, Cal.com), building custom calendar agents with MCP, multi-calendar merging, timezone management, focus block protection, meeting fatigue detection, and agent-to-agent meeting negotiation protocols. Activate on: "calendar agent", "AI scheduling", "calendar coordination", "meeting scheduling", "calendar API", "focus time protection", "calendar optimization", "Google Calendar MCP", "Reclaim", "Clockwise", "Motion", "Cal.com", "smart scheduling", "calendar-aware agent", "timezone scheduling", "agent negotiation meetings". NOT for: manual calendar UI component design (use form-validation-architect), project management scheduling or Gantt charts (use project-management-guru-adhd), general time-tracking or pomodoro apps (use adhd-daily-planner for time-awareness), building the agent itself from scratch (use agent-creator).

curiositech/windags-skills

Build and adopt production AI agent infrastructure in 2026. Covers framework selection (LangGraph, CrewAI, AutoGen, MCP), orchestration patterns, evaluation, observability, memory systems, and tool use. Also covers the SOCIAL dimension: how to sell agent infrastructure internally, change management, measuring ROI, building trust in autonomous systems, and scaling adoption across teams. Activate on: "agent infrastructure", "agent framework comparison", "which agent framework", "sell AI tools internally", "agent adoption", "agent observability", "agent evaluation", "MCP architecture", "agentic mesh", "enterprise AI agents", "AI change management", "agent ROI". NOT for: building specific agents (use ai-engineer), designing agent behavior patterns (use agentic-patterns), prompt tuning (use prompt-engineer).

curiositech/windags-skills

Fundamental patterns for effective agentic behavior. Teaches decomposition, tool orchestration, error recovery, context management, quality self-assessment, and knowing when to stop. Model-agnostic principles that make any agent more effective regardless of domain. Activate on: "how should I structure this agent", "agentic workflow", "agent patterns", "multi-step task", "tool orchestration", "/agentic-patterns", "decompose this", "agent best practices", "chain of actions", "when should the agent stop", "agent loop design". NOT for: creating agent infrastructure (use agent-creator), building DAGs (use windags-architect), specific tool implementation.

curiositech/windags-skills

Automated discovery and matching of agent skills for dynamic task routing and capability assessment

curiositech/windags-skills

Cryptographic security for agentic systems — zero-trust agent networking, signed message envelopes (JWS/JWE), capability-based security (ocaps), Merkle tree audit trails, WASM sandboxing, and formal verification. Covers CLI dev tool security, mTLS between agents, permission boundaries (least privilege for AI agents), and supply chain security for skills/plugins. Activate on: "agent security", "zero trust agents", "secure agent communication", "capability-based security", "ocap", "signed messages between agents", "agent audit trail", "sandbox agent execution", "agent permissions", "mTLS agents", "cryptographic verification", "agent supply chain", "OWASP agentic", "prove agent did X", "tamper-proof agent logs". NOT for: application-level SAST scanning (use security-auditor), network firewall rules (use infrastructure), SOC2/HIPAA compliance (organizational), or prompt injection defense (use prompt-engineer).

curiositech/windags-skills

Data structures and serialization formats for agent-to-agent communication. Covers message envelopes, structured output schemas, capability declarations, task handoff payloads, error/retry signaling, and context windows as data structures. Deep comparison of A2A protocol, MCP, OpenAI function calling, and LangChain message types. Teaches when to use rigid schemas vs free-form with validation, typed vs untyped, streaming vs batch. Activate on: "agent message format", "agent communication schema", "agent-to-agent protocol", "A2A protocol", "MCP message format", "structured output for agents", "agent interop", "interchange format", "agent serialization", "task handoff format", "capability declaration". NOT for: what agents say to each other (use agent-conversation-protocols), orchestration topology (use multi-agent-coordination), building agent infrastructure (use agentic-infrastructure-2026).

curiositech/windags-skills

Logic-based agent programming language implementing BDI architecture for practical autonomous agent development

curiositech/windags-skills

>- Design AgentSpeak(L)-style BDI agents with context-guarded plans, selection functions, and intention stacks. Use for interruptible autonomy, agent policy, and multi-agent orchestration in dynamic environments. NOT for simple rule engines, static planners, or centralized workflows.

curiositech/windags-skills

Foundational concurrent computation model where actors communicate exclusively through asynchronous message passing

curiositech/windags-skills

license: Apache-2.0 NOT for unrelated tasks outside this domain.

関連スキル