Skip to main content
skill CX Codex

r-lifecycle — Claude Code skill: what it does, how to install

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.

MIT 149 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-lifecycle -a claude-code
Open on GitHub

What r-lifecycle does

The skill teaches the agent how to handle function stages using the R lifecycle package. It provides patterns for documentation badges, staged deprecation workflows from deprecate_soft() to deprecate_stop(), and redirecting old function calls to new implementations.

For argument deprecation and renaming, the workflow uses deprecated() default values and lifecycle::is_present() checks. It also structures unit tests using snapshot tests and suppresses deprecation messages with withr::local_options().

Working with these conventions requires the lifecycle and usethis packages in your R project. Without running usethis::use_lifecycle(), the badge SVG assets in man/figures/ will be missing.

What it helps with

  • deprecate R functions using tidyverse conventions
  • add lifecycle stage badges to roxygen2 documentation
  • rename function parameters safely using lifecycle::is_present()
  • test deprecation warnings with testthat snapshot tests

Example prompts for the agent

  • Mark old_plot() as deprecated in favor of new_plot() using lifecycle
  • Set up lifecycle support in this R package with usethis
  • Rename argument file to path with deprecation warnings

How to install r-lifecycle

1Skills CLI (Vercel)

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

2Manually: put the files in place

~/.claude/skills/r-lifecycle/SKILL.md

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

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

Questions about r-lifecycle

How to install r-lifecycle in Claude Code?

Run npx skills add posit-dev/skills --skill r-lifecycle -a claude-code.

What stages does r-lifecycle cover?

It covers experimental, superseded, and deprecated stages, including transitions across deprecate_soft(), deprecate_warn(), and deprecate_stop().

What dependencies are required for r-lifecycle?

You need R installed along with the lifecycle and usethis packages, plus roxygen2 for building package documentation.

Source text

SKILL.md · MIT
---
name: r-lifecycle
description: "Guidance for managing R package lifecycle according to tidyverse principles using the lifecycle package. Use when: (1) Setting up lifecycle infrastructure in a package, (2) Deprecating functions or arguments, (3) Renaming functions or arguments, (4) Superseding functions, (5) Marking functions as experimental, (6) Understanding lifecycle stages (stable, experimental, deprecated, superseded), or (7) Writing deprecation helpers for complex scenarios."
metadata:
  author: Garrick Aden-Buie (@gadenbuie)
  version: "1.1"
license: MIT
---

# R Package Lifecycle Management

Manage function and argument lifecycle using tidyverse conventions and the lifecycle package.

## Setup

Check if lifecycle is configured by looking for `lifecycle-*.svg` files in `man/figures/`.

If not configured, run:

```r
usethis::use_lifecycle()
```

This:

- Adds lifecycle to `Imports` in DESCRIPTION
- Adds `@importFrom lifecycle deprecated` to the package documentation file
- Copies badge SVGs to `man/figures/`

## Lifecycle Badges

Insert badges in roxygen2 documentation:

```r
#' @description
#' `r lifecycle::badge("experimental")`
#' `r lifecycle::badge("deprecated")`
#' `r lifecycle::badge("superseded")`
```

For arguments:

```r
#' @param old_arg `r lifecycle::badge("deprecated")` Use `new_arg` instead.
```

Only badge functions/arguments whose stage differs from the package's overall stage.

## Deprecating a Function

1. Add badge and explanation to `@description`:

```r
#' Do something
#'
#' @description
#' `r lifecycle::badge("deprecated")`
#'
#' `old_fun()` was deprecated in mypkg 1.0.0. Use [new_fun()] instead.
#' @keywords internal
```

2. Add `deprecate_warn()` as first line of function body:

```r
old_fun <- function(x) {

lifecycle::deprecate_warn("1.0.0", "old_fun()", "new_fun()")
new_fun(x)
}
```

3. Show migration in examples:

```r
#' @examples
#' old_fun(x)
#' # ->
#' new_fun(x)
```

## Deprecation Functions

| Function           | When to Use                                             |
| ------------------ | ------------------------------------------------------- |
| `deprecate_soft()` | First stage; warns only direct users and during tests   |
| `deprecate_warn()` | Standard deprecation; warns once per 8 hours            |
| `deprecate_stop()` | Final stage before removal; errors with helpful message |

**Deprecation workflow for major releases:**

1. Search `deprecate_stop()` - consider removing function entirely
2. Replace `deprecate_warn()` with `deprecate_stop()`
3. Replace `deprecate_soft()` with `deprecate_warn()`

## Renaming a Function

Move implementation to new name, call from old name with deprecation:

```r
#' @description
#' `r lifecycle::badge("deprecated")`
#'
#' `add_two()` was renamed to `number_add()` for API consistency.
#' @keywords internal
#' @export
add_two <- function(x, y) {
lifecycle::deprecate_warn("1.0.0", "add_two()", "number_add()")
number_add(x, y)
}

#' Add two numbers
#' @export
number_add <- function(x, y) {
x + y
}
```

## Deprecating an Argument

Use `deprecated()` as default value with `is_present()` check:

```r
#' @param path `r lifecycle::badge("deprecated")` Use `file` instead.
write_file <- function(x, file, path = deprecated()) {
  if (lifecycle::is_present(path)) {
    lifecycle::deprecate_warn("1.4.0", "write_file(path)", "write_file(file)")
    file <- path
  }
  # ... rest of function
}
```

## Renaming an Argument

```r
add_two <- function(x, y, na_rm = TRUE, na.rm = deprecated()) {
  if (lifecycle::is_present(na.rm)) {
    lifecycle::deprecate_warn("1.0.0", "add_two(na.rm)", "add_two(na_rm)")
    na_rm <- na.rm
  }
  sum(x, y, na.rm = na_rm)
}
```

## Superseding a Function

For functions with better alternatives that shouldn't be removed:

```r
#' Gather columns into key-value pairs
#'
#' @description
#' `r lifecycle::badge("superseded")`
#'
#' Development on `gather()` is complete. For new code, use [pivot_longer()].
#'
#' `df %>% gather("key", "value", x, y, z)` is equivalent to
#' `df %>% pivot_longer(c(x, y, z), names_to = "key", values_to = "value")`.
```

No warning needed - just document the preferred alternative.

## Marking as Experimental

```r
#' @description
#' `r lifecycle::badge("experimental")`
cool_function <- function() {
  lifecycle::signal_stage("experimental", "cool_function()")
  # ...
}
```

## Testing Deprecations

Test that deprecated functions work and warn appropriately:

```r
test_that("old_fun is deprecated", {
  expect_snapshot({
    x <- old_fun(1)
    expect_equal(x, expected_value)
  })
})
```

Suppress warnings in existing tests:

```r
test_that("old_fun returns correct value", {
  withr::local_options(lifecycle_verbosity = "quiet")
  expect_equal(old_fun(1), expected_value)
})
```

## Deprecation Helpers

For deprecations affecting many functions (e.g., removing a common argument), create an internal helper:

```r
warn_for_verbose <- function(
  verbose = TRUE,
  env = rlang::caller_env(),
  user_env = rlang::caller_env(2)
) {
  if (!lifecycle::is_present(verbose) || isTRUE(verbose)) {
    return(invisible())
  }

  lifecycle::deprecate_warn(
    when = "2.0.0",
    what = I("The `verbose` argument"),
    details = c(
      "Set `options(mypkg_quiet = TRUE)` to suppress messages.",
      "The `verbose` argument will be removed in a future release."
    ),
    user_env = user_env
  )

  invisible()
}
```

Then use in affected functions:

```r
my_function <- function(..., verbose = deprecated()) {
  warn_for_verbose(verbose)
  # ...
}
```

## Custom Deprecation Messages

For non-standard deprecations, use `I()` to wrap custom text:

```r
lifecycle::deprecate_warn(
  when = "1.0.0",
  what = I('Setting option "pkg.opt" to "foo"'),
  with = I('"pkg.new_opt"')
)
```

The `what` fragment must work with "was deprecated in..." appended.

## Reference

See `references/lifecycle-stages.md` for detailed stage definitions and transitions.

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

Similar skills

All skills for Programming languages →

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-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 r-cran-extrachecks 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. CX Codex +1 144installs 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