golem Framework Documentation

The golem-agent-skills plugin provides shared {golem} skills specifically packaged for Claude Code and OpenAI agents. It is designed to assist in professional Shiny development by enforcing R package best practices and golem conventions.

Available Skills

• Golem App Builder: Build and evolve golem applications using routed references.
• Golem Upgrade: Upgrade golem apps across package and structure changes.
• Golem Fix Missing ns: Check modules for missing ns() calls.

Requirements

• R 4.0+
• {golem} package
• {devtools} package
• {shiny} package

Tests should be placed in the tests/testthat/ directory. To maintain a clear mapping to your application logic, follow these conventions:

• File Naming: Test files should mirror your R/ files using the pattern test-<filename>.R.
• Test Blocks: Wrap test logic in test_that("description", { ... }) blocks.
• Independence: Each test must be hermetic and independent, meaning they should pass in any order and in isolation.

Decide where to place your code based on the function's role:

Factory Functions (R/fct_*.R)

• Purpose: Contain reusable business logic (e.g., data processing, calculations, validations).
• Requirement: Must be testable in isolation, outside of the Shiny context.
• Creation: Use golem::add_fct().

Utility Functions (R/utils_*.R or R/mod_<name>_utils_<fn>.R)

• Purpose: General-purpose helpers that are reusable across modules.
• Module-specific utilities: If a utility is specific to a module, place it in R/mod_<name>_utils_<fn>.R.
• Creation: Use golem::add_utils().

When working with golem, adhere to these core principles:

• R Package Conventions: A golem app is an R package; always follow standard R package development rules.
• Namespace Management: Never edit the NAMESPACE file manually. Always use devtools::document() to manage exports and imports.
• Development Environment: After making any non-trivial changes to the application, it is recommended to run golem::run_dev() to refresh the development environment.

# To update NAMESPACE
devtools::document()

# To refresh the development environment after changes
golem::run_dev()

Tests in a golem application should follow these structural conventions:

• Location: All tests reside in the tests/testthat/ directory.
• Naming: Test files should mirror your R/ files using the pattern test-<filename>.R.
• Blocks: Wrap test logic in test_that("description", { ... }) blocks.
• Independence: Each test must be hermetic, meaning it should pass in isolation and in any order. Avoid relying on global state or top-level code outside of test_that() blocks.

To maintain a stable and performant Shiny application, follow these reactive programming rules:

• Module Boundaries: Do not pass reactive() objects between modules unless explicitly required.
• UI Updates: Avoid the pattern of renderUI() combined with uiOutput(). Instead, prefer using update*() functions (e.g., updateSelectInput()) to modify existing inputs.
• Reactive Cycles: Watch for cycles where A updates B, which in turn updates A. Break these cycles using explicit conditions.
• Data Sharing: If you must share data between modules, use a reactiveValues() object, but only include the minimum necessary data to prevent unnecessary reactivity.

A golem module is composed of two primary functions following a specific naming pattern based on the module name:

1. mod_<name>_ui(): The function responsible for the User Interface.
2. mod_<name>_server(): The function responsible for the Server logic.

When building the UI, you must always use ns <- NS(id) to namespace UI elements and ensure all input/output IDs are prefixed with ns.

When testing golem applications, follow these strategies for reactive logic:

1. Decouple Logic: Whenever possible, extract and test business logic outside of the Shiny context.
2. Use testServer(): For testing Shiny modules and reactive dependencies, use the testServer() function.
3. Mocking: Use mocking to replace external dependencies (like APIs or databases) to keep tests predictable and fast.

A Golem application is structured as an R package. Adhere to these structural and workflow rules:

• Folder Structure: Keep the R/ folder flat (no subfolders). Place development scripts in dev/ and data creation scripts in data-raw/.
• Namespace Management: Never edit the NAMESPACE file manually.
• Documentation: Always run devtools::document() after making changes to Roxygen comments.
• Build Exclusions: Use usethis::use_build_ignore() for files that do not belong in the standard package structure.
• Style: Follow the tidyverse style guide.

A golem application is structured as an R package. To maintain a healthy project structure, adhere to these rules:

• Folder Structure: Keep the R/ folder flat (no subfolders).
• Development & Data: Place development scripts in the dev/ folder and data creation scripts in the data-raw/ folder.
• Namespace Management: Never edit the NAMESPACE file manually. Always use devtools::document() after making changes to Roxygen documentation to update it.
• File Management: Use usethis::use_build_ignore() for files that do not belong in the standard package structure.
• Style: Follow the tidyverse style guide.

To remove the plugin and its marketplace source from Claude Code, run the following commands:

1. Uninstall the plugin: /plugin uninstall golem-skills
2. Remove the marketplace: /plugin marketplace remove thinkr
3. Reload plugins: /reload-plugins