r-package-dev-skill

This is a rigorous development workflow for statistical and numerical R packages (the kind that implement an estimator, a model, or an algorithm against a documented methodology), packaged as a skill for coding agents.

The idea is that given a reasonably well-defined issue for an R package, an AI agent using this skill can produce a pull request solving the issue ready for your review.

The cycle

clarify scope  →  ExecPlan  →  plan review + sentinel  →  implement
              →  CRAN gate  →  post-exec review + sentinel
              →  disposition sweep  →  PR to main

The cycle combines subagents, review before and after implementation, and a check for compatibility with CRAN requirements.

What you need first

Check these before you start:

• A coding-agent harness with subagents. The skill assumes subagents are available for reviewing. A harness without subagents can still run this manually (see harness-notes.md).
• R, plus devtools, testthat, urlchecker, and spelling packages. Install the packages with install.packages(c("devtools", "urlchecker", "spelling")) (or ask your agent to do it when you load the skill).
• A formatter, or a deliberate none. The profile records whether the package uses air (preferred), styler, or none.
• gh, authenticated, against a GitHub remote. PR creation, CI status, and the disposition sweep's "file an issue" path all shell out to gh.
• Optional: a UserPromptSubmit hook. It works around a Claude Code bug that silently suppresses subagents. The cost is hand-editing ~/.claude/settings.json and running a script on every prompt in every repo (see harness-notes.md).

If you're installing somewhere other than Claude Code, set AGENT_SKILLS_DIR (by default ~/.claude/skills) to wherever your harness looks for skills.

Install

You can do the below yourself or just ask your coding agent to do it.

git clone https://github.com/gregfaletto/r-package-dev-skill.git
cd r-package-dev-skill
bash scripts/install.sh          # symlinks it where your agent looks for skills

SKILL.md is the entry point and router, and everything substantive is in references/. The workflow requires subagents, but beyond that it's plain markdown; see references/harness-notes.md for how it maps onto a specific agent harness.

Then, from the root of any R package repo that doesn't have one yet:

bash "${AGENT_SKILLS_DIR:-$HOME/.claude/skills}/r-package-dev/scripts/bootstrap-repo.sh"

That scaffolds .workflow/ and .plans/, copies in the profile template (more on profiles below), and adds the gitignore entries, plus the matching .Rbuildignore regexes when a DESCRIPTION is present.

Getting Started

If your package isn't already CRAN-ready, expect your first cycle to be cleanup so that it can be up to CRAN-ready standards after each pull request going forward. USAGE.md explains what that involves. The skill also needs basic information about your package, called a profile. Direct your coding agent to follow references/adoption.md to derive the profile for your package field by field.

USAGE.md covers full details on what a session looks like, what you'll be asked for, how to steer it faster or slower, which output files are worth reading, and what to do when something goes wrong.

Design notes

The skill uses a profile (more details below) that characterizes the package. It consists of build commands, the authority document, the naming and error conventions, the public API, and a handful of gotchas.

Some profile fields switch the process in addition to describing the package. The table in USAGE.md lists which fields these are and what each one switches, and the template marks them [switch] where they're filled in.

Scope

The skill is written for R packages implementing statistical or numerical methodology, usually intended to be published on CRAN (or at least kept up to CRAN-ready standards). Plain devtools packages and literate/generated (litr) packages are both in scope, as are roxygen2, testthat, and each of S3, S4, R6, and S7.

You can also use the skill outside that target, with substitutions. The planning format, the subagents, the review discipline, the git workflow, the object-systems reference, and most of the lesson catalogue transfer unchanged to a non-numerical package, like a web client, a data-wrangling or visualization package, or developer tooling.

Governance models other than a single maintainer who reviews and merges everything are supported but thinly tested. The team and outside-contributor paths are written down, but the workflow was derived from single-maintainer repos. Where a repo's CONTRIBUTING.md or branch protection rules disagree with the skill, they win.

The skill doesn't yet cover Bioconductor (different branch model, BiocCheck, six-month release cycle), non-testthat frameworks, compiled code in src/, or renv and similar project layers. Only the gate and the release model need local adjustment there.

Packages built with litr

litr lets you write an R package as a literate program. The code, tests, and documentation are written together in R Markdown, and knitting the document generates the package. cssr is built this way.

The skill works with litr packages, and guides/litr.md covers what changes for them. The main difference is that the agent edits only the source document, since the package is generated from it. A full build also runs the tests woven into the document, so a green build means they passed. The gate runs on the generated package directory, and the profile records the build command, the gate's flags, and that the version is set in the source document instead of the generated DESCRIPTION.

What's in it

SKILL.md                                the loop, the non-negotiables, scope, routing
AGENTS.md                               same, for harnesses that read a repo-root file
references/
  scope-clarification.md                stage 1 — the questions that scope an issue
  execplan.md                           format, skeleton, criteria, artifact names
  cran-gate.md                          R loop, the gate, CI, formatting, test discipline
  git-and-pr.md                         branching, PR style, stacked-PR traps
  object-systems.md                     S3 / S4 / R6 / S7 — dispatch, export, validators
  adoption.md                           setting up a new package; deriving the profile
  harness-notes.md                      spawning subagents; the absolute-path rule
  lessons.md                            indexed failure modes, with the stories
  subagents/
    plan-reviewer.md                    pre-implementation review
    implementer.md                      delegated implementation
    sentinel.md                         drift checks; its BLOCKED gates the push
    post-exec-reviewer.md               pre-merge review
guides/
  periodic-review.md                    the quarterly codebase sweep — occasional
  litr.md                               only for packages built from a source document
templates/
  PROFILE.md                            the per-repo contract (a form, not anyone's answers)
scripts/
  install.sh                            symlink into your agent's skills dir
  bootstrap-repo.sh                     scaffold a repo
  delegation-standing-request.sh        UserPromptSubmit hook — see harness-notes.md
  check-docs.R                          link and anchor checker for this repo's markdown
  check-briefs.R                        every pointer a brief hands out has to resolve
  check-fields.R                        every field the template defines has to be named
  check-profile.R                       checks a repo's PROFILE.md against the template
USAGE.md                                the human's guide — start here
CONTRIBUTING.md                         editing the skill itself
CONSIDERED.md                           changes considered and set aside

License

MIT; see LICENSE.

references/execplan.md derives its structure from the OpenAI Cookbook's ExecPlans article (MIT, Copyright (c) 2025 OpenAI). See NOTICE for what's derived and what isn't.