Install the Great Docs Skill

Give your AI coding agent the Great Docs skill so it can help build and configure your documentation site.

Great Docs publishes a skill file 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 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 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:

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.