# Install the Great Docs Skill

Great Docs publishes a [skill file](https://posit-dev.github.io/great-docs/skill.md) that teaches AI coding agents how to work with the tool. Once installed, your agent will know how to run Great Docs commands, edit configuration, write user guide pages, and troubleshoot common build problems without you having to explain each step.


# What is a skill?

A skill is a Markdown file (following the [Skills](https://github.com/vercel-labs/skills) specification) that gives an AI agent structured knowledge about a tool or workflow. It contains concise documentation, decision tables, common tasks, and gotchas all formatted so an agent can absorb the information and act on it. Think of it as a cheat sheet written specifically for an AI audience.


# Install with npx (recommended)

The fastest method works with Claude Code, GitHub Copilot, Cursor, Gemini CLI, Codex, and [30+ other agents](https://github.com/vercel-labs/skills):

``` bash
npx skills add https://posit-dev.github.io/great-docs/
```

This downloads the skill file and places it in the location your agent expects. No further configuration is needed.


# Install for Codex or OpenCode

Some agents (like Codex and OpenCode) work best when you tell them to fetch the skill directly. Paste this into your agent's chat:

    Fetch the skill file at https://posit-dev.github.io/great-docs/skill.md and follow the instructions.

The agent will download the file, read it, and incorporate the knowledge into the current session.


# Install manually

If you prefer to download the file yourself, use `curl`:

``` bash
curl -O https://posit-dev.github.io/great-docs/skill.md
```

Place the downloaded `skill.md` in your project root (or wherever your agent reads context files). Some agents also support a `.skills/` directory; consult your agent's documentation for the preferred location.


# What the skill teaches your agent

The Great Docs skill file covers the following areas:

- **Configuration reference.** Every key in `great-docs.yml` with example values, so the agent can modify settings without guessing at syntax.
- **Build pipeline.** The 11-step build sequence, so the agent understands what happens when you run `great-docs build` and where to look when something goes wrong.
- **Common tasks.** Step-by-step instructions for adding user guide pages, enabling CLI documentation, overriding the homepage, and more.
- **Gotchas.** Warnings about running from the project root, `module` vs. package name, circular imports, user guide ordering, and the `great-docs/` directory being regenerated on every build.

With the skill installed, you can give your agent high-level instructions like "add a user guide page about authentication" or "enable CLI docs for my package" and it will carry out the steps correctly.


# Keeping the skill up to date

The skill file is regenerated each time the Great Docs site is built and deployed. If you installed with `npx skills add`, you can re-run the same command to pull the latest version. For manual installs, re-download with `curl` periodically or whenever you upgrade Great Docs.