cran-extrachecks
Skill2 starsChanged 6 months agoMITView on GitHub
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.
1 other project uses a version of this.
Adopted by
Most recently taken up by
- BrightGold70/skillsword for word, first seen Nov 8, 2026
Other versions1 project uses a version of this.
Word for word · 1
- BrightGold70/skills★ 1100% same
Edited · 0
None found.
Wrote their own version · 0
None found.
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository23 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- alt-textSkill
- brand-ymlSkill
- cliSkill
- create-release-checklistSkill
- critical-code-reviewerSkill
- describe-designSkill
- ggsqlSkill
- implementSkill
- maintainer-declineSkill
- miraiSkill
- pr-createSkill
- pr-threads-addressSkill
- pr-threads-resolveSkill
- quarto-authoringSkill
- r-cli-appSkill
- release-postSkill
- review-testingSkill
- r-package-developmentSkill
- shiny-bslibSkill
- shiny-bslib-themingSkill
- testing-r-packagesSkill
- working-onSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
29 rules. About 0 are common, 11 are distinctive, and 18 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈11
Distinctive · estimate
This author's own choices. Worth a look.
18
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 17
Initial Assessment: Ask user if this is first submission or resubmission
- Very specific: line 28
Create NEWS.md: Run usethis::use_news_md() if not already present
- Very specific: line 29
Create cran-comments.md: Run usethis::use_cran_comments() if not already present
- Very specific: line 31
Ensure it includes install instructions that will be valid when the package is accepted to CRAN (usually install.packages("pkgname")).
- Distinctive: line 32
Check that it does not contain relative links.
- Very specific: line 34
Important: If README.Rmd exists, edit ONLY README.Rmd (README.md will be overwritten), then run devtools::build_readme() to re-render …
- Very specific: line 36
Check function documentation: Verify all exported functions have @return and @examples (see detailed guidance below)
- Very specific: line 37
Verify copyright holder: Check that Authors@R: includes a copyright holder with role [cph]
- Distinctive: line 38
Review bundled file licensing: Check licensing of any included third-party files
- Very specific: line 39
Run URL checks: Use urlchecker::url_check() and fix any issues
- Distinctive: line 51
Must be present for every exported function
- Very specific: line 84
If your exported function has a meaningful return value, it will almost definitely require an @examples section.
- Distinctive: line 92
If you write roxygen examples for un-exported functions, you must either:
- Very specific: line 94
Call them with ::: notation: pkg:::my_fun()
- Very specific: line 95
Use @noRd tag to suppress .Rd file creation
- Very specific: line 101
If showing an error, wrap the call in try() instead
- Very specific: line 102
Consider custom predicates (e.g., googlesheets4::sheets_has_token()) with if () blocks
- Very specific: line 118
Use @examplesIf for entire example sections requiring suggested packages:
- Distinctive: line 167
Put all software and R package names in single quotes:
- Distinctive: line 176
Keep titles under 65 characters.
- Distinctive: line 228
All acronyms must be fully expanded on first mention:
- Distinctive: line 241
Only use double quotes for publication titles, not for phrases or emphasis:
- Very specific: line 294
When urlchecker::url_check() flags these URLs, leave them as-is.
- Very specific: line 307
Remove file from .Rbuildignore
- Very specific: line 308
Use usethis::use_code_of_conduct() which generates sections without relative links
- Very specific: line 314
Always add [cph] role to Authors field, even if you're the only author:
- Distinctive: line 336
Update LICENSE year to current submission year:
- Very specific: line 349
If there are no references, reply to the email explaining this.
- Distinctive: line 425
Use this checklist to ensure nothing is missed before submission:
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
CRAN Extra Checks
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.
Workflow
- Initial Assessment: Ask user if this is first submission or resubmission
- Run Standard Checklist: Work through each item systematically (see below)
- Identify Issues: As you review files, note specific problems
- Propose Fixes: Suggest specific changes for each issue found
- Implement Changes: Make edits only when user approves
- Verify: Confirm all changes are complete
Standard CRAN Preparation Checklist
Work through these items systematically:
- Create NEWS.md: Run
usethis::use_news_md()if not already present - Create cran-comments.md: Run
usethis::use_cran_comments()if not already present - Review README:
- Ensure it includes install instructions that will be valid when the package is accepted to CRAN (usually
install.packages("pkgname")). - Check that it does not contain relative links. This works on GitHub but will be flagged by CRAN. Use full URLs to package documentation or remove the links.
- Does the README clearly explain the package purpose and functionality?
- Important: If README.Rmd exists, edit ONLY README.Rmd (README.md will be overwritten), then run
devtools::build_readme()to re-render README.md
- Ensure it includes install instructions that will be valid when the package is accepted to CRAN (usually
- Proofread DESCRIPTION: Carefully review
Title:andDescription:fields (see detailed guidance below) - Check function documentation: Verify all exported functions have
@returnand@examples(see detailed guidance below) - Verify copyright holder: Check that
Authors@R:includes a copyright holder with role[cph] - Review bundled file licensing: Check licensing of any included third-party files
- Run URL checks: Use
urlchecker::url_check()and fix any issues
Detailed CRAN Checks
Documentation Requirements
Return 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.
- Required even for functions marked
@keywords internal - Required even if function returns nothing - document as
@return Noneor similar - Must be present for every exported function
Example:
# 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.
- Required even for functions marked
@keywords internal - Exceptions exist for functions used purely for side effects (e.g., creating directories)
- Examples must be executable
Un-exported Functions with Examples
If you write roxygen examples for un-exported functions, you must either:
- Call them with
:::notation:pkg:::my_fun() - Use
@noRdtag to suppress.Rdfile creation
Using \dontrun{} Sparingly
\dontrun{} should only be used if the example really cannot be executed (e.g., missing additional software, API keys, etc.).
- If showing an error, wrap the call in
try()instead - Consider custom predicates (e.g.,
googlesheets4::sheets_has_token()) withif ()blocks - Sometimes
interactive()can be used as the condition - Lengthy examples (> 5 sec) can use
\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()
#' }DESCRIPTION Title Field
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:
- "A Toolkit for" → Remove
- "Tools for" → Remove
- "for R" → Remove
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 ParsingQuote Software/Package Names
Put all software and R package names in single quotes:
# GOOD
Title: Interface to 'Tiingo' Stock Price APILength Limit
Keep titles under 65 characters.
DESCRIPTION Description Field
Never Start With Forbidden Phrases
CRAN will reject descriptions starting with:
- "This package"
- Package name
- "Functions for"
# 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:
- What the package does
- Why it may be useful
- Types of problems it helps solve
# 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.URL and Link Validation
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:
- CRAN badge URLs (e.g.,
https://cran.r-project.org/package=pkgname) - CRAN status badges (e.g.,
https://www.r-pkg.org/badges/version/pkgname) - CRAN check results (e.g.,
https://cranchecks.info/badges/pkgname) - Package documentation URLs on r-universe or pkgdown sites that deploy after release
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.mdThis occurs when files are in .Rbuildignore. Solutions:
- Remove file from
.Rbuildignore - Use
usethis::use_code_of_conduct()which generates sections without relative links
Administrative Requirements
Copyright 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 = "jane.doe@posit.co"),
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 → 2026Method 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].Key Files to Review
Work through these files systematically:
- DESCRIPTION: Title, Description, Authors@R, URLs, License year
- R/*.R: Function documentation (
@return,@examples,@examplesIf,@noRd) - README.Rmd (if exists): Edit this file (NOT README.md), then run
devtools::build_readme() - README.md: Review for install instructions, relative links, URLs. Only edit directly if no README.Rmd exists
- cran-comments.md: Preemptive notes for reviewers
- NEWS.md: Version notes for this release
- .Rbuildignore: Files referenced in README
Common Fix Patterns
DESCRIPTION Title:
# Before
Title: A Toolkit for the Construction of Modeling Packages for R
# After
Title: Construct Modeling PackagesDESCRIPTION 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)Useful Tools
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 formatting
Final Verification Checklist
Use this checklist to ensure nothing is missed before submission:
Files and Structure
NEWS.mdexists and documents changes for this versioncran-comments.mdexists with submission notes- If README.Rmd exists, it was edited (not README.md) and
devtools::build_readme()was run - README includes valid install instructions (
install.packages("pkgname")) - README has no relative links (all links are full URLs or removed)
DESCRIPTION File
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]role- For Posit packages: Includes
person("Posit Software, PBC", role = c("cph", "fnd"), comment = c(ROR = "03wc8by49")) - LICENSE year matches current submission year
Function Documentation
- All exported functions have
@returndocumentation - All exported functions with meaningful returns have
@examples - No example sections use commented-out code
- Examples avoid
\dontrun{}unless truly necessary - Examples requiring suggested packages use
@examplesIforifguards - Un-exported functions with examples use
:::notation or@noRd
URLs and Links
urlchecker::url_check()was run- All URLs use https protocol (no http links)
- No redirecting URLs (except aspirational CRAN badge URLs)
- Aspirational URLs (CRAN badges, etc.) are left as-is
- No relative links in README that reference
.Rbuildignorefiles
Optional but Recommended
- If concerns about method references, added preemptive note to
cran-comments.md - Reviewed bundled file licensing if including third-party files
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

