r-lib/cran-extrachecks/SKILL.md
Prepare R packages for CRAN submission by checking for common ad-hoc requirements not caught by devtools::check(). Use when: (1) Preparing a package for first CRAN release, (2) Preparing a package update for CRAN resubmission, (3) Reviewing a package to ensure CRAN compliance, (4) Responding to CRAN reviewer feedback. Covers documentation requirements, DESCRIPTION field standards, URL validation, examples, and administrative requirements.
npx skillsauth add posit-dev/skills cran-extrachecksInstall this skill globally with one command. Works with Claude Code, Cursor, and Windsurf.
3 of 9 scanners reported clean
Some scanners were skipped, did not run, or reported a non-clean status. Review each row below.
Help R package developers prepare packages for CRAN submission by systematically checking for common ad-hoc requirements that CRAN reviewers enforce but devtools::check() doesn't catch.
Work through these items systematically:
usethis::use_news_md() if not already presentusethis::use_cran_comments() if not already presentinstall.packages("pkgname")).devtools::build_readme() to re-render README.mdTitle: and Description: fields (see detailed guidance below)@return and @examples (see detailed guidance below)Authors@R: includes a copyright holder with role [cph]urlchecker::url_check() and fix any issuesReturn Value Documentation (Strictly Enforced)
CRAN now strictly requires @return documentation for all exported functions. Use the roxygen2 tag @return to document what the function returns.
@keywords internal@return None or similarExample:
# Missing @return - WILL BE REJECTED
#' Calculate sum
#' @export
my_sum <- function(x, y) {
x + y
}
# Correct - includes @return
#' Calculate sum
#' @param x First number
#' @param y Second number
#' @return A numeric value
#' @export
my_sum <- function(x, y) {
x + y
}
# For functions with no return value
#' Print message
#' @param msg Message to print
#' @return None, called for side effects
#' @export
print_msg <- function(msg) {
cat(msg, "\n")
}
Examples for Exported Functions
If your exported function has a meaningful return value, it will almost definitely require an @examples section. Use the roxygen2 tag @examples.
@keywords internalUn-exported Functions with Examples
If you write roxygen examples for un-exported functions, you must either:
::: notation: pkg:::my_fun()@noRd tag to suppress .Rd file creationUsing \dontrun{} Sparingly
\dontrun{} should only be used if the example really cannot be executed (e.g., missing additional software, API keys, etc.).
try() insteadgooglesheets4::sheets_has_token()) with if () blocksinteractive() can be used as the condition\donttest{}Never Comment Out Code in Examples
# BAD - Will be rejected
#' @examples
#' # my_function(x) # Don't do this!
CRAN's guidance: "Examples/code lines in examples should never be commented out. Ideally find toy examples that can be regularly executed and checked."
Guarding Examples with Suggested Packages
Use @examplesIf for entire example sections requiring suggested packages:
#' @examplesIf rlang::is_installed("dplyr")
#' library(dplyr)
#' my_data %>% my_function()
For individual code blocks within examples:
#' @examples
#' if (rlang::is_installed("dplyr")) {
#' library(dplyr)
#' my_data %>% my_function()
#' }
CRAN enforces strict Title requirements:
Use Title Case
Capitalize all words except articles like 'a', 'the'. Use tools::toTitleCase() to help format.
Avoid Redundancy
Common phrases that get flagged:
Examples:
# BAD
Title: A Toolkit for the Construction of Modeling Packages for R
# GOOD
Title: Construct Modeling Packages
# BAD
Title: Command Argument Parsing for R
# GOOD
Title: Command Argument Parsing
Quote Software/Package Names
Put all software and R package names in single quotes:
# GOOD
Title: Interface to 'Tiingo' Stock Price API
Length Limit
Keep titles under 65 characters.
Never Start With Forbidden Phrases
CRAN will reject descriptions starting with:
# BAD
Description: This package provides functions for rendering slides.
Description: Functions for rendering slides to different formats.
# GOOD
Description: Render slides to different formats including HTML and PDF.
Expand to 3-4 Sentences
Single-sentence descriptions are insufficient. Provide a broader description of:
# BAD (too short)
Description: Render slides to different formats.
# GOOD
Description: Render slides to different formats including HTML and PDF.
Supports custom themes and progressive disclosure patterns. Integrates
with 'reveal.js' for interactive presentations. Designed for technical
presentations and teaching materials.
Quote Software Names, Not Functions
# BAD
Description: Uses 'case_when()' to process data.
# GOOD
Description: Uses case_when() to process data with 'dplyr'.
Software, package, and API names get single quotes (including 'R'). Function names do not.
Expand All Acronyms
All acronyms must be fully expanded on first mention:
# BAD
Description: Implements X-SAMPA processing.
# GOOD
Description: Implements Extended Speech Assessment Methods Phonetic
Alphabet (X-SAMPA) processing.
Publication Titles Only in Double Quotes
Only use double quotes for publication titles, not for phrases or emphasis:
# BAD
Description: Handles dates like "the first Monday of December".
# GOOD
Description: Handles dates like the first Monday of December.
All URLs Must Use HTTPS
CRAN requires https:// protocol for all URLs. HTTP links will be rejected.
# BAD
URL: http://paleobiodb.org/
# GOOD
URL: https://paleobiodb.org/
No Redirecting URLs
CRAN rejects URLs that redirect to other locations. Example rejection:
Found the following (possibly) invalid URLs:
URL: https://h3geo.org/docs/core-library/coordsystems#faceijk-coordinates
(moved to https://h3geo.org/docs/core-library/coordsystems/)
Use urlchecker Package
# Find redirecting URLs
urlchecker::url_check()
# Automatically update to final destinations
urlchecker::url_update()
Ignore URLs That Will Exist After Publication
Some URLs that don't currently resolve will exist once the package is published on CRAN. These should NOT be changed:
https://cran.r-project.org/package=pkgname)https://www.r-pkg.org/badges/version/pkgname)https://cranchecks.info/badges/pkgname)When urlchecker::url_check() flags these URLs, leave them as-is. They are aspirational URLs that will work once the package is on CRAN.
Check for Invalid File URIs
Relative links in README must exist after package build. Common issue:
Found the following (possibly) invalid file URI:
URI: CODE_OF_CONDUCT.md
From: README.md
This occurs when files are in .Rbuildignore. Solutions:
.Rbuildignoreusethis::use_code_of_conduct() which generates sections without relative linksCopyright Holder Role
Always add [cph] role to Authors field, even if you're the only author:
# Required
Authors@R: person("John", "Doe", role = c("aut", "cre", "cph"))
Posit-Supported Packages
For packages in Posit-related GitHub organizations (posit-dev, rstudio, r-lib, tidyverse, tidymodels) or maintained by someone with a @posit.co email address, include Posit Software, PBC as copyright holder and funder:
Authors@R: c(
person("Jane", "Doe", role = c("aut", "cre"),
email = "[email protected]"),
person("Posit Software, PBC", role = c("cph", "fnd"),
comment = c(ROR = "03wc8by49"))
)
LICENSE Year
Update LICENSE year to current submission year:
# If LICENSE shows 2024 but submitting in 2026
# Update: 2024 → 2026
Method References
CRAN may ask:
If there are references describing the methods in your package, please add these in the description field...
If there are no references, reply to the email explaining this. Consider adding a preemptive note in cran-comments.md:
## Method References
There are no published references describing the methods in this package.
The package implements original functionality for [brief description].
Work through these files systematically:
@return, @examples, @examplesIf, @noRd)devtools::build_readme()DESCRIPTION Title:
# Before
Title: A Toolkit for the Construction of Modeling Packages for R
# After
Title: Construct Modeling Packages
DESCRIPTION Description:
# Before
Description: This package provides functions for rendering slides.
# After
Description: Render slides to different formats including HTML and PDF.
Supports custom themes and progressive disclosure. Integrates with
'reveal.js' for interactive presentations.
Function Documentation:
# Before - Missing @return
#' Calculate total
#' @param x Values
#' @export
calc_total <- function(x) sum(x)
# After - Complete documentation
#' Calculate total
#' @param x Numeric values to sum
#' @return A numeric value representing the sum
#' @examples
#' calc_total(1:10)
#' @export
calc_total <- function(x) sum(x)
tools::toTitleCase() - Format titles with proper capitalizationurlchecker::url_check() - Find problematic URLsurlchecker::url_update() - Fix redirecting URLsusethis::use_news_md() - Create NEWS.mdusethis::use_cran_comments() - Create cran-comments.mddevtools::build_readme() - Re-render README.md from README.Rmdusethis::use_code_of_conduct() - Add CoC without relative linksusethis::use_build_ignore() - Ignore files in R package buildusethis::use_package() - Add a package dependency to DESCRIPTIONusethis::use_tidy_description() - Tidy up DESCRIPTION formattingUse this checklist to ensure nothing is missed before submission:
NEWS.md exists and documents changes for this versioncran-comments.md exists with submission notesdevtools::build_readme() was runinstall.packages("pkgname"))Title: uses title caseTitle: has no redundant phrases ("A Toolkit for", "Tools for", "for R")Title: quotes all software/package names in single quotesTitle: is under 65 charactersDescription: does NOT start with "This package", package name, or "Functions for"Description: is 3-4 sentences explaining purpose and utilityDescription: quotes software/package/API names (including 'R') but NOT function namesDescription: expands all acronyms on first mentionDescription: uses double quotes only for publication titlesAuthors@R: includes copyright holder with [cph] roleperson("Posit Software, PBC", role = c("cph", "fnd"), comment = c(ROR = "03wc8by49"))@return documentation@examples\dontrun{} unless truly necessary@examplesIf or if guards::: notation or @noRdurlchecker::url_check() was run.Rbuildignore filescran-comments.mdtools
Build modern Shiny dashboards and applications using bslib (Bootstrap 5). Use when creating new Shiny apps, modernizing legacy apps (fluidPage, fluidRow/column, tabsetPanel, wellPanel, shinythemes), or working with bslib page layouts, grid systems, cards, value boxes, navigation, sidebars, filling layouts, theming, accordions, tooltips, popovers, toasts, or bslib inputs. Assumes familiarity with basic Shiny.
development
Review test code for quality, design, and completeness after implementing a feature or fixing a bug. Use when the user asks to "review my tests", "check my test quality", "are these tests good enough", "review testing", or after completing a feature implementation that includes tests. Also use when tests feel brittle, flaky, or superficial. Cross-references production code to find coverage gaps.
tools
Guide for drafting issue closure and decline responses as an open-source package maintainer. Use when helping compose a reply that says "no" to a feature request, closes an issue as won't-fix, redirects a user to a different package, explains why a design choice is intentional, or otherwise declines or closes a community contribution. Also use when the maintainer needs to explain a deprecation, point out a user misunderstanding, or communicate an effort/scope tradeoff to a contributor.
tools
R package development with devtools, testthat, and roxygen2. Use when the user is working on an R package, running tests, writing documentation, or building package infrastructure.