Write User Guide

What it does

When your agent uses it

• Improving user-guide content
• Tasks that involve Technical writing
• Tasks that involve Static sites and blogs

Example prompts

• “/write-user-guide”

Requirements

• Python 3
• Compatibility (from SKILL.md): Requires Great Docs >=0.8, Quarto CLI installed.

Workflow steps

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

1. 1Rename files to adjust numeric prefixes.
2. 2Update guide-section values to regroup.
3. 3Rebuild. Great Docs regenerates the sidebar automatically.
4. 4Check for broken cross-references.

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

  No scripts in the folder and no shell commands in SKILL.md (its code samples are markdown, bash and yaml).

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

• Network

  No URLs in SKILL.md.

  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 Great Docs >=0.8, Quarto CLI installed.

  From compatibility in the SKILL.md frontmatter.

Context cost

Write User Guide loads about 2.3k tokens when it runs, and up to ~4.3k if it reads all its reference files. Until then it costs about 75 tokens; SKILL.md has 761 words of instructions outside code blocks.

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

~75

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

~2.3k

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

~4.3k

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); files beside SKILL.md are not scanned.

SKILL.md

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

name

write-user-guide

description

Write and maintain narrative user-guide pages for a Great Docs site. Covers page creation, QMD frontmatter, section grouping, sidebar ordering, callouts, executable code cells, cross-references, and content guidelines. Use when adding, reorganizing, or improving user-guide content.

compatibility

Requires Great Docs >=0.8, Quarto CLI installed.

license

MIT

metadata.author

rich-iannone

metadata.version

1.0

metadata.tags

documentation, user-guide, quarto, content-authoring

mkdir -p user_guide
cat > user_guide/00-introduction.qmd << 'EOF'
---
title: "Introduction"
guide-section: "Getting Started"
tags: [Getting Started]
---

# Introduction

Welcome to the project. This guide walks you through...
EOF

great-docs build

skills/write-user-guide/
├── SKILL.md
└── references/
    ├── page-anatomy.md
    └── writing-guidelines.md

user_guide/
├── 00-introduction.qmd     # appears first
├── 01-installation.qmd
├── 02-quickstart.qmd
├── 03-authoring-qmd-files.qmd
└── 04-writing-docstrings.qmd

---
title: "Writing Docstrings"
guide-section: "Getting Started"
tags: [API, Content]
---

Getting Started
├── Introduction
├── Installation
└── Quick Start
Site Content
├── Authoring QMD Files
├── Writing Docstrings
└── User Guides

# Page Title

Opening paragraph: 2-3 sentences explaining what this page covers
and why the reader cares.

## First Major Section

Narrative prose. Keep paragraphs short (3-5 sentences).

### Subsection

More detail. Use tables, code blocks, and callouts to break up text.

## Second Major Section

...

:::{.callout-tip}

## Pro tip

You can combine `guide-section` with `tags` to make pages
discoverable from multiple angles.
:::

:::{.callout-warning}

## Watch out

Renaming a page file changes its URL. Update any cross-references.
:::

:::{.callout-note}
This feature requires Great Docs 0.8 or later.
:::

```{python}
import great_docs
gd = great_docs.GreatDocs()
print(gd.project_path)
```

{{< tbl-preview file="assets/data/students.csv" >}}
{{< tbl-explorer file="assets/data/students.csv" >}}

```{python}
from great_docs import tbl_preview, tbl_explorer

tbl_preview(df)           # compact head/tail preview
tbl_explorer(df)          # interactive: sort, filter, paginate
```

See the [Configuration](../user-guide/configuration.qmd) page.
See the [API reference](../reference/GreatDocs.qmd) page.

![Architecture diagram](../assets/architecture.png)

Task Progress:
- [ ] Step 1: Choose a filename
- [ ] Step 2: Write frontmatter
- [ ] Step 3: Write content
- [ ] Step 4: Build and preview

© 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 2 other files (references) in .agents/skills/write-user-guide of pymc-labs/pathmc.

• SKILL.md
• references/page-anatomy.md
• references/writing-guidelines.md

Open the folder on GitHubat commit e3b9467