# Agent skill

starlight-pydocs ships an [agent skill](https://agentskills.io/): 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](#skill-contents).

## Install the skill

### With the skills CLI

The [`skills` CLI](https://github.com/vercel-labs/skills) installs the skill from GitHub, and asks
which of your agents to install it for:

```sh
npx skills add ewels/starlight-pydocs
```

### By hand

Download [`SKILL.md`](https://github.com/ewels/starlight-pydocs/blob/main/skills/starlight-pydocs/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](https://code.claude.com/docs/en/skills)).
- **Codex**: `.agents/skills/starlight-pydocs/SKILL.md` in your project, or
  `~/.agents/skills/starlight-pydocs/SKILL.md` for all your projects
  ([docs](https://learn.chatgpt.com/docs/build-skills)). 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](https://ewels.github.io/starlight-pydocs/guides/getting-started/)
- A plain Astro site with no Starlight uses `starlight-pydocs/astro` instead.
  [Vanilla Astro](https://ewels.github.io/starlight-pydocs/guides/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](https://ewels.github.io/starlight-pydocs/guides/pregenerated-dumps/)

Version annotations also need the full git history in CI (`fetch-depth: 0`).
[Version annotations](https://ewels.github.io/starlight-pydocs/guides/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](https://ewels.github.io/starlight-pydocs/guides/configuration/#member-selection)

### 4. Match the docstrings and links

- Set `docstringStyle` (`google`, `numpy`, `sphinx` or `auto`).
  [Docstring styles](https://ewels.github.io/starlight-pydocs/guides/docstring-styles/)
- Add Sphinx inventories so annotations link to Python and to other projects.
  [Cross-references](https://ewels.github.io/starlight-pydocs/guides/cross-references/)
- Add source links to the repository.
  [Source links](https://ewels.github.io/starlight-pydocs/guides/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](https://ewels.github.io/starlight-pydocs/guides/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.