# Cran Audit

> This skill should be used when the user asks to \"audit for CRAN\", \"check CRAN readiness\", \"prepare for CRAN submission\", \"CRAN check\", \"is my package CRAN ready\", \"submit to CRAN\", or mentions CRAN submission compliance. It audits an R package against CRAN Repository Policy and submission requirements, producing a structured gap report with actionable fixes. Use when this capability is needed.

- Skill: `tomevault-io/cran-audit` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/cran-audit`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/cran-audit/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/cran-audit

---


# CRAN Submission Audit

Audit an R package against CRAN Repository Policy requirements and produce a structured gap report. This skill evaluates package structure, DESCRIPTION metadata, documentation, code quality, and test coverage against the full CRAN checklist.

## Workflow

### 1. Locate the Package

Identify the R package to audit. Look for `DESCRIPTION` file in the current working directory or a specified path. If no R package is found, ask the user which package to audit.

### 1b. Load User Config

Read `.claude/pub-pipeline.local.md` if it exists (Read tool). Extract author metadata and package context from YAML frontmatter. If the file is missing, inform the user and offer to create one from the template at `${CLAUDE_PLUGIN_ROOT}/docs/user-config-template.md`.

### 2. Gather Package State

Run these checks in parallel where possible:

**Package metadata** (Read tool):
- Read `DESCRIPTION` — check all required fields
- Read `NAMESPACE` — verify auto-generation by roxygen2
- Read `LICENSE` or `LICENSE.md` — verify OSI-approved license
- Check for `NEWS.md`, `cran-comments.md`, `README.md`

**Code quality** (Grep/Glob tools):
- Search for `q()` calls in R code
- Search for `.Internal()`, `:::` accessing base internals
- Search for writes outside `tempdir()` / `tools::R_user_dir()`
- Check that Suggested packages are used conditionally (`if (requireNamespace(...))`)
- Verify no binary executables in source
- Search for `options()` or `par()` calls that don't restore state via `on.exit()` or `withr`
- Run `urlchecker::url_check()` to verify all URLs are valid and HTTPS

**Documentation** (Grep/Glob tools):
- Check all exported functions have `@returns` roxygen tag
- Check all exported functions have `@examples` roxygen tag
- Verify `man/` directory exists with `.Rd` files

**R CMD check** (Bash tool):
```bash
cd /path/to/package && Rscript -e 'devtools::check(args = "--as-cran")'
```

**Test coverage** (Bash tool):
```bash
cd /path/to/package && Rscript -e 'covr::package_coverage()'
```

### 3. Evaluate Against Checklist

Score each item from the CRAN checklist as PASS, FAIL, or WARN. Consult the full checklist in `${CLAUDE_PLUGIN_ROOT}/docs/cran-reference.md` for detailed requirements.

Key categories to evaluate:

| Category | Key Checks |
|----------|-----------|
| **DESCRIPTION** | Title case, no period, informative Description, Authors@R with roles, valid License |
| **Dependencies** | Imports from CRAN/Bioconductor only, conditional Suggests usage |
| **Code behavior** | No q(), no .Internal, no writing outside tempdir, no global env modification |
| **Documentation** | All exports have @returns and @examples, vignettes build |
| **Examples** | `\dontrun{}` only for truly non-runnable code; prefer `\donttest{}` for slow examples |
| **Side effects** | `options()`/`par()` restored via `on.exit()` or `withr`; no persistent state changes |
| **Size** | Tarball <10MB, data+docs <5MB, examples run in seconds |
| **Cross-platform** | Portable code, no OS-specific assumptions |
| **Testing** | R CMD check clean (0E/0W), notes explained |
| **URLs** | All URLs valid and using HTTPS |

### 4. Produce Gap Report

Format the report as:

```markdown
# CRAN Audit Report: {package name} v{version}

## Summary
- **Status**: READY / NEEDS WORK / NOT READY
- **Score**: X/Y checks passed
- **Blockers**: N critical issues

## Critical (Must Fix)
1. [Issue description] — [file:line] — [how to fix]

## Warnings (Should Fix)
1. [Issue description] — [file:line] — [recommendation]

## Passed
- [Check name] ✓

## R CMD Check Results
[Paste relevant output]

## Recommended Next Steps
1. [Ordered list of actions]
```

### 5. Offer to Fix

After presenting the report, offer to fix issues that can be automated:
- Add missing `@returns` tags
- Add `cran-comments.md` if missing
- Fix Title/Description formatting
- Add conditional `requireNamespace()` checks
- Create `NEWS.md` if missing
- Replace `\dontrun{}` with `\donttest{}` where appropriate

## Reference Files

For the complete CRAN policy checklist and submission workflow, consult:
- **`${CLAUDE_PLUGIN_ROOT}/docs/cran-reference.md`** — Full CRAN Repository Policy reference with pre-submission checklist, submission workflow, and common rejection reasons

## Important Notes

- NAMESPACE is auto-generated by roxygen2 — never edit manually. Run `devtools::document()` after any roxygen changes.
- `R CMD check --as-cran` is the gold standard. If it passes with 0E/0W/0N, the package is very likely to be accepted.
- First-time submissions face heightened scrutiny. The Description field is especially important.
- CRAN reviewers are volunteers. Respect their time by fixing all automated issues before submission.

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/queelius) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-14 -->