Skip to content

Creating Plugins

How to create a department-specific plugin for the VisiTrans Claude Toolkit.

Plugin structure

A plugin is a directory inside plugins/ with this structure:

plugins/my-department/
├── .claude-plugin/
│   ├── plugin.json              # Plugin metadata
│   ├── skill-symlinks.manifest  # Skill mappings
│   └── command-symlinks.manifest # Command mappings (optional)
├── CHANGELOG.md                 # Version history (required)
├── skills/
│   └── my-skill/
│       └── SKILL.md
├── agents/                      # Optional
│   └── my-agent.md
└── commands/                    # Optional
    └── my-command.md

Step 1: Create the directory

mkdir -p plugins/my-department/.claude-plugin
mkdir -p plugins/my-department/skills

Step 2: Create plugin.json

{
  "name": "my-department",
  "version": "1.0.0",
  "description": "Skills and agents for the My Department team",
  "depends_on": ["core-standards"],
  "author": {
    "name": "My Department"
  },
  "license": "MIT",
  "components": {
    "skills": 0,
    "agents": 0,
    "commands": 0
  }
}

Update the component counts as you add skills, agents, and commands.

Step 2b: Create CHANGELOG.md

Create plugins/my-department/CHANGELOG.md:

# Changelog

## [1.0.0] - 2026-01-01

### Added
- Initial release with [describe initial features]

The finalize gate (/vt-c-5-finalize) requires a changelog entry for every version. See Plugin Versioning for the full versioning workflow.

Step 3: Add skills

Create a skill directory with a SKILL.md file:

mkdir -p plugins/my-department/skills/my-workflow

The SKILL.md file needs YAML frontmatter:

---
name: my-workflow
description: Description of what this skill does and when to use it.
---

# My Workflow

Instructions for Claude when this skill activates...

Use the skill creator

Run /vt-c-skill-creator in Claude Code for an interactive guide to creating well-structured skills.

Step 4: Create the manifest

Create plugins/my-department/.claude-plugin/skill-symlinks.manifest:

my-workflow -> skills/my-workflow

Each line maps a skill name to its directory path (relative to the plugin root).

Step 5: Register in the registry

Add your plugin to plugins/registry.json:

{
  "plugins": {
    "core-standards": { "path": "plugins/core-standards", "required": true, "version": "3.0.0" },
    "my-department": { "path": "plugins/my-department", "required": false, "version": "1.0.0", "depends_on": ["core-standards"] }
  }
}

Step 6: Install

./scripts/setup.sh --full --plugins core-standards,my-department

Adding agents

Agents go in plugins/my-department/agents/:

---
name: my-specialist
description: Use this agent when...
tools:
  - Read
  - Grep
  - Glob
---

# My Specialist Agent

You are a specialist in...

Adding commands

Commands go in plugins/my-department/commands/:

---
name: my-command
description: What this command does
argument-hint: "[optional-args]"
---

# My Command

Instructions for what happens when the user runs /my-command...

Add command mappings to .claude-plugin/command-symlinks.manifest.

Best practices

  • Keep plugins focused — one plugin per department or domain
  • Depend on core-standards — don't duplicate what the core provides
  • Use consistent frontmatter — name and description are required
  • Test locally — run setup.sh --verify after installation
  • Update component counts — keep plugin.json accurate
  • Keep versions in sync — plugin.json version must match plugins/registry.json
  • Maintain your changelog — every version bump needs a ## [x.y.z] entry in CHANGELOG.md
  • See Plugin Versioning for the complete versioning and finalize gate workflow

Plugin MCP servers

Plugins can bundle MCP servers to automatically provide tools and integrations when the plugin is enabled. Plugin MCP servers start automatically and appear alongside manually configured MCP tools.

Configuration approaches

Option 1: Inline in plugin.json

Add an mcpServers field directly to your plugin.json:

{
  "name": "my-department",
  "version": "1.0.0",
  "description": "Skills and agents for My Department",
  "depends_on": ["core-standards"],
  "mcpServers": {
    "department-api": {
      "command": "${CLAUDE_PLUGIN_ROOT}/servers/api-server",
      "args": ["--port", "8080"]
    }
  }
}

Option 2: Standalone .mcp.json at plugin root

Create a .mcp.json file at the root of your plugin directory (next to CHANGELOG.md):

{
  "mcpServers": {
    "department-tools": {
      "command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server",
      "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"],
      "env": {
        "DB_URL": "${DB_URL}"
      }
    }
  }
}

Plugin-relative paths

Use ${CLAUDE_PLUGIN_ROOT} to reference files within your plugin directory. This variable resolves to the absolute path of the plugin root, making configurations portable across machines.

Lifecycle

  • Plugin MCP servers start when the plugin is enabled
  • You must restart Claude Code after enabling or disabling a plugin for MCP server changes to take effect
  • Plugin servers are managed through plugin installation, not /mcp commands
  • Users can view all active MCP servers (including plugin-provided ones) with /mcp

When to use plugin MCP servers

Plugin MCP servers are useful when your department needs:

  • Automatic tool setup — no manual claude mcp add required per-user
  • Bundled distribution — server code and plugin config packaged together
  • Team consistency — everyone gets the same tools when the plugin is installed

For building MCP servers, see the /vt-c-mcp-builder skill which covers server implementation in Python (FastMCP) and Node.js (MCP SDK).