Your First Plugin

Your First Plugin

Build a complete Claude Code plugin from scratch, test it locally, and submit it to the marketplace.

---

What Is a Plugin?

A plugin is a directory that extends Claude Code with skills, slash commands, and agents. Most plugins (98%) are pure Markdown -- no external code, no servers. Claude reads the files and follows the instructions they contain.

A plugin contains:

Component	File	Purpose
Manifest	.claude-plugin/plugin.json	Name, version, author, metadata
Skills	skills/[name]/SKILL.md	Auto-activating capabilities
Commands	commands/*.md	Slash commands (/review, /deploy)
Agents	agents/*.md	Specialized AI agents
Docs	README.md + LICENSE	Documentation and license

---

What You Will Build

A code-review-toolkit plugin with two skills and one command:

code-review-toolkit/
├── .claude-plugin/
│   └── plugin.json
├── skills/
│   ├── security-checker/
│   │   └── SKILL.md
│   └── style-analyzer/
│       └── SKILL.md
├── commands/
│   └── review.md
├── README.md
└── LICENSE

---

Step 1: Plan Your Plugin

Answer these questions before writing anything:

• What does it do? Automated code review with security and style checks.
• Who is it for? Developers who want consistent reviews.
• What skills does it need? Security scanning (OWASP Top 10) and style analysis (PEP 8, ESLint).
• What commands? /review to run both checks at once.
• What tools? Read, Grep, Bash(git:*) -- minimum necessary, always scoped.

---

Step 2: Create the Directory Structure

mkdir -p code-review-toolkit/.claude-plugin
mkdir -p code-review-toolkit/skills/security-checker
mkdir -p code-review-toolkit/skills/style-analyzer
mkdir -p code-review-toolkit/commands

---

Step 3: Write plugin.json

Create .claude-plugin/plugin.json with the required fields:

{
  "name": "code-review-toolkit",
  "version": "1.0.0",
  "description": "Automated code review toolkit with security scanning and style analysis",
  "author": {
    "name": "Your Name",
    "email": "you@example.com"
  },
  "license": "MIT",
  "keywords": ["code-review", "security", "style", "quality", "OWASP"],
  "category": "security"
}

Only these fields are allowed in plugin.json: name, version, description, author, repository, homepage, license, keywords. CI rejects anything else.

---

Step 4: Create Skills

security-checker/SKILL.md

---
name: security-checker
description: |
  Scan code for security vulnerabilities based on OWASP Top 10.
  Use when: reviewing code for security issues, pre-commit checks, security audits.
  Triggers: security scan, check vulnerabilities, OWASP review.
allowed-tools: Read, Grep, Bash(git:*)
version: 1.0.0
author: Your Name <you@example.com>
license: MIT
tags: [security, OWASP, vulnerability-scanning]
---

# Security Checker

Analyze source code for common security vulnerabilities based on the OWASP Top 10.

## Overview

Scans files for injection attacks, hardcoded secrets, broken authentication patterns,
and other security anti-patterns across Python, JavaScript, and TypeScript codebases.

## Prerequisites

- Source files must be readable
- Git history available for secret scanning

## Instructions

1. Read target files with the **Read** tool
2. Use **Grep** to scan for dangerous patterns (SQL concatenation, hardcoded keys, eval usage)
3. Check git history for leaked secrets: `Bash(git:log -p --diff-filter=A)`
4. Classify findings by severity: Critical, High, Medium, Low

## Output

Return a structured report with file, line number, severity, and remediation advice.

## Error Handling

- If file not found, suggest correct path
- If git not available, skip history scan and note the limitation

## Examples

User: "Scan src/auth.py for security issues"
1. Reads src/auth.py
2. Finds hardcoded API key on line 12
3. Returns Critical finding with fix suggestion

## Resources

- [OWASP Top 10](https://owasp.org/www-project-top-ten/)
- See `${CLAUDE_SKILL_DIR}/references/implementation.md` for pattern library

style-analyzer/SKILL.md

---
name: style-analyzer
description: |
  Analyze code style against language-specific best practices.
  Use when: code reviews, maintaining consistency, checking style.
  Triggers: check style, analyze style, code quality check.
allowed-tools: Read, Grep
version: 1.0.0
author: Your Name <you@example.com>
license: MIT
tags: [style, linting, code-quality]
---

# Style Analyzer

Check code against language-specific style guides and report violations.

## Overview

Detects style violations for Python (PEP 8), JavaScript (ESLint/Airbnb), and TypeScript.
Checks line length, indentation, naming conventions, import order, and documentation.

## Prerequisites

- Source file must exist and be readable

## Instructions

1. Detect language from file extension
2. Read file with the **Read** tool
3. Use **Grep** to find naming violations and missing docstrings
4. Check line lengths, indentation consistency, and import order
5. Score the file and generate a report

## Output

Return a report with issue counts by category and an overall score out of 10.

## Error Handling

- If language cannot be detected, ask the user to specify
- If file is empty, report that no analysis is possible

## Examples

User: "Check code style in main.py"
1. Detects Python, applies PEP 8 rules
2. Finds 3 line-length violations, 1 naming issue
3. Returns report with score 7/10

## Resources

- [PEP 8](https://peps.python.org/pep-0008/)
- [Airbnb JavaScript Style Guide](https://github.com/airbnb/javascript)

---

Step 5: Create the Slash Command

Create commands/review.md:

---
description: Run comprehensive code review (security + style)
allowed-tools: Read, Grep, Bash(git:*)
---

Perform a comprehensive code review of the specified file or directory.

## Steps

1. Run the `security-checker` skill to scan for vulnerabilities
2. Run the `style-analyzer` skill to check code style
3. Combine results into a single report ordered by severity

Ask the user which file or directory to review.

---

Step 6: Add README and LICENSE

Create a README.md that explains what the plugin does, how to install it, and how to use it. Include sections for each skill and command.

Create a LICENSE file (MIT recommended for marketplace submissions).

---

Step 7: Test Locally

Copy the plugin to your Claude plugins directory:

cp -r code-review-toolkit ~/.claude/plugins/

Restart Claude Code, then test:

1. Slash command: Type /review and verify it appears
2. Security skill: Say "scan this file for security vulnerabilities"
3. Style skill: Say "check code style in main.py"

---

Step 8: Validate

Run the marketplace validator against your plugin:

ccpi validate ./code-review-toolkit

This checks plugin.json structure, skill frontmatter, allowed-tools format, and directory layout.

---

Step 9: Submit to the Marketplace

1. Fork the repository
2. Copy your plugin to plugins/[category]/code-review-toolkit/
3. Add an entry to .claude-plugin/marketplace.extended.json
4. Run pnpm run sync-marketplace
5. Run ./scripts/validate-all-plugins.sh plugins/security/code-review-toolkit/
6. Open a pull request

---

Next Steps

• Plugin Structure -- detailed directory layout reference
• Your First Skill -- deep dive into skill creation
• Contributing -- full submission guidelines
• SKILL.md Specification -- frontmatter and body requirements