Agent-Skills.md

Agent Skills: Astro Starlight

Astro Starlight documentation theme — setup, sidebar config, Pagefind search, dark/light mode, plugins (DocSearch, blog, openapi, typedoc, versions), multi-language, Content Layer API, llms.txt, customization. Use for building documentation sites.

UncategorizedID: fusengine/agents/astro-starlight

Repository

fusengine/agents
fusengineLicense: MIT
7

Install this agent skill to your local

pnpm dlx add-skill https://github.com/fusengine/agents/tree/HEAD/plugins/astro-expert/skills/astro-starlight

Skill Files

Browse the full folder contents for astro-starlight.

Download Skill

Loading file tree…

plugins/astro-expert/skills/astro-starlight/SKILL.md

Skill Metadata

Name
astro-starlight
Description
Astro Starlight documentation theme — setup, sidebar config, Pagefind search, dark/light mode, plugins (DocSearch, blog, openapi, typedoc, versions), multi-language, Content Layer API, llms.txt, customization. Use for building documentation sites.

Astro Starlight

Production-ready documentation theme for Astro with built-in search, dark mode, i18n, and rich plugin ecosystem.

Agent Workflow (MANDATORY)

Before ANY implementation, use TeamCreate to spawn 3 agents:

  1. fuse-ai-pilot:explore-codebase - Analyze existing Starlight config, sidebar, and content structure
  2. fuse-ai-pilot:research-expert - Verify Starlight plugin APIs via Context7/Exa
  3. mcp__context7__query-docs - Check Starlight docs for Content Layer and i18n patterns

After implementation, run fuse-ai-pilot:sniper for validation.

Overview

When to Use

  • Building technical documentation sites
  • Creating API reference docs (with starlight-openapi)
  • Generating docs from TypeScript types (with starlight-typedoc)
  • Adding a blog to a documentation site (with starlight-blog)
  • Setting up versioned documentation (with starlight-versions)
  • Multi-language documentation with hreflang support

Why Starlight

| Feature | Benefit | |---------|---------| | Pagefind built-in | Full-text search, zero config | | Dark/light mode | Automatic, CSS custom properties | | Sidebar config | Filesystem-based or manual groups | | Plugin ecosystem | DocSearch, blog, openapi, typedoc | | Content Layer API | Astro 6 content collections integration | | llms.txt support | starlight-llms-txt for AI discoverability |

Reference Guide

Concepts

| Topic | Reference | When to Consult | |-------|-----------|-----------------| | Setup | setup.md | Installation, project structure | | Sidebar | sidebar-config.md | Navigation, groups, auto-gen | | Search | search.md | Pagefind, DocSearch, exclude pages | | Plugins | plugins.md | Blog, openapi, typedoc, versions | | i18n | i18n-multilang.md | Locales, translations, hreflang | | Content Layer | content-layer.md | docsLoader, schema, collections | | Customization | customization.md | CSS variables, components override |

Templates

| Template | When to Use | |----------|-------------| | starlight-config.md | Full astro.config.mjs with Starlight | | sidebar-example.md | Complex sidebar with groups and badges |

Best Practices

  1. Start with filesystem sidebar - Add manual config only when needed
  2. Keep Pagefind for small sites - DocSearch for high-traffic or large docs
  3. Use starlight-llms-txt - AI crawlers increasingly important for docs
  4. Content Layer schema - Type-safe frontmatter prevents runtime errors
  5. CSS custom properties - Override theme without component slots