Great Docs

What it does

When your agent uses it

• Troubleshooting Python package documentation
• Tasks that involve Static sites and blogs
• Tasks that involve Technical writing

Example prompts

• “/great-docs”

Requirements

• Python 3
• A Bash shell
• Compatibility (from SKILL.md): Requires Python >=3.11, Quarto CLI installed.

Workflow steps

12 steps, taken from the first numbered list in SKILL.md.

1. 1Prepare build directory (copy assets, JS, SCSS)
2. 2Copy user guide from user_guide/
3. 3Copy project assets/
4. 4Refresh API reference (introspect package)
5. 5Generate llms.txt and llms-full.txt
6. 6Generate skill.md (if enabled)
7. 7Generate source links JSON
8. 8Generate changelog (from GitHub Releases)
9. 9Generate CLI reference (if enabled)
10. 10Process user guide (frontmatter, sidebar)
11. 11Process custom sections
12. 12Render API reference (.qmd files)

What it can do on your machine

Read from SKILL.md and the folder at commit e3b9467. It shows what the files ask for, not the result of running them.

• Tool permissions

  Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

  From allowed-tools in the SKILL.md frontmatter.

• Runs code

  Ships 2 files in scripts/ (Shell), which the agent can run.

  Shell commands in SKILL.md call:

  • pip
  • python

  From the folder's file list and the shell code blocks in SKILL.md.

• Network

  Hosts in commands or code, which the agent is likely to contact:

  • quarto.org

  Also links to:

  • posit-dev.github.io
  • github.com

  From URLs in SKILL.md, links to its own repository left out.

• Credentials

  Names no API keys, tokens, secrets or passwords.

  From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

• Compatibility

  Requires Python >=3.11, Quarto CLI installed.

  From compatibility in the SKILL.md frontmatter.

Context cost

Great Docs loads about 2.7k tokens when it runs, and up to ~6.5k if it reads all its reference files. Until then it costs about 81 tokens; SKILL.md has 866 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it

~81

When it runs · the whole SKILL.md, loaded when a task matches

~2.7k

With references · SKILL.md plus every file in references/, read only if the agent opens them

~6.5k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); the scripts in this folder are not scanned.

SKILL.md

The full file from pymc-labs/pathmc at commit e3b9467, republished under its MIT licence (© pymc-labs). 866 words, ~2,676 tokens.

name

great-docs

description

Generate documentation sites for Python packages with Great Docs. Covers init, build, preview, configuration (great-docs.yml), API reference, CLI docs, user guides, theming, deployment, and the llms.txt agent-context files. Use when creating, configuring, building, or troubleshooting Python package documentation.

compatibility

Requires Python >=3.11, Quarto CLI installed.

license

MIT

metadata.author

rich-iannone

metadata.version

2.0

metadata.tags

documentation, python-packages, quarto, api-reference, static-site

pip install great-docs
# Quarto must also be installed: https://quarto.org/docs/get-started/

cd my-package/        # directory with pyproject.toml
great-docs init       # create great-docs.yml, discover API
great-docs build      # full build -> great-docs/_site/
great-docs preview    # local server on port 3000

skills/great-docs/
├── SKILL.md                ← This file
├── references/
│   ├── config-reference.md ← All great-docs.yml options
│   ├── cli-reference.md    ← CLI commands and arguments
│   └── common-errors.md    ← Error patterns and fixes
├── scripts/
│   ├── setup-env.sh        ← Environment bootstrap script
│   └── run-build.sh        ← Build with validation
└── assets/
    └── config-template.yaml ← Starter great-docs.yml

def my_function():
    """
    Description.

    %seealso func_a, func_b: related functions, ClassC
    %nodoc
    """

Task Progress:
- [ ] Step 1: Install prerequisites
- [ ] Step 2: Initialize configuration
- [ ] Step 3: Customize config
- [ ] Step 4: Build and preview
- [ ] Step 5: Verify output

sections:
  - title: Examples
    dir: examples

# great-docs.yml
navbar_style: sky # gradient: sky, peach, lilac, mint, etc.
content_style: lilac # content area glow
dark_mode_toggle: true # toggle switch in navbar
logo: assets/logo.svg # or {light: ..., dark: ...}
hero: true # landing page hero section
announcement:
  content: "v2 is out!"
  type: info
  dismissable: true

#!/usr/bin/env bash
set -euo pipefail
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
pip install great-docs
quarto --version || echo "ERROR: Quarto not installed"

#!/usr/bin/env bash
set -euo pipefail
great-docs build
echo "Build complete. Site at great-docs/_site/"
ls great-docs/_site/index.html && echo "OK: index.html exists"

© pymc-labs, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 6 other files (scripts, references, assets) in .agents/skills/great-docs of pymc-labs/pathmc.

• SKILL.md
• assets/config-template.yaml
• references/cli-reference.md
• references/common-errors.md
• references/config-reference.md
• scripts/run-build.sh
• scripts/setup-env.sh

Open the folder on GitHubat commit e3b9467