Skip to main content
skill CX Codex

r-cran-extrachecks — Claude Code skill: CRAN checks

The r-cran-extrachecks Claude Code skill checks R packages for CRAN submission requirements that devtools::check() misses. It runs during first submissions, resubmissions, package reviews, and responses to CRAN feedback.

MIT 144 installs ★ 574 updated 2026-10-15

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add posit-dev/skills --skill r-cran-extrachecks -a claude-code
Open on GitHub

What r-cran-extrachecks does

The skill reviews package files for issues that can arise during CRAN checks. It covers function documentation, the Title: and Description: fields in DESCRIPTION, links, examples, licenses for bundled third-party files, and administrative requirements. URL checks use urlchecker::url_check().

Its checklist includes creating NEWS.md and cran-comments.md with usethis, reviewing the README, and checking rules for @return and @examples. When README.Rmd exists, edits go there; devtools::build_readme() then regenerates README.md. The skill suggests fixes and applies them only with approval.

S3 methods whose roxygen block contains only @export or @exportS3Method are exempt from the @return and @examples requirements. Add a title or another documentation tag, and roxygen generates an .Rd file, so the exemption no longer applies.

What it helps with

  • catch CRAN submission checks that devtools::check() misses
  • check documentation tags on exported functions
  • find relative links in a README
  • prepare NEWS.md and cran-comments.md for a package submission
  • review CRAN feedback and propose code or documentation fixes

Example prompts for the agent

  • Check my R package before its first CRAN submission.
  • Review the documentation and DESCRIPTION before I resubmit this package.
  • Go through the CRAN reviewer’s feedback and suggest fixes.

How to install r-cran-extrachecks

1Skills CLI (Vercel)

npx skills add posit-dev/skills --skill r-cran-extrachecks -a claude-code

2Manually: put the files in place

~/.claude/skills/r-cran-extrachecks/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/r-cran-extrachecks/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about r-cran-extrachecks

How do I install r-cran-extrachecks in Claude Code?

Run npx skills add posit-dev/skills --skill r-cran-extrachecks -a claude-code. The skill file is at ~/.claude/skills/r-cran-extrachecks/SKILL.md.

What does r-cran-extrachecks do?

It checks R packages for CRAN requirements that devtools::check() does not catch, including documentation, DESCRIPTION fields, and links. It proposes changes and waits for approval before applying them.

Which documentation rules does the skill check?

Exported functions with an .Rd file are checked for @return and, when they return a meaningful value, @examples. S3 methods with roxygen blocks containing only @export or @exportS3Method are exempt.

Source text

SKILL.md · MIT
---
name: r-cran-extrachecks
description: >
  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.
metadata:
  author: Garrick Aden-Buie (@gadenbuie)
  version: "1.1"
license: MIT
---

# 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

1. **Initial Assessment**: Ask user if this is first submission or resubmission
2. **Run Standard Checklist**: Work through each item systematically (see below)
3. **Identify Issues**: As you review files, note specific problems
4. **Propose Fixes**: Suggest specific changes for each issue found
5. **Implement Changes**: Make edits only when user approves
6. **Verify**: Confirm all changes are complete

## Standard CRAN Preparation Checklist

Work through these items systematically:

1. **Create NEWS.md**: Run `usethis::use_news_md()` if not already present
2. **Create cran-comments.md**: Run `usethis::use_cran_comments()` if not already present
3. **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
4. **Proofread DESCRIPTION**: Carefully review `Title:` and `Description:` fields (see detailed guidance below)
5. **Check function documentation**: Verify all exported functions have `@return` and `@examples` (see detailed guidance below). Note the exemption for S3 methods documented only with `#' @export`: they produce no `.Rd` file and are not required to have either tag
6. **Verify copyright holder**: Check that `Authors@R:` includes a copyright holder with role `[cph]`
7. **Review bundled file licensing**: Check licensing of any included third-party files
8. **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 None` or similar
- Must be present for every exported function

These rules apply only to functions with an `.Rd` file. Roxygen2 creates an `.Rd` file only when a block contains documentation content (a title or description). A block that contains nothing but `#' @export` adds the function to the `NAMESPACE` without generating an `.Rd` file, so there is nothing for CRAN's documentation checks to inspect. This is the conventional pattern for S3 methods:

```r
#' @export
print.my_class <- function(x, ...) {
  cat("my_class object\n")
  invisible(x)
}
```

Such methods do **not** need `@return` or `@examples`, and `R CMD check` does not flag them as undocumented (registered S3 methods are excluded from the undocumented-objects check).

- The exemption holds only while the block contains *nothing but* `@export` (or `@exportS3Method`). Adding a title, `@param`, `@rdname`, `@describeIn`, or any other documentation makes roxygen2 generate an `.Rd` file, and the function must then satisfy all documentation rules including `@return`.
- Do not confuse these with the S3 *generic* itself (e.g., `my_print <- function(x, ...) UseMethod("my_print")`). A newly exported generic is an ordinary exported function with documentation, so it still needs `@return` and `@examples`.
- Methods sharing a page with their generic via `@rdname` or `@describeIn` follow the same rules as the generic: the combined `.Rd` needs the required tags once, not once per method.

Example:
```r
# 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
- S3 methods with `@export`-only roxygen blocks have no `.Rd` file and need no examples (see above)

**Un-exported Functions with Examples**

If you write roxygen examples for un-exported functions, you must either:

1. Call them with `:::` notation: `pkg:::my_fun()`
2. Use `@noRd` tag to suppress `.Rd` file 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()`) with `if ()` blocks
- Sometimes `interactive()` can be used as the condition
- Lengthy examples (> 5 sec) can use `\donttest{}`

**Never Comment Out Code in Examples**

```r
# 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:

```r
#' @examplesIf rlang::is_installed("dplyr")
#' library(dplyr)
#' my_data %>% my_function()
```

For individual code blocks within examples:
```r
#' @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:
```r
# 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:

```r
# GOOD
Title: Interface to 'Tiingo' Stock Price API
```

**Length 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"

```r
# 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

```r
# 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**

```r
# 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:

```r
# 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:

```r
# 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.

```r
# 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**

```r
# 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.md
```

This occurs when files are in `.Rbuildignore`. Solutions:
1. Remove file from `.Rbuildignore`
2. 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:

```r
# 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:

```r
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:

```r
# 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`:

```markdown
## 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:**
```r
# Before
Title: A Toolkit for the Construction of Modeling Packages for R

# After
Title: Construct Modeling Packages
```

**DESCRIPTION Description:**
```r
# 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:**
```r
# 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 capitalization
- `urlchecker::url_check()` - Find problematic URLs
- `urlchecker::url_update()` - Fix redirecting URLs
- `usethis::use_news_md()` - Create NEWS.md
- `usethis::use_cran_comments()` - Create cran-comments.md
- `devtools::build_readme()` - Re-render README.md from README.Rmd
- `usethis::use_code_of_conduct()` - Add CoC without relative links
- `usethis::use_build_ignore()` - Ignore files in R package build
- `usethis::use_package()` - Add a package dependency to DESCRIPTION
- `usethis::use_tidy_description()` - Tidy up DESCRIPTION formatting

## Final Verification Checklist

Use this checklist to ensure nothing is missed before submission:

### Files and Structure
- [ ] `NEWS.md` exists and documents changes for this version
- [ ] `cran-comments.md` exists 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 case
- [ ] `Title:` has no redundant phrases ("A Toolkit for", "Tools for", "for R")
- [ ] `Title:` quotes all software/package names in single quotes
- [ ] `Title:` is under 65 characters
- [ ] `Description:` does NOT start with "This package", package name, or "Functions for"
- [ ] `Description:` is 3-4 sentences explaining purpose and utility
- [ ] `Description:` quotes software/package/API names (including 'R') but NOT function names
- [ ] `Description:` expands all acronyms on first mention
- [ ] `Description:` uses double quotes only for publication titles
- [ ] `Authors@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 with `.Rd` files have `@return` documentation
- [ ] All documented exported functions with meaningful returns have `@examples`
- [ ] S3 methods with `@export`-only roxygen blocks are correctly exempt (no `.Rd` file, no `@return`/`@examples` needed)
- [ ] S3 generics added by the package have full documentation (`@return`, `@examples`) since they are ordinary exported functions
- [ ] No example sections use commented-out code
- [ ] Examples avoid `\dontrun{}` unless truly necessary
- [ ] Examples requiring suggested packages use `@examplesIf` or `if` guards
- [ ] 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 `.Rbuildignore` files

### Optional but Recommended
- [ ] If concerns about method references, added preemptive note to `cran-comments.md`
- [ ] Reviewed bundled file licensing if including third-party files

© Garrick Aden-Buie (@gadenbuie) · MIT · posit-dev/skills

Similar skills

SKILL.md skills catalog →

From the same set30

The whole set →
r-cran-status r-cran-status is a Claude Code skill that checks an R package’s CRAN review status and R CMD check results across platforms. CX Codex +1 227installs r-testthat The r-testthat Claude Code skill guides test writing and organization for R packages using testthat version 3 or later. The agent loads it for new tests or revisions to existing ones. CX Codex +1 182installs r-tidyverse-style r-tidyverse-style — a skill for Claude Code enforces tidyverse conventions during R code reviews and package development. Activates when standardizing syntax or writing new functions. CX Codex +1 177installs r-cli r-cli — a skill for Claude Code guides command-line interface styling in R packages using the cli library. Runs during migration from base R messaging, error formatting, or progress bar setup. CX Codex +1 151installs r-lifecycle r-lifecycle — a skill for Claude Code that guides function and argument deprecation in R packages. It enforces tidyverse lifecycle standards and formats roxygen2 documentation. CX Codex +1 149installs r-mirai The r-mirai Claude Code skill helps write R code for asynchronous and parallel work with mirai. It activates for worker setup, mirai_map tasks, and migrations from future or parallel. CX Codex +1 148installs shiny-r-optimize shiny-r-optimize is a Claude Code skill that diagnoses slow Shiny for R apps and applies targeted performance fixes. It handles hangs, excess recomputation, timeouts, and rising user load. CX Codex +1 123installs shiny-py-optimize The shiny-py-optimize Claude Code skill diagnoses slow Shiny for Python apps and suggests fixes. It activates for sluggish startup, stalled interactions, or excessive recomputation. CX Codex +1 116installs

Project sponsors

Companies that keep this analytics open