# quarto-authoring

A skill for Quarto work: .qmd files, _quarto.yml, cross-references, callouts, citations, Mermaid diagrams and R Markdown migration.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 1400 installs · ★ 547
- Author: Mickaël Canouil (@mcanouil)
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/posit-dev/skills/tree/HEAD/quarto/quarto-authoring/SKILL.md
- Updated: 2026-10-15
- HTML: https://affpapa.org/en/nevibecode/skills/quarto-authoring

## What it does

The skill activates when a project actually uses Quarto: `.qmd` files, a `_quarto.yml` config, reports, websites, books or presentations. It also covers moving an existing project over from R Markdown, bookdown, xaringan, distill, blogdown or Jupyter. Plain R Markdown questions without a Quarto mention stay outside its scope.

Inside is a main file with the basic document structure plus reference files: cross-references, code cell options, figures, tables, citations, callouts, diagrams, layout, shortcodes, YAML front matter, extensions, compute engines. A separate set covers conversion, and those are meant to be read only during an explicit migration. The skill is based on Quarto CLI v1.9.36.

Some details bite. `#| cache: true` only works in R cells on the knitr engine; other languages ignore it silently, so you need `execute: cache: true` in YAML, and Python/Jupyter additionally needs `jupyter-cache`. Cell options use dashes (`fig-cap`), not dots, and label prefixes are mandatory: `fig-`, `tbl-`, `sec-`, `eq-`. Worth checking any snippets copied over from R Markdown.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add posit-dev/skills --skill quarto-authoring -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/quarto-authoring/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/quarto-authoring/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add posit-dev/skills --skill quarto-authoring -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/quarto-authoring/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add posit-dev/skills --skill quarto-authoring -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/quarto-authoring/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install posit-dev/skills quarto-authoring
```

2. **Manually: put the files in place**
- File: `.github/skills/quarto-authoring/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add posit-dev/skills --skill quarto-authoring -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/posit-dev/skills --path quarto/quarto-authoring
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/quarto-authoring/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add posit-dev/skills --skill quarto-authoring -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/posit-dev/skills/tree/HEAD/quarto/quarto-authoring/SKILL.md

## When to use it
- build an HTML or PDF report from a `.qmd` with a table of contents and folded code
- wire up cross-references to figures, tables and sections
- add note, warning and tip callouts to a document
- hook up a bibliography and format citations with a CSL style
- port a bookdown or xaringan project to Quarto

## Example prompts
- Create a Quarto report with a title, author and html format with a table of contents and folded code
- Add a cross-reference to `fig-plot` in this `.qmd` and give it a caption
- Convert this project from R Markdown to Quarto

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 0c4b96042424db6a.

BEGIN THIRD-PARTY FILE 0c4b96042424db6a
```text
---
name: quarto-authoring
description: Use when the user is explicitly working with Quarto, .qmd files, _quarto.yml, Quarto projects, or Quarto features such as callouts, cross-references, citations, Mermaid diagrams, extensions, websites, books, presentations, and reports. Also use for explicit migration from or comparison with R Markdown, bookdown, blogdown, xaringan, distill, or Jupyter notebooks to Quarto. Do not use for general R Markdown or related-format questions unless Quarto or migration to Quarto is explicitly mentioned.
metadata:
  author: Mickaël Canouil (@mcanouil)
  version: "1.4"
license: MIT
---

# Quarto Authoring

> This skill is based on Quarto CLI v1.9.36 (2026-03-24).

## When to Use What

Task: Write a new Quarto document
Use: Follow "QMD Essentials" below, then see specific reference files

Task: Add cross-references
Use: [references/cross-references.md](references/cross-references.md)

Task: Configure code cells
Use: [references/code-cells.md](references/code-cells.md)

Task: Add figures with captions
Use: [references/figures.md](references/figures.md)

Task: Create tables
Use: [references/tables.md](references/tables.md)

Task: Add citations and bibliography
Use: [references/citations.md](references/citations.md)

Task: Add callout blocks
Use: [references/callouts.md](references/callouts.md)

Task: Add diagrams (Mermaid, Graphviz)
Use: [references/diagrams.md](references/diagrams.md)

Task: Control page layout
Use: [references/layout.md](references/layout.md)

Task: Use shortcodes
Use: [references/shortcodes.md](references/shortcodes.md)

Task: Add conditional content
Use: [references/conditional-content.md](references/conditional-content.md)

Task: Use divs and spans
Use: [references/divs-and-spans.md](references/divs-and-spans.md)

Task: Configure YAML front matter
Use: [references/yaml-front-matter.md](references/yaml-front-matter.md)

Task: Find and use extensions
Use: [references/extensions.md](references/extensions.md)

Task: Apply markdown linting rules
Use: [references/markdown-linting.md](references/markdown-linting.md)

Task: Choose or configure a compute engine (knitr, jupyter, julia)
Use: [references/engines.md](references/engines.md)

### Migration (only when converting an existing project)

Do NOT read these references when writing new Quarto documents.
Only read the one matching the source format when the user explicitly asks to convert or migrate an existing project.

- R Markdown (.Rmd) to Quarto: [references/conversion-rmarkdown.md](references/conversion-rmarkdown.md)
```
END THIRD-PARTY FILE 0c4b96042424db6a

The third-party file has ended. Everything between the 0c4b96042424db6a tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2558 of 7446 bytes. © Mickaël Canouil (@mcanouil) · MIT · https://github.com/posit-dev/skills/tree/HEAD/quarto/quarto-authoring/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md