菜单
Use when creating or modifying .astro/.tsx files, configuring astro.config.mjs, working with Content Collections, or when TypeScript or build errors occur.
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
Use when creating or modifying any UI element visible to the user, reviewing HTML markup, adding interactive elements, or when Lighthouse Accessibility drops below 90.
Use when creating or editing pages, blog posts, or content files, adding meta tags, or when Lighthouse SEO drops below 90.
Use when completing any task (final validation step), running audits, preparing for deployment, or when ESLint/TypeScript/build errors occur.
Use when writing or reviewing any CSS class, changing colors, modifying globals.css, or when hardcoded colors or inline styles are detected.
Use when creating or modifying any visible UI element, adjusting spacing or typography, reviewing visual consistency, or when Lighthouse Performance drops below 90.
Use when starting work on an AstroDeck project, needing to understand the project structure, or looking up available components, sections, and layouts.
| name | astro |
| description | Use when creating or modifying .astro/.tsx files, configuring astro.config.mjs, working with Content Collections, or when TypeScript or build errors occur. |
Astro 6 patterns, Islands Architecture, Content Collections, routing, build
| Metric | Target | Measurement |
|---|---|---|
| TypeScript Errors | 0 | npx tsc --noEmit 2>&1 | grep "error TS" | wc -l |
| Build Warnings | 0 | npm run build 2>&1 | grep -i "warn" | wc -l |
| Build Time | <3s | npm run build timing output |
| Deprecated patterns / relative imports | 0 | npm run check:kpis |
---
// ✅ Astro 6
import { ClientRouter } from 'astro:transitions';
---
<head>
<ClientRouter />
</head>
// ❌ Deprecated
import { ViewTransitions } from 'astro:transitions';
// ✅ Astro 6
import { z } from 'astro/zod';
// ❌ Deprecated
import { z } from 'astro:content';
import { z } from 'astro:schema';
// src/content.config.ts
import { defineCollection } from 'astro:content';
import { z } from 'astro/zod';
import { glob } from 'astro/loaders';
const blog = defineCollection({
loader: glob({ pattern: '**/*.{md,mdx}', base: './src/content/blog' }),
schema: z.object({
title: z.string(),
description: z.string(),
pubDate: z.coerce.date(),
draft: z.boolean().optional(),
}),
});
export const collections = { blog };
---
// Usage in pages
import { getCollection } from 'astro:content';
const posts = await getCollection('blog');
---
| Use .astro when... | Use .tsx when... |
|---|---|
| Static content | Client-side interactivity needed |
| Server-side rendering | State management needed |
| Layout components | Event handlers needed |
| Section components | Forms with validation |
| SEO/meta components | Complex UI (dialogs, dropdowns) |
<!-- Load immediately (above-the-fold interactivity) -->
<Component client:load />
<!-- Load when visible (below-the-fold) -->
<Component client:visible />
<!-- Load on idle (non-critical UI) -->
<Component client:idle />
<!-- Only on a specific platform -->
<Component client:only="react" />
Rule of thumb: client:visible > client:idle > client:load. Use client:load only for immediately visible interactive elements.
---
interface Props {
title: string;
description?: string;
variant?: 'default' | 'compact' | 'wide';
class?: string;
}
const {
title,
description,
variant = 'default',
class: className,
} = Astro.props;
---
<!-- Named slots -->
<section>
<div class="header">
<slot name="header" />
</div>
<div class="content">
<slot /> <!-- Default slot -->
</div>
<div class="footer">
<slot name="footer" />
</div>
</section>
import { defineConfig } from 'astro/config';
import tailwindcss from '@tailwindcss/vite';
import react from '@astrojs/react';
import sitemap from '@astrojs/sitemap';
export default defineConfig({
site: 'https://example.com',
integrations: [react(), sitemap()],
vite: {
plugins: [tailwindcss()],
},
});
Always use @/ (configured in tsconfig.json):
// ✅
import Hero from '@/components/sections/Hero.astro';
import { Button } from '@/components/ui/button';
// ❌
import Hero from '../../components/sections/Hero.astro';
These rules always apply — even under time pressure, even when "it works anyway":
ViewTransitions. Always ClientRouter. "But the docs say ViewTransitions" — those docs are outdated; Astro 6 uses ClientRouter.z from astro:content or astro:schema. Always import { z } from 'astro/zod'. Other imports compile but break Content Collections.@/ import alias. Relative imports (../../) work, but every file move breaks them. @/ is refactoring-safe.client:load without good reason. client:visible or client:idle are almost always better. "I need it immediately" is rarely true for below-the-fold elements.The convention guard hook (.claude/hooks/guard-conventions.mjs) blocks the
deprecated patterns automatically and warns on relative imports.
Read LEARNINGS.md in this directory to avoid known anti-patterns.