Agent skill

quarto

This skill should be used when users need to create, configure, or render Quarto documents (.qmd files). Use this skill for generating reports, analysis documents, or presentations with HTML or Typst output formats, integrating code chunks (Python, R, Stata), and troubleshooting rendering issues.

View SKILL.md on GitHub Repository
Stars 163
Forks 31

Install this agent skill to your Project

npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/other/other/quarto

SKILL.md

Quarto Document Generation Skill

Contents

  • When to Use This Skill
  • Quick Start
  • Output Formats
  • Code Chunks
  • Document Workflow
  • Project Configuration
  • Troubleshooting
  • References

When to Use This Skill

Task Use This Skill
Create .qmd documents Yes
Configure HTML/Typst output Yes
Embed Python/R/Stata code Yes
Set up Quarto projects Yes
Debug rendering issues Yes
Generate reports from templates Yes

Quick Start

Basic Document Structure

markdown
---
title: "Document Title"
author: "Author Name"
date: "2025-01-05"
format:
  html:
    toc: true
    code-fold: true
---

# Introduction

Content here...

```{python}
# Code chunk
import pandas as pd

Render Commands

bash
quarto render document.qmd          # Default format
quarto render document.qmd --to html
quarto render document.qmd --to typst
quarto preview document.qmd         # Live preview

Output Formats

HTML vs Typst

Feature HTML Typst
Best for Web, interactive Print, PDF
Code folding Yes No
Embedded resources Yes N/A
Math rendering KaTeX/MathJax Native
Custom fonts CSS Direct

HTML Configuration

yaml
format:
  html:
    toc: true
    toc-depth: 3
    code-fold: true
    code-tools: true
    embed-resources: true
    theme: cosmo

Typst Configuration

yaml
format:
  typst:
    toc: true
    number-sections: true
    papersize: us-letter
    margin:
      x: 1.25in
      y: 1.25in
    fontsize: 11pt

Multiple Formats

yaml
format:
  html:
    toc: true
  typst:
    toc: true

Code Chunks

Cell Options

Option Effect
echo: false Hide code, show output
eval: false Show code, don't run
output: false Hide all output
warning: false Suppress warnings
include: false Run but show nothing
error: true Show errors, don't fail
cache: true Cache results

Python Example

markdown
```{python}
#| label: fig-plot
#| fig-cap: "My Figure"
#| echo: false

import matplotlib.pyplot as plt
plt.plot([1, 2, 3], [1, 4, 9])
plt.show()
```

Cross-References

markdown
See @fig-plot for visualization.
Results in @tbl-results.
Methods in @sec-methods.

## Methods {#sec-methods}

```{python}
#| label: fig-plot
#| fig-cap: "My plot"
```

Document Workflow

1. Create Document

bash
# Using template script
uv run python .claude/skills/quarto/scripts/create_quarto.py \
  --output report.qmd \
  --title "My Report" \
  --format html \
  --template analysis

Template types: analysis, report, presentation, article

2. Validate YAML

bash
uv run python .claude/skills/quarto/scripts/validate_yaml.py document.qmd

3. Edit Content

  • Write markdown and code chunks
  • Use cell options to control output
  • Add cross-references for figures/tables

4. Preview

bash
quarto preview document.qmd

5. Render Final

bash
quarto render document.qmd
quarto render document.qmd --to all  # All formats

6. Batch Render

bash
uv run python .claude/skills/quarto/scripts/render_all.py \
  --pattern "reports/*.qmd"

Project Configuration

_quarto.yml

yaml
project:
  type: default
  output-dir: _output

format:
  html:
    theme: cosmo
    toc: true
    code-fold: true
  typst:
    toc: true

execute:
  echo: true
  warning: false
  cache: true

Recommended Structure

project/
├── analysis/
│   ├── 01_import.qmd
│   └── 02_analyze.qmd
├── reports/
│   └── summary.qmd
├── _quarto.yml
├── references.bib
└── data/

Troubleshooting

YAML Errors

  1. Use spaces, not tabs for indentation
  2. Ensure colons have space after: key: value
  3. Quote strings with special characters
  4. Validate with: uv run python .claude/skills/quarto/scripts/validate_yaml.py

Code Execution Errors

  1. Verify kernel is installed (jupyter, IRkernel)
  2. Check code chunk syntax (triple backticks + language)
  3. Use #| error: true to show errors without failing
  4. Check file paths are relative and correct

Rendering Failures

  1. Run quarto check to verify installation
  2. Use quarto render --verbose for details
  3. Check for missing packages in code chunks
  4. For Typst: ensure Quarto 1.4+ is installed

Debug Commands

bash
quarto check              # Verify installation
quarto render --verbose   # Detailed output
quarto render --keep-md   # Keep intermediate files

References

Project References

  • Quick Reference - Comprehensive syntax reference

Available Assets

Template Description
assets/template_html.qmd Basic HTML analysis
assets/template_typst.qmd Basic Typst document
assets/template_dual.qmd Both formats
assets/template_report.qmd Formal report
assets/_quarto.yml Project configuration

Available Scripts

Script Purpose
scripts/create_quarto.py Generate from templates
scripts/render_all.py Batch render
scripts/validate_yaml.py Check YAML syntax

External Resources

Best Practices

  1. Use relative paths - Keep documents portable
  2. Cache long computations - cache: true for expensive chunks
  3. Test incrementally - Render frequently during development
  4. Use project config - Set common options in _quarto.yml
  5. Version control .qmd - Commit source, not rendered output
  6. Document dependencies - List required packages in setup chunk

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

majiayu000/claude-skill-registry

agent-ops-spec

Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-state

Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-spec

Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-testing

Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-testing

Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-state

Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.

163 31
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results