Skip to content
Starlight to Skills

Getting Started

Experimental: This plugin is in early development. Expect breaking changes between releases.

A Starlight plugin and command-line tool to turn Starlight documentation pages into reviewed, discoverable, and up-to-date agent skills.

  1. Define: Describe what a skill does, when agents should use it, and choose which Starlight documentation pages contain the knowledge they need.
  2. Generate: Use the model of your choice to turn your definition and selected documentation pages into an agent skill.
  3. Approve: Review and explicitly approve each new or updated skill before making it available to agents.
  4. Serve: Make approved skills available to agents through Agent Skills Discovery on your Starlight site.
  5. Keep up to date: Use deterministic checks to prevent outdated skills from remaining available to agents as your documentation changes.

Prerequisites

Section titled “Prerequisites”

You will need to have a Starlight website set up. If you don’t have one yet, you can follow the “Getting Started” guide in the Starlight docs to create one.

Installation

Section titled “Installation”

  1. Starlight to Skills is a Starlight plugin and command-line tool. Install it using your favorite package manager:

    Terminal window
    npm i starlight-to-skills

  2. Configure the plugin in your Starlight configuration in the astro.config.mjs file.

    astro.config.mjs
    import starlight from '@astrojs/starlight'
    import { defineConfig } from 'astro/config'
    import starlightToSkills from 'starlight-to-skills'
    

    export default defineConfig({
      integrations: [
        starlight({
          plugins: [starlightToSkills()],
          title: 'My Docs',
        }),
      ],
    })

  3. Starlight to Skills requires a dedicated starlight-to-skills.config.ts configuration file at the root of your Starlight project. Use the configuration to define the provider and model to use for generating skills.

    Starlight to Skills uses Mastra under the hood to call the model and generate the skill content. A list of all supported providers and models can be found in the Mastra documentation.

    The following example configures Starlight to Skills to use the gpt-5.6-luna model from the openai provider.

    starlight-to-skills.config.ts
    import { defineConfig } from 'starlight-to-skills/config'
    

    export default defineConfig({
      model: 'openai/gpt-5.6-luna',
    })

  4. Exclude the plugin’s temporary .starlight-to-skills/ directory from version control. Approved skills should be committed.

  5. Set Astro’s site option to your site’s deployed URL. This is required to enable the catalog page listing all approved skills available for discovery and to use the <SkillCallout> component.

    astro.config.mjs
    export default defineConfig({
      site: 'https://example.com',
      integrations: [
        starlight({
          // ...
        }),
      ],
    })

  6. Define your first skill by creating a TypeScript file in the src/skills/ directory named after the skill with a .skill.ts extension, e.g. skill-name.skill.ts.

    The definition should include a description of the skill and a list of Starlight documentation pages that contain the knowledge needed for the skill. Documentation paths are relative to the src/content/docs/ directory. Optionally, guidance can provide additional context and instructions for skill generation.

    The following example defines a skill named upgrade-v2-to-v3:

    src/skills/upgrade-v2-to-v3.skill.ts
    import { defineSkill } from 'starlight-to-skills/skill'
    

    export default defineSkill({
      description:
        'Upgrade projects from package v2 to v3, including required dependency, ' +
        'configuration, and API changes. Use when planning, performing, reviewing, ' +
        'or troubleshooting the migration.',
      docs: ['./upgrade.mdx', './guides/upgrade-to/v3.mdx'],
      guidance: 'List any in-use features no longer supported in v3.',
    })

  7. Generate the skill using the generate command of the Starlight to Skills CLI with the name of the skill.

    Provide the API key for the configured provider in a .env file at the root of your project that is excluded from version control or set it inline when running the command. You can find the complete list of required environment variables for each provider in the Mastra documentation.

    Terminal window
    npx starlight-to-skills generate upgrade-v2-to-v3

  8. Review the generated skill and approve it using the approve command with the name of the skill.

    Terminal window
    npx starlight-to-skills approve upgrade-v2-to-v3

Once approved, the new skill will be available to agents through Agent Skills Discovery on your Starlight site.

For example, for a Starlight site hosted at https://example.com, the skills command-line tool can be used to install the skill from your documentation site:

Terminal window
npx skills add https://example.com

When documentation pages associated with a skill change, the project-wide check command runs during the next build and reports the skill as not up to date. You can generate an updated skill or confirm that the existing skill remains valid.

The Starlight to Skills plugin behavior can be tweaked using various configuration options and skill definition properties.