Getting Started

Learn how to start contributing skills to the Trail of Bits Skills Marketplace

Welcome

We welcome contributions to the Trail of Bits Skills Marketplace! This guide will help you get started with creating your first skill or plugin.

Prerequisites

Before you begin, make sure you have:

• Familiarity with Claude Code and how skills work
• Basic understanding of YAML frontmatter
• Git and GitHub account for submitting PRs

Quick Start

1. Choose a complexity level

   Start by choosing a reference skill that matches your target complexity:

   Complexity	Reference Skill	What It Demonstrates
   Basic	ask-questions-if-underspecified	Minimal frontmatter, simple guidance
   Intermediate	constant-time-analysis	Python package, references/, language-specific docs
   Advanced	culture-index	Scripts, workflows/, templates/, PDF extraction, multiple entry points

   When in doubt, copy one of these reference skills and adapt it to your needs.

2. Set up your plugin structure

   Create the basic directory structure for your plugin:

   plugins/
     your-plugin-name/
       .claude-plugin/
         plugin.json
       skills/
         your-skill-name/
           SKILL.md
       README.md
   

   See Plugin Structure for detailed requirements.

3. Write your SKILL.md

   Every skill needs a SKILL.md file with proper frontmatter. See Skill Authoring for detailed guidance.

   ---
   name: your-skill-name
   description: "Third-person description of what it does and when to use it"
   ---
   
4. Test your skill

   Install your plugin locally for testing:

   # Navigate to parent directory of the skills repo
   cd /path/to/parent
   /plugins marketplace add ./skills
   

   Then use /plugin menu in Claude Code to install and test your plugin.

5. Submit a pull request

   Once your skill is working, submit a PR! See the PR Checklist below.

Official Resources

Before creating a skill, review these official Anthropic resources:

• Claude Code Plugins - Plugin system documentation
• Agent Skills - How skills work
• Best Practices - General best practices
• Skill Authoring Best Practices - Progressive disclosure, degrees of freedom, workflow checklists
• The Complete Guide to Building Skills - Evaluation-driven development, iterative testing

Example Plugins to Study

Learn from production-quality plugins:

• 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

Deep Dives

For comprehensive skill authoring guidance:

• Claude Skills Deep Dive - Comprehensive analysis of skill architecture

PR Checklist

Before submitting your pull request, ensure you’ve completed these items:

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

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
• Ensure version numbers match between the plugin’s plugin.json and its entry in the root .claude-plugin/marketplace.json

Getting Help

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

If you have questions or need help:

1. Review the official Anthropic documentation
2. Study the reference examples
3. Check existing plugins in the repository
4. Ask in the GitHub Discussions or open an issue

Next Steps

Skill Authoring

Learn how to write effective skills

Plugin Structure

Understand the required directory structure

Best Practices

Follow Trail of Bits quality standards

Examples

See real-world skill examples