Starlight to Skills

1. Define

   Describe what a skill does, when agents should use it, and choose which Starlight documentation pages contain the knowledge they need.

   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.',
   })

2. Generate

   Use the model of your choice to turn your definition and selected documentation pages into an agent skill.

   ❯ pnpm exec starlight-to-skills generate upgrade-v2-to-v3
   Generated 'upgrade-v2-to-v3'.
   
    SKILL.md 
   
     ---
     name: "upgrade-v2-to-v3"
     description: "Upgrade projects from package v2 to v3, including required dependency, configuration, and API changes. Use when planning, performing, reviewing, or troubleshooting the migration."
     ---
   
     # Upgrade to v3
   
     1. Update `@example/package` in `package.json` from `^2.0.0` to `^3.0.0`.
     2. Rename the `foo` configuration option to `bar`.
   
     ## Handle removed APIs
   
     v3 removes `createLegacyBaz()` without a replacement. If the project uses it, leave the call unchanged and mention it in the final response.
   
    Next steps 
   
   Review the generated skill.
   
    - To make changes, update the skill definition or documentation, then run 'pnpm exec starlight-to-skills generate upgrade-v2-to-v3' again.
    - To approve it, run 'pnpm exec starlight-to-skills approve upgrade-v2-to-v3'.

3. Approve

   Review and explicitly approve each new or updated skill before making it available to agents.

   ❯ pnpm exec starlight-to-skills approve upgrade-v2-to-v3
   Approved 'upgrade-v2-to-v3'.

4. Serve

   Make approved skills available to agents through Agent Skills Discovery on your Starlight site. List all skills in a dedicated catalog page, and prominently recommend individual skills in relevant documentation with the <SkillCallout> component.

   ❯ npx skills add https://example.com
   
   ┌   skills 
   │
   ◇  Source: https://example.com
   │
   ◇  Found 1 skill
   │
   ●  Skill: upgrade-v2-to-v3
   │
   │  Upgrade projects from package v2 to v3, including required dependency, configuration, and API changes. Use when planning, performing, reviewing, or troubleshooting the migration.
   │

5. Keep up to date

   Use deterministic checks to prevent outdated skills from remaining available to agents as your documentation changes.

   ❯ pnpm astro build
   [ERROR] [starlight-to-skills] Not all skills are up to date.
   
    upgrade-v2-to-v3 
   
   Skill 'upgrade-v2-to-v3' is not up to date.
   
    Documentation content changed 
   
    - ./guides/upgrade-to/v3.mdx
   
   Hint: Run 'pnpm exec starlight-to-skills generate upgrade-v2-to-v3', review the generated skill, and then run 'pnpm exec starlight-to-skills approve upgrade-v2-to-v3'. Alternatively, if the existing approved skill is still valid, run 'pnpm exec starlight-to-skills approve upgrade-v2-to-v3 --existing'.