AGENTS.md · posit-dev/skills

Sections

1. What This Repository Is
2. Utility Scripts
3. Directory Structure
4. SKILL.md Format
5. Registering a New Skill
6. Skill Categories
7. Key Conventions

First lines (shown under the repo's MIT license)

# 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](https://agentskills.io), 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:

```bash
# 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:

```bash
# 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:

```yaml
---
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`:

```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

| Category | Purpose |
|----------|---------|
| `posit-dev/` | General developer skills (code review, architecture docs) |
| `github/` | PR creation and review thread workflows |
| `open-source/` | R/Python package release and changelog workflows |
| `r-lib/` | R package development with the r-lib ecosystem |
| `shiny/` | Shiny app development |
| `quarto/` | Quarto document authoring |
| `connect/` | Deploying and managing content on Posit Connect |
| `brand-yml/` | Shared skill registered under both `shiny` and `quarto` plugins |

## 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.