{"kind":"AgentDefinition","metadata":{"namespace":"community","name":"astro","version":"0.1.0"},"spec":{"agents_md":"---\ndescription: 'Astro development standards and best practices for content-driven websites'\napplyTo: '**/*.astro, **/*.ts, **/*.js, **/*.md, **/*.mdx'\n---\n\n# Astro Development Instructions\n\nInstructions for building high-quality Astro applications following the content-driven, server-first architecture with modern best practices.\n\n## Project Context\n- Astro 5.x with Islands Architecture and Content Layer API\n- TypeScript for type safety and better DX with auto-generated types\n- Content-driven websites (blogs, marketing, e-commerce, documentation)\n- Server-first rendering with selective client-side hydration\n- Support for multiple UI frameworks (React, Vue, Svelte, Solid, etc.)\n- Static site generation (SSG) by default with optional server-side rendering (SSR)\n- Enhanced performance with modern content loading and build optimizations\n\n## Development Standards\n\n### Architecture\n- Embrace the Islands Architecture: server-render by default, hydrate selectively\n- Organize content with Content Collections for type-safe Markdown/MDX management\n- Structure projects by feature or content type for scalability\n- Use component-based architecture with clear separation of concerns\n- Implement progressive enhancement patterns\n- Follow Multi-Page App (MPA) approach over Single-Page App (SPA) patterns\n\n### TypeScript Integration\n- Configure `tsconfig.json` with recommended v5.0 settings:\n```json\n{\n  \"extends\": \"astro/tsconfigs/base\",\n  \"include\": [\".astro/types.d.ts\", \"**/*\"],\n  \"exclude\": [\"dist\"]\n}\n```\n- Types auto-generated in `.astro/types.d.ts` (replaces `src/env.d.ts`)\n- Run `astro sync` to generate/update type definitions\n- Define component props with TypeScript interfaces\n- Leverage auto-generated types for content collections and Content Layer API\n\n### Component Design\n- Use `.astro` components for static, server-rendered content\n- Import framework components (React, Vue, Svelte) only when interactivity is needed\n- Follow Astro's component script structure: frontmatter at top, template below\n- Use meaningful component names following PascalCase convention\n- Keep components focused and composable\n- Implement proper prop validation and default values\n\n### Content Collections\n\n#### Modern Content Layer API (v5.0+)\n- Define collections in `src/content.config.ts` using the new Content Layer API\n- Use built-in loaders: `glob()` for file-based content, `file()` for single files\n- Leverage enhanced performance and scalability with the new loading system\n- Example with Content Layer API:\n```typescript\nimport { defineCollection, z } from 'astro:content';\nimport { glob } from 'astro/loaders';\n\nconst blog = defineCollection({\n  loader: glob({ pattern: '**/*.md', base: './src/content/blog' }),\n  schema: z.object({\n    title: z.string(),\n    pubDate: z.date(),\n    tags: z.array(z.string()).optional()\n  })\n});\n```\n\n#### Legacy Collections (backward compatible)\n- Legacy `type: 'content'` collections still supported via automatic glob() implementation\n- Migrate existing collections by adding explicit `loader` configuration\n- Use type-safe queries with `getCollection()` and `getEntry()`\n- Structure content with frontmatter validation and auto-generated types\n\n### View Transitions \u0026 Client-Side Routing\n- Enable with `\u003cClientRouter /\u003e` component in layout head (renamed from `\u003cViewTransitions /\u003e` in v5.0)\n- Import from `astro:transitions`: `import { ClientRouter } from 'astro:transitions'`\n- Provides SPA-like navigation without full page reloads\n- Customize transition animations with CSS and view-transition-name\n- Maintain state across page navigations with persistent islands\n- Use `transition:persist` directive to preserve component state\n\n### Performance Optimization\n- Default to zero JavaScript - only add interactivity where needed\n- Use client directives strategically (`client:load`, `client:idle`, `client:visible`)\n- Implement lazy loading for images and components\n- Optimize static assets with Astro's built-in optimization\n- Leverage Content Layer API for faster content loading and builds\n- Minimize bundle size by avoiding unnecessary client-side JavaScript\n\n### Styling\n- Use scoped styles in `.astro` components by default\n- Implement CSS preprocessing (Sass, Less) when needed\n- Use CSS custom properties for theming and design systems\n- Follow mobile-first responsive design principles\n- Ensure accessibility with semantic HTML and proper ARIA attributes\n- Consider utility-first frameworks (Tailwind CSS) for rapid development\n\n### Client-Side Interactivity\n- Use framework components (React, Vue, Svelte) for interactive elements\n- Choose the right hydration strategy based on user interaction patterns\n- Implement state management within framework boundaries\n- Handle client-side routing carefully to maintain MPA benefits\n- Use Web Components for framework-agnostic interactivity\n- Share state between islands using stores or custom events\n\n### API Routes and SSR\n- Create API routes in `src/pages/api/` for dynamic functionality\n- Use proper HTTP methods and status codes\n- Implement request validation and error handling\n- Enable SSR mode for dynamic content requirements\n- Use middleware for authentication and request processing\n- Handle environment variables securely\n\n### SEO and Meta Management\n- Use Astro's built-in SEO components and meta tag management\n- Implement proper Open Graph and Twitter Card metadata\n- Generate sitemaps automatically for better search indexing\n- Use semantic HTML structure for better accessibility and SEO\n- Implement structured data (JSON-LD) for rich snippets\n- Optimize page titles and descriptions for search engines\n\n### Image Optimization\n- Use Astro's `\u003cImage /\u003e` component for automatic optimization\n- Implement responsive images with proper srcset generation\n- Use WebP and AVIF formats for modern browsers\n- Lazy load images below the fold\n- Provide proper alt text for accessibility\n- Optimize images at build time for better performance\n\n### Data Fetching\n- Fetch data at build time in component frontmatter\n- Use dynamic imports for conditional data loading\n- Implement proper error handling for external API calls\n- Cache expensive operations during build process\n- Use Astro's built-in fetch with automatic TypeScript inference\n- Handle loading states and fallbacks appropriately\n\n### Build \u0026 Deployment\n- Optimize static assets with Astro's built-in optimizations\n- Configure deployment for static (SSG) or hybrid (SSR) rendering\n- Use environment variables for configuration management\n- Enable compression and caching for production builds\n\n## Key Astro v5.0 Updates\n\n### Breaking Changes\n- **ClientRouter**: Use `\u003cClientRouter /\u003e` instead of `\u003cViewTransitions /\u003e`\n- **TypeScript**: Auto-generated types in `.astro/types.d.ts` (run `astro sync`)\n- **Content Layer API**: New `glob()` and `file()` loaders for enhanced performance\n\n### Migration Example\n```typescript\n// Modern Content Layer API\nimport { defineCollection, z } from 'astro:content';\nimport { glob } from 'astro/loaders';\n\nconst blog = defineCollection({\n  loader: glob({ pattern: '**/*.md', base: './src/content/blog' }),\n  schema: z.object({ title: z.string(), pubDate: z.date() })\n});\n```\n\n## Implementation Guidelines\n\n### Development Workflow\n1. Use `npm create astro@latest` with TypeScript template\n2. Configure Content Layer API with appropriate loaders\n3. Set up TypeScript with `astro sync` for type generation\n4. Create layout components with Islands Architecture\n5. Implement content pages with SEO and performance optimization\n\n### Astro-Specific Best Practices\n- **Islands Architecture**: Server-first with selective hydration using client directives\n- **Content Layer API**: Use `glob()` and `file()` loaders for scalable content management\n- **Zero JavaScript**: Default to static rendering, add interactivity only when needed\n- **View Transitions**: Enable SPA-like navigation with `\u003cClientRouter /\u003e`\n- **Type Safety**: Leverage auto-generated types from Content Collections\n- **Performance**: Optimize with built-in image optimization and minimal client bundles\n","description":"Astro development standards and best practices for content-driven websites","import":{"commit_sha":"541b7819d8c3545c6df122491af4fa1eae415779","imported_at":"2026-05-18T20:05:35Z","license_text":"MIT License\n\nCopyright GitHub, Inc.\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.","owner":"github","repo":"github/awesome-copilot","source_url":"https://github.com/github/awesome-copilot/blob/541b7819d8c3545c6df122491af4fa1eae415779/instructions/astro.instructions.md"},"manifest":{}},"content_hash":[120,80,183,106,145,183,194,81,204,58,77,212,0,89,248,42,174,36,5,250,182,169,16,79,218,137,150,127,113,110,156,162],"trust_level":"unsigned","yanked":false}