Agent skill

starlight-pydocs ships an agent skill: a short setup checklist that coding agents such as Claude Code and Codex load when you ask them to add or configure the plugin. It links to these guides rather than repeating them, so it stays correct as the plugin changes. The skill is in the npm package at skills/starlight-pydocs/SKILL.md, and is reproduced in full below.

Install the skill

With the skills CLI

The skills CLI installs the skill from GitHub, and asks which of your agents to install it for:

npx skills add ewels/starlight-pydocs

By hand

Download SKILL.md from GitHub and copy it into your agent’s skills directory:

• Claude Code: .claude/skills/starlight-pydocs/SKILL.md in your project, or ~/.claude/skills/starlight-pydocs/SKILL.md for all your projects (docs).
• Codex: .agents/skills/starlight-pydocs/SKILL.md in your project, or ~/.agents/skills/starlight-pydocs/SKILL.md for all your projects (docs). Cursor, OpenCode and several other agents read .agents/skills/ too.

Using it

The agent loads the skill on its own when a task matches its description, such as adding starlight-pydocs to a site. You can also call it by name: /starlight-pydocs in Claude Code, or $starlight-pydocs in Codex.

Skill contents

Everything below is SKILL.md word for word. Only its frontmatter and title are left out, and its headings are one level lower so they sit under this one.

A short checklist for adding starlight-pydocs to a site. It links to the full documentation rather than repeating it, so read the linked page before you change anything it covers.

1. Install and wire it up

• Install starlight-pydocs and add it as a Starlight plugin. Put pydocsSidebarGroup where the API reference belongs in the sidebar. Getting started
• A plain Astro site with no Starlight uses starlight-pydocs/astro instead. Vanilla Astro
• search is an array of paths to the parent of the package directory (['../src'] for ../src/mypkg), relative to the Astro project root.

2. Make Griffe runnable wherever the site builds

The build runs Griffe unless the package has a pre-generated source. The plugin tries uvx first, then python -m griffe. So a CI or deploy job (GitHub Pages included) needs one of these:

• uv on PATH, for example astral-sh/setup-uv before the build step;
• Python with griffe installed; or
• a dump written by the Python project and read with source.file or source.url, which needs no Python at all. Pre-generated dumps

Version annotations also need the full git history in CI (fetch-depth: 0). Version annotations

3. Decide what the public API is

Griffe documents every name without a leading underscore, so helpers and internals end up in the reference unless you say otherwise. Pick one:

• declare __all__ in each module (it wins, as in mkdocstrings). It picks that module’s own members only: submodules get their pages either way;
• or use members.include / members.exclude globs in the package config.

If only part of the documented surface is stable, say so on a page of your own. Configuration → Member selection

4. Match the docstrings and links

• Set docstringStyle (google, numpy, sphinx or auto). Docstring styles
• Add Sphinx inventories so annotations link to Python and to other projects. Cross-references
• Add source links to the repository. Source links

5. Optional: add starlight-codeblocks

starlight-codeblocks is a separate Starlight plugin. With both installed, they work together with no pydocs option. starlight-codeblocks

• Install starlight-codeblocks and add codeblocks() to the Starlight plugins.
• Python code blocks anywhere on the site then link to the API pages, and type links in signatures get hover cards. Long docstring examples collapse, and doctests get a Copy commands button.
• To link a hand-written example to an older version of the package, add pydocsBase="<base>" to its fence line.
• In mdx code blocks, codeblocks reads directives only in {/* */} comments.
• To turn a feature off, use the codeblocks option, such as apiLinks: false.

6. Check a built site, not only the dev server

Run astro build and read the [starlight-pydocs] lines in the log, and any starlight-codeblocks warnings. Warnings passed through from Griffe (griffe: WARNING …) point at docstrings worth fixing. Any other warning usually means something is missing from the output, such as uncoloured signatures. Then open a generated page from astro preview and check that signatures are coloured and annotation links resolve.