Contributing Skills

Contributing Skills

Resources

Official Anthropic documentation (always check these first):

• Claude Code Plugins
• Agent Skills
• Best Practices
• Skill Authoring Best Practices — progressive disclosure, degrees of freedom, workflow checklists
• The Complete Guide to Building Skills (text) — evaluation-driven development, iterative testing

Reference skills - learn by example at different complexity levels:

When in doubt, copy one of these and adapt it.

Deep dives on skill authoring:

• Claude Skills Deep Dive - Comprehensive analysis of skill architecture

Example plugins worth studying:

• superpowers - Advanced workflow patterns, TDD enforcement, multi-skill orchestration
• compound-engineering-plugin - Production plugin structure
• getsentry/skills — Production Sentry skills; security-review is a standout routing + progressive disclosure example

For Claude: Use the claude-code-guide subagent for plugin/skill questions - it has access to official documentation.

Technical Reference

Plugin Structure

plugins/
  <plugin-name>/
    .claude-plugin/
      plugin.json         # Plugin metadata (name, version, description, author)
    commands/             # Optional: slash commands
    agents/               # Optional: autonomous agents
    skills/               # Optional: knowledge/guidance
      <skill-name>/
        SKILL.md          # Entry point with frontmatter
        references/       # Optional: detailed docs
        workflows/        # Optional: step-by-step guides
        scripts/          # Optional: utility scripts
    hooks/                # Optional: event hooks
    README.md             # Plugin documentation

Important: Component directories (skills/, commands/, agents/, hooks/) must be at the plugin root, NOT inside .claude-plugin/. Only plugin.json belongs in .claude-plugin/.

Frontmatter

---
name: skill-name              # kebab-case, max 64 chars
description: "Third-person description of what it does and when to use it"
allowed-tools:                # Optional: restrict to needed tools only
  - Read
  - Grep
---

Naming Conventions

• kebab-case: constant-time-analysis, not constantTimeAnalysis
• Gerund form preferred: analyzing-contracts, processing-pdfs (not contract-analyzer, pdf-processor)
• Avoid vague names: helper, utils, tools, misc
• Avoid reserved words: anthropic, claude

Path Handling

• Use {baseDir} for paths, never hardcode absolute paths
• Use forward slashes (/) even on Windows

Python Scripts

When skills include Python scripts with dependencies:

1. Use PEP 723 inline metadata - Declare dependencies in the script header:

   # /// script
   # requires-python = ">=3.11"
   # dependencies = ["requests>=2.28", "pydantic>=2.0"]
   # ///
   

2. Use uv run - Enables automatic dependency resolution:

   uv run {baseDir}/scripts/process.py input.pdf
   

3. Include pyproject.toml - Keep in scripts/ for development tooling (ruff, etc.)

4. Document system dependencies - List non-Python deps (poppler, tesseract) in workflows with platform-specific install commands

Hooks

PreToolUse hooks run on every Bash command—performance is critical:

• Prefer shell + jq over Python—interpreter startup (Python + tree-sitter) adds noticeable latency
• Fast-fail early - exit 0 immediately for non-matching commands so most invocations are instant
• Favor regex over AST parsing - accept rare false positives if performance gain is significant and Claude can rephrase
• Anticipate false positive patterns - diagnostic commands (which python), search tools (grep python), and filenames (cat python.txt) shouldn't trigger interception
• Document tradeoffs in PR descriptions so reviewers understand deliberate design choices

Quality Standards

These are Trail of Bits house standards on top of Anthropic's requirements.

Description Quality

Your skill competes with 100+ others. The description must trigger correctly.

• Third-person voice: "Analyzes X" not "I help with X"
• Include triggers: "Use when auditing Solidity" not just "Smart contract tool"
• Be specific: "Detects reentrancy vulnerabilities" not "Helps with security"

Value-Add

Skills should provide guidance Claude doesn't already have, not duplicate reference material.

• Behavioral guidance over reference dumps - Don't paste entire specs; teach when and how to look things up
• Explain WHY, not just WHAT - Include trade-offs, decision criteria, judgment calls
• Document anti-patterns WITH explanations - Say why something is wrong, not just that it's wrong

Example: The DWARF skill doesn't include the full DWARF spec. It teaches Claude how to use dwarfdump, readelf, and pyelftools to look up what it needs, plus judgment about when each tool is appropriate.

Scope Boundaries

Prescriptiveness should match task risk:

• Strict for fragile tasks - Security audits, crypto implementations, compliance checks need rigid step-by-step enforcement
• Flexible for variable tasks - Code exploration, documentation, refactoring can offer options and judgment calls

Required Sections

Every SKILL.md must include:

## When to Use
[Specific scenarios where this skill applies]

## When NOT to Use
[Scenarios where another approach is better]

Security Skills

For audit/security skills, also include:

## Rationalizations to Reject
[Common shortcuts or rationalizations that lead to missed findings]

Content Organization

• Keep SKILL.md under 500 lines - split into references/, workflows/
• Use progressive disclosure - quick start first, details in linked files
• One level deep - SKILL.md links to files, files don't chain to more files

Note: Directory depth is fine (references/guides/topic.md). Reference chains are not (SKILL.md → file1.md → file2.md where file1 references file2). The problem is chained references, not nested folders.

Progressive Disclosure Pattern

## Quick Start
[Core instructions here]

## Advanced Usage
See [ADVANCED.md](references/ADVANCED.md) for detailed patterns.

## API Reference
See [API.md](references/API.md) for complete method documentation.

PR Checklist

Before submitting:

Technical (CI validates these):

• Valid YAML frontmatter with name and description
• Name is kebab-case, ≤64 characters
• All referenced files exist
• No hardcoded paths (/Users/..., /home/...)

Quality (reviewers check these):

• Description triggers correctly (third-person, specific)
• "When to use" and "When NOT to use" sections present
• Examples are concrete (input → output)
• Explains WHY, not just WHAT

Documentation:

• Plugin has README.md
• Added to root README.md table
• Registered in root .claude-plugin/marketplace.json (repo-level, not the plugin's own .claude-plugin/)
• Added to CODEOWNERS with plugin-specific ownership (/plugins/<name>/ @gh-username @dguido)
  • To find the GitHub username: run gh api user --jq .login (most reliable — uses authenticated GitHub identity)

Version updates (for existing plugins):

• Increment version in both plugins/<name>/.claude-plugin/plugin.json and the root .claude-plugin/marketplace.json when making substantive changes (clients only update plugins when the version number increases)
• Ensure version numbers match between the plugin's plugin.json and its entry in the root .claude-plugin/marketplace.json