AGENTS.md

This file provides guidance to coding agents (e.g., Posit Assistant, Claude Code, Codex, Cursor) when working with code in this repository.

What This Repository Is

A collection of Agent Skills published by Posit PBC. Skills are structured markdown files, following the Agent Skills specification, that teach coding agents specialized workflows (e.g., Shiny app development, R package testing, GitHub PR workflows). There is no application code to build, compile, or deploy — the primary artifacts are Markdown files consumed directly by coding agents that support the Agent Skills format.

Utility Scripts

Two runnable utilities live at the repo root.

count-skill-tokens.py reports line and token counts for a skill:

# Requires uv
./count-skill-tokens.py shiny/shiny-bslib
# or
uv run count-skill-tokens.py r-lib/r-cli

Warns when SKILL.md exceeds 5,000 tokens / 500 lines, or when the skill description frontmatter exceeds 100 tokens.

find-stale-references.py finds references to old skill names after a rename, so stale mentions don't linger in the repo or in users' projects:

# Check the default r-lib r-* prefix renames
./find-stale-references.py [paths...]

# High-confidence path references only (e.g. "r-lib/cli/SKILL.md")
./find-stale-references.py --kinds path

# Check a custom rename
./find-stale-references.py --rename old-name=new-name ~/my-project

Bare name mentions are also reported but need review: the old name may refer to an R package (cli), a website (cli.r-lib.org), or an ordinary word (lifecycle) rather than the skill. Exits non-zero when matches are found, so it can gate CI.

Directory Structure

<category>/
  README.md                   # Category-level notes (optional per skill)
  <skill-name>/
    SKILL.md                  # Required: skill definition with YAML frontmatter
    references/               # Optional: supplementary docs loaded on demand
      *.md
    scripts/                  # Optional: R or shell helpers
    templates/                # Optional: document templates

Do not create a README.md inside individual skill directories — documentation about a skill's design goes in the category README.

SKILL.md Format

Every skill requires YAML frontmatter at minimum:

---
name: your-skill-name        # kebab-case, matches directory name
description: >               # The agent reads this to decide when to activate the skill
  Clear description of what this skill does and when to trigger it.
  Keep under 100 tokens.
---

The body is instructions written for the agent, not end users — imperative, step-by-step, covering edge cases.

Registering a New Skill

After creating the skill directory, add it to the appropriate plugin in .claude-plugin/marketplace.json:

{
  "name": "open-source",
  "skills": [
    "./open-source/release-post",
    "./open-source/your-new-skill"   ← add here
  ]
}

If a skill spans multiple categories (like brand-yml for both Shiny and Quarto), add its path to multiple plugin skills arrays. The source field is always "./" (repo root).

When adding a new plugin to marketplace.json, also update the root README.md "Method 2: Direct Installation" section so it lists the /plugin install command for every plugin. All plugins in marketplace.json must have a corresponding install line in the README.

Skill Categories

Key Conventions

• Progressive disclosure: Put specialized or large reference content in references/*.md and instruct the agent to read those files only when needed. This keeps the main SKILL.md within token limits.
• Harness assumptions: If a skill assumes a specific coding harness or tools, say so in the compatibility frontmatter field and in the skill's README description. Where possible, prefer harness-agnostic instructions or separate harness-specific reference files (see posit-dev/implement/references/).
• R scripts: Use a shebang (#!/usr/bin/env Rscript), include inline usage docs, check for required packages at startup, and exit non-zero on error.
• Testing: Install locally via cp -r <category>/<skill> ~/.agents/skills/ (or ~/.posit/assistant/skills/ for Posit Assistant) and verify your coding harness activates the skill.