AndrewBrown-USDA/aigb-skills-usda / skills/r-package-vignette
r-package-vignette
VerifiedAuthor and build R package vignettes using litedown or knitr + rmarkdown. Use when creating or updating vignettes/*.Rmd, configuring VignetteBuilder in DESCRIPTION, gating expensive or optional-dependency chunks with evaluation guards, or verifying vignette builds.
R Package Vignette Workflow
Author, guard, and verify R package vignettes (vignettes/*.Rmd) using either the lightweight litedown engine or the classic knitr + rmarkdown engine.
1. Discovery & Engine Selection
- Check
DESCRIPTION:- Inspect
VignetteBuilderandSuggeststo determine which engine the repository uses. - Verify which dependencies are in
Imports(always available) vs.Suggests(must be guarded withrequireNamespace()).
- Inspect
- Choose the Engine Reference:
litedown(VignetteBuilder: litedown): Minimal dependency footprint, fast rendering vialitedown::fuse(), and chunk options configured withlitedown::reactor(). Read./references/litedown.md.knitr+rmarkdown(VignetteBuilder: knitr): Standard R Markdown ecosystem (rmarkdown::html_vignette), chunk options configured withknitr::opts_chunk$set(), and seamlesspkgdownintegration. Read./references/knitr-rmarkdown.md.- When starting a new package without existing vignettes, prefer
litedownfor lightweight/low-dependency packages andknitr+rmarkdownwhenpkgdownor complex Pandoc features are required.
- Inspect Target Code & Data:
- Read existing
vignettes/*.Rmdfiles to match YAML headers, chunk option styles, and environment variable conventions. - Read target
R/*.Rsource files to verify exact function signatures, arguments, and return structures before writing examples. - If the vignette requires creating or updating a packaged dataset in
data/*.rdaorinst/extdata/, use ther-package-dataskill first.
- Read existing
2. Shared Vignette Conventions
Conditional Evaluation Guards (CRAN & CI Safety)
Vignettes must build cleanly on CRAN and CI machines where optional Suggests packages, network access, credentials, or long compute budgets are unavailable.
Define a boolean guard at the top of the vignette using the repository's standard pattern (isTRUE(as.logical(Sys.getenv(...)))) combined with requireNamespace():
run_long <- isTRUE(as.logical(Sys.getenv("R_<PKG>_RUN_LONG_EXAMPLES", unset = "FALSE"))) &&
requireNamespace("<optional_pkg>", quietly = TRUE)
Pass eval = run_long to the engine's global option setter (litedown::reactor() or knitr::opts_chunk$set(); see engine reference files for exact syntax).
Dependency & Resource Hygiene
- Evaluated Chunks: Only load packages listed in
Importsor guardedSuggests. Operate on pre-packageddata/*.rdaorinst/extdata/datasets. - Acquisition / Network Code: Place heavy data-fetching workflows (e.g., remote spatial queries, web API downloads) in non-evaluated chunks (
eval = FALSE) or reference the correspondingdata-raw/<dataset>.Rscript. - Temporary Files & Cleanup: Write any intermediate files to
tempdir()and remove downloaded/temporary artifacts in a hidden cleanup chunk at the end of the vignette (unlink(..., recursive = TRUE)) so sequential vignette builds in CI do not exhaust disk space. - State Restoration: Save and restore
options()orpar()changes when modifying global R state.
3. Execution & Verification Workflow
- Propose Outline: Present the target functions, section outline, engine choice, and dataset dependencies for approval before authoring.
- Install Current Package State: Always install the local package (and any new datasets) before rendering so the vignette executes against the current namespace:
R CMD INSTALL . - Render & Verify with Guard Enabled: Execute the engine-specific render command (see
./references/litedown.mdor./references/knitr-rmarkdown.md) withR_<PKG>_RUN_LONG_EXAMPLES=TRUEto verify all code chunks run without errors. - Verify Tarball Build: Confirm that
R CMD build .builds the vignette index and outputs cleanly. - Clean Up: Remove transient
.html,.md, or figure files generated invignettes/that are not tracked in version control.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |