repo-add-plugin

name

repo-add-plugin

description

Bootstrap a new plugin with complete directory structure, metadata files, and marketplace integration. Use when: (1) explicitly asked to create a new plugin, (2) starting a new category of skills that doesn't fit existing plugins, (3) forking or extending the marketplace with custom plugins, (4) setting up development environment for new skill categories, (5) creating specialized plugin for specific domain (data science, security, etc.)

Repo Add Plugin

Create a new plugin from scratch with all required files, proper schema compliance, and marketplace registration.

Instructions

1. Gather plugin metadata. Ask for plugin name (short, lowercase, hyphenated), description (one-line summary), initial version (default: 0.1.0), category (usually "development"), and keywords (array of relevant terms)—these pieces establish the plugin's identity and marketplace presence.

2. Create directory structure. Create plugins/{name}/ directory with subdirectories for .claude-plugin/, skills/, and commands/—this establishes the physical layout that Claude Code expects for plugin discovery.

3. Generate plugin.json with correct schema. Create metadata file using proper author object format with name field, string URL for repository, array of strings for commands, and omit both skills field (auto-discovered) and compatibility field (not recognized)—these schema requirements prevent validation errors that block plugin loading.

4. Generate README.md. Create documentation file with plugin title and description, installation instructions for both marketplace and manual approaches, placeholder skill count (0 skills initially), usage examples section, and link to marketplace—this provides users with complete orientation to the plugin's purpose and setup.

5. Generate CHANGELOG.md. Create changelog file with standard structure including Unreleased section and initial placeholder entry—this establishes the documentation foundation for tracking changes across releases.

6. Add plugin to marketplace.json. Insert new plugin entry in .claude-plugin/marketplace.json with matching schema including name, description, version, source, category, author, repository, and keywords—this registers the plugin in the marketplace catalog making it discoverable and installable.

7. Run validation. Invoke repo-preflight to verify structure correctness including version consistency, skill count accuracy, changelog existence, and schema compliance—report any issues discovered during validation.

Workflow Steps

Step 1: Gather Metadata

Establish the plugin's marketplace identity by collecting name, description, and keywords—the name becomes the invocation path users type, the description determines discoverability through semantic search, and keywords enable cross-plugin navigation by topic. These pieces work together to make the plugin meaningful in the catalog.

Prompt for the name (lowercase, hyphenated format), a one-line description that captures purpose, and relevant keywords as comma-separated terms. Version starts at 0.1.0 to signal early development state, category defaults to "development" to mark it as tooling, and author plus repository maintain marketplace coherence when all plugins share organizational infrastructure.

Step 2: Create Directory Structure

Create these paths:

plugins/{name}/
plugins/{name}/.claude-plugin/
plugins/{name}/skills/
plugins/{name}/commands/

Step 3: Generate plugin.json

Create plugins/{name}/.claude-plugin/plugin.json:

{
  "name": "{name}",
  "version": "0.1.0",
  "description": "{description}",
  "author": {
    "name": "synapseradio"
  },
  "repository": "https://github.com/synapseradio/thinkies",
  "keywords": [
    "{keyword1}",
    "{keyword2}",
    "{keyword3}"
  ],
  "commands": []
}

The schema reflects Claude Code's architectural choices about responsibility and discovery. Author uses object format with name field to enable future metadata expansion while keeping current usage simple. Repository takes string URL format prioritizing clarity over structural flexibility. Commands array lists relative paths to command files. Skills field remains absent because Claude Code discovers skills from directory structure, maintaining the filesystem as the single source of truth. Compatibility field is omitted because Claude Code's current schema doesn't recognize it—including unsupported fields causes validation errors that prevent plugin loading.

Step 4: Generate README.md

Create plugins/{name}/README.md:

# {Title Case Name}

{Description}

## Overview

{Expanded description of plugin purpose and capabilities}

## Skills

This plugin provides **0 skills** across the following categories:

*(Skills will be listed here as they are added)*

## Installation

### Via Marketplace

Add the Thinkies marketplace to Claude Code:
1. Open Claude Code settings
2. Add marketplace URL: `https://raw.githubusercontent.com/synapseradio/thinkies/master/.claude-plugin/marketplace.json`
3. Install the `{name}` plugin

### Manual Installation

```bash
# Clone the repository
git clone https://github.com/synapseradio/thinkies.git

# Copy plugin to Claude Code plugins directory
cp -r thinkies/plugins/{name} ~/.claude/plugins/

Usage

Skills are invoked via the Skill() tool:

Skill("{skill-name}")

(Examples will be added as skills are developed)

License

MIT

### Step 5: Generate CHANGELOG.md

Create `plugins/{name}/CHANGELOG.md`:

```markdown
# Changelog

All notable changes to this plugin will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

- Initial plugin structure created
- Ready for skill development

Step 6: Add to Marketplace

Update .claude-plugin/marketplace.json by adding entry to plugins array:

{
  "name": "{name}",
  "description": "{description}",
  "version": "0.1.0",
  "source": "./plugins/{name}",
  "category": "development",
  "author": {
    "name": "synapseradio"
  },
  "repository": "https://github.com/synapseradio/thinkies",
  "keywords": [
    "{keyword1}",
    "{keyword2}"
  ]
}

Use jq to safely insert:

jq --argjson plugin '{ ... }' '.plugins += [$plugin]' \
  .claude-plugin/marketplace.json

Step 7: Validate

Invoke repo-preflight skill:

• Version consistency should pass (0.1.0 in both files)
• Skill count should be 0
• CHANGELOG should exist
• No skill references yet

Report results.

Examples

Example: Creating expression plugin

User: "I want to create a plugin for writing and communication skills"

Claude: "Great! Let's create a new plugin. What should it be called?"

User: "expression"

Claude: "Perfect. What's the one-line description?"

User: "Skills for writing with epistemic clarity and effective communication"

Claude: "Excellent. Any specific keywords? I'll suggest: writing, clarity, communication, epistemic, expression"

User: "Add narrative, voice, and tone too"

Process:

1. Creates directory structure:

   • plugins/expression/
   • plugins/expression/.claude-plugin/
   • plugins/expression/skills/
   • plugins/expression/commands/

2. Generates plugin.json with:

   {
     "name": "expression",
     "version": "0.1.0",
     "description": "Skills for writing with epistemic clarity and effective communication",
     "author": { "name": "synapseradio" },
     "repository": "https://github.com/synapseradio/thinkies",
     "keywords": ["writing", "clarity", "communication", "epistemic", "expression", "narrative", "voice", "tone"],
     "commands": []
   }
   

3. Generates README.md with plugin info and 0 skills

4. Generates CHANGELOG.md with initial structure

5. Adds to marketplace.json

6. Runs preflight

Output:

Plugin Created Successfully
===========================

Plugin: expression
Location: plugins/expression/
Version: 0.1.0

Files created:
✓ plugins/expression/.claude-plugin/plugin.json
✓ plugins/expression/README.md
✓ plugins/expression/CHANGELOG.md
✓ plugins/expression/skills/ (empty, ready for skills)

Marketplace integration:
✓ Added to .claude-plugin/marketplace.json

Preflight results:
✓ Version consistency verified
✓ Skill count accurate (0)
✓ CHANGELOG exists
✓ No broken references

Status: ✓ Ready to add skills

Next steps:
1. Use `repo-add-skill` to add skills to this plugin
2. Develop skill content
3. Use `repo-release` when ready to release

Example: Creating plugin with specific version

User: "Create a 'devops' plugin starting at version 1.0.0 for deployment and operations skills"

Claude: "Creating devops plugin. Keywords?"

User: "deployment, operations, infrastructure, automation, monitoring"

Process:

1. Creates structure as above
2. Sets version to 1.0.0 in both plugin.json and marketplace.json
3. Generates files
4. Validates

Output:

Plugin Created Successfully
===========================

Plugin: devops
Location: plugins/devops/
Version: 1.0.0

Files created:
✓ plugins/devops/.claude-plugin/plugin.json
✓ plugins/devops/README.md
✓ plugins/devops/CHANGELOG.md
✓ plugins/devops/skills/

Marketplace integration:
✓ Added to .claude-plugin/marketplace.json

Preflight results:
✓ All checks passed

Next steps:
1. Add skills with `repo-add-skill`
2. Consider updating CHANGELOG with initial scope

Example: Schema validation catches error

User: "Add a 'testing' plugin"

Claude: "What's the description?"

User: "Skills for test design and quality assurance"

Process:

1. Creates structure
2. Generates plugin.json with correct schema:
   • ✓ author: { "name": "synapseradio" } (object, not string)
   • ✓ repository: "https://..." (string, not object)
   • ✓ commands: [] (array, not object)
   • ✓ No skills field
   • ✓ No compatibility field
3. Adds to marketplace.json
4. Validates

Output:

Plugin Created Successfully
===========================

Plugin: testing
Location: plugins/testing/
Version: 0.1.0

Schema compliance verified:
✓ author is object: { "name": "synapseradio" }
✓ repository is string URL
✓ commands is array
✓ No unsupported fields

Marketplace integration:
✓ Added to .claude-plugin/marketplace.json

Preflight results:
✓ All checks passed

Next steps:
1. Add skills with `repo-add-skill`