Skill authoring standards

A skill is a reusable Claude Code playbook — a methodology, a prompt pattern, or a step-by-step approach Claude follows when triggered. Skills can ship two ways: standalone at the repo root (skills/<slug>/SKILL.md) or bundled inside a plugin (plugins/<plugin>/skills/<slug>/SKILL.md). Both surface in the same /skills/browse/ catalog with a source label on each card.

This page is two layers: Anthropic’s official guidance, then the RBA tailoring on top.

Anthropic’s best practices

Source: Claude Code — Skills and Agent Skills.

A skill is a directory containing a SKILL.md file plus any supporting files. Anthropic’s core guidance:

Progressive disclosure is the whole design

Claude does not read the full skill up front. It loads in three stages:

1. Always loaded: the name and description from the frontmatter. This is all Claude sees when deciding whether to use the skill.
2. Loaded when triggered: the SKILL.md body.
3. Loaded on demand: supporting files (reference.md, examples.md, scripts, templates) — only when the body tells Claude to read them.

Design for this. Keep SKILL.md focused on the procedure; push large references, schemas, and worked examples into sibling files and point to them by relative path. A skill that inlines everything defeats progressive disclosure and wastes context.

The description is the single most important field

description is what Claude uses to decide when to invoke the skill. Anthropic’s guidance: make it specific, write it in the third person, and state both what the skill does and when to use it, including the words a user would actually say. “Audits a page for WCAG 2.1 AA compliance and produces a ranked remediation plan; use when reviewing accessibility before launch” beats “accessibility helper.”

Frontmatter

---
name: <skill-name>          # required — lowercase letters, numbers, hyphens; max 64 chars
description: <one sentence> # required — what it does AND when to use it
allowed-tools: Read, Grep  # optional — restricts the skill to these tools
---

name and description are the only required fields. allowed-tools is optional but recommended — when present it restricts the skill to exactly those tools.

Other Anthropic recommendations

• One skill, one capability. Don’t build a Swiss-army skill; compose focused skills instead.
• Name with the capability, lowercase-hyphenated, matching the directory name.
• Keep SKILL.md lean. Anthropic recommends moving depth into supporting files rather than growing the body.
• A skill may include executable scripts and resources in its directory; reference them from the body.

How RBA tailors this

On top of Anthropic’s baseline, RBA adds the rules that keep the catalog coherent and the marketplace installable.

Required structure

skills/<skill-name>/                              # standalone
└── SKILL.md

plugins/<plugin>/skills/<skill-name>/             # plugin-bundled
├── SKILL.md          # required — the skill itself
├── examples.md       # optional — concrete worked examples
├── reference.md      # optional — specs, schemas, lookup tables
└── templates.md      # optional — skeleton structures Claude fills in

Frontmatter — RBA additions

---
name: <skill-name>                   # required — must match the folder name (RBA: slug = name)
description: <one sentence>           # required — Anthropic's rules apply
primitive: true                       # optional — set only when this is a cross-cutting foundation primitive
argument-hint: "<placeholder>"       # recommended — guides /<skill> invocation
allowed-tools: Read, Grep, Bash(git log *)  # RBA: least-privilege, never bare Bash
platforms: []                        # optional — facet override (array of strings)
disciplines: []                      # optional
lifecycle: []                        # optional
tags: []                             # optional
outcomes: []                         # optional — deliverable-shaped tags (seo, performance, accessibility-audit)
---

• Slug = name = folder. RBA enforces what Anthropic recommends: the directory name, the name field, and the body title all refer to the same kebab-case slug.
• primitive: true is a single optional flag for cross-cutting primitives every workflow leans on (research, branding, document templates). Most skills don’t need this. Plugin-bundled skills inherit it from the plugin’s rba-meta.json and must not redeclare it.
• Facet fields (platforms, disciplines, lifecycle, tags, outcomes) feed catalog filters; each must be an array of strings if declared.

Standalone vs. plugin-bundled

Pick standalone when the skill is self-contained, a one-shot contribution, and you don’t want to author a full plugin.json + rba-meta.json + README.md to ship one prompt.

Pick a plugin bundle when the skill ships alongside related artifacts, needs to be installable via claude plugin install (only bundles flow through the marketplace), or the author wants to version a coherent set together.

Both paths land in the same /skills/browse/ catalog, so discoverability is identical.

Tool allowlist — RBA tightens least-privilege

Anthropic recommends restricting tools. RBA makes it a hard gate: never bare Bash; use Bash(specific-command *) patterns. Prefer domain-scoped WebFetch(domain:example.com) over bare WebFetch.

Skill type	Typical tools
Research / read-only analysis	Read, Grep, Glob, WebSearch, WebFetch(domain:...)
Codebase scaffolding	Read, Write, Edit, Grep, Glob
Audit with shell	Above + Bash(specific-command *)
File mutation	Above + Write, Edit

Persona requirement (RBA convention)

Anthropic doesn’t mandate a persona; RBA does, because it sharpens output. The persona at the top of the SKILL.md body must be:

• Domain-specific, not generic — “senior CMS architect,” not “helpful assistant”
• Opinionated, not neutral — opinions sharpen the output
• Realistic — an experienced practitioner, not “world’s leading expert”

Validator-enforced

• SKILL.md is under 500 lines — the RBA expression of Anthropic’s “keep it lean” guidance. Depth moves to sibling files.
• Folder name matches frontmatter name.
• No bare Bash; least-privilege allowed-tools.
• Plugin-bundled skills do not redeclare primitive (it inherits from the plugin’s rba-meta.json).

Quality checklist

A skill is ready to ship when:

1. The description states both what it does and when to use it (Anthropic).
2. Heavy detail lives in supporting files, not the body (Anthropic — progressive disclosure).
3. Frontmatter has name and description; standalone skills may set optional facets (platforms, disciplines, outcomes, etc.) or primitive: true when applicable (RBA).
4. Folder, frontmatter name, and title all match the slug (RBA).
5. The persona is domain-specific (RBA).
6. Every methodology phase explains both the what and the why.
7. The output format is an explicit template, not vague guidance.
8. allowed-tools is least-privilege with no bare Bash (RBA).
9. SKILL.md is under 500 lines (RBA validator).
10. The skill produces useful output when run on a realistic input.

Anti-patterns

• A vague description that won’t trigger the skill at the right time (defeats Anthropic’s discovery model)
• Inlining references/examples that belong in supporting files (defeats progressive disclosure)
• Generic “helpful assistant” persona
• Methodology that lists steps without explaining why each matters
• Open-ended output (“provide your analysis”) instead of explicit templates
• Tool allowlist of * or unrestricted Bash
• A skill that duplicates an existing skill rather than composing with it