Plugin Dev Studio Workflow

Comprehensive development environment for building, testing, and validating Claude Code plugins with hot-reload support.

When to Use This Skill

Activate this skill when:

• Developing a new plugin and need rapid iteration with live validation

• Debugging plugin manifest or resource file issues

• Visualizing plugin dependency graphs for architecture review

• Building regression test suites for plugin commands

• Preparing a plugin for publication to a registry

Architecture Overview

The Dev Studio consists of four core subsystems:

+------------------+ +---------------+ +-------------------+ | FileWatcher | --> | HotReloader | --> | Resource Registry | | (FNV-1a hashing) | | (Validation) | | (Live state) | +------------------+ +---------------+ +-------------------+ | v +--------------------+ | Console Reporter | | (file:line errors) | +--------------------+

+-------------------+ +---------------------------+ | PluginPlayground | | DependencyGraphRenderer | | (Record/Replay) | | (ASCII + Mermaid output) | +-------------------+ +---------------------------+

FileWatcher

Monitors a plugin directory for file changes using filesystem watchers with content-hash-based change detection.

Key design decisions:

• Uses FNV-1a (32-bit) hashing for speed — non-cryptographic, but extremely fast for small files

• Only triggers reload when file content actually changed (ignores timestamp-only updates)

• Debounces rapid changes with a 100ms window to batch editor save operations

• Classifies files by resource type (command, skill, agent, config, source)

HotReloader

Processes file changes and maintains a live resource registry.

On each change:

• If manifest changed: re-read, re-validate JSON structure and required fields

• If markdown resource changed: re-lint frontmatter (YAML validity, required fields)

• Update resource registry: add new resources, update modified ones, remove deleted ones

• Report validation results with file:line references for inline error display

PluginPlayground

Isolated execution context for testing plugin commands.

Record-replay workflow:

• Register mock capabilities for external dependencies

• Execute commands and record full input/output pairs as fixtures

• Save fixtures to tests/fixtures/ as JSON

• Replay fixtures in CI to detect regressions

DependencyGraphRenderer

Builds and renders plugin dependency graphs.

Two output formats:

• ASCII tree: Uses Unicode box-drawing characters for terminal display

• Mermaid diagram: Pasteable into GitHub markdown, Notion, or Mermaid Live Editor

Development Workflow

Phase 1: Scaffold and Configure

Create plugin structure

mkdir -p my-plugin/{commands,skills,agents,config,src,tests/fixtures} mkdir -p my-plugin/.claude-plugin

Create minimal manifest

cat > my-plugin/.claude-plugin/plugin.json << 'EOF' { "name": "my-plugin", "version": "0.1.0", "description": "My new plugin", "contextEntry": "CONTEXT.md", "capabilities": { "provides": ["my-capability"], "requires": [] } } EOF

Create required operator runbook

cat > my-plugin/CLAUDE.md << 'EOF'

My Plugin Guide

Purpose

• Brief description of plugin intent.

Supported Commands

• command-name (commands/command-name.md)

Prohibited Actions

• List destructive or out-of-scope operations.

Required Validation Checks

• npm run check:plugin-context
• npm run check:plugin-schema

Context Budget

1. CONTEXT_SUMMARY.md
2. commands/index (or commands/)
3. README.md and only task-relevant deep docs

Escalation Path

• Describe who reviews risky or blocking changes. EOF

Create operator context entrypoint (keep concise)

cat > my-plugin/CONTEXT.md << 'EOF'

my-plugin Context

Purpose

One-paragraph operator summary.

Key Commands

• /my:command

Agent Inventory

• my-agent

Load Deeper Docs When

• You need implementation details or architecture rationale. EOF

Phase 2: Develop with Hot-Reload

Start the dev server with file watching

/mp:dev serve ./my-plugin --watch

The dev server will:

• Validate the manifest on startup

• Discover and register all commands, skills, and agents

• Watch for file changes and re-validate on save

• Show inline errors with file:line references

Phase 3: Test in Playground

Launch interactive playground

/mp:dev playground ./my-plugin

In the playground:

> run /my:command "test input"

> save my-test-case

> log

Phase 4: Visualize Dependencies

Show dependency graph

/mp:dev graph ./my-plugin

Review the ASCII tree to verify:

• All capability declarations are correct

• Inter-resource dependencies are properly linked

• No circular dependencies exist

Phase 5: Validate Before Publish

Full validation suite

/mp:dev validate ./my-plugin

Fix all errors before publishing. Warnings are advisory but should be addressed.

Phase 6: Regression Testing

List saved fixtures

/mp:dev fixture list

Replay a specific fixture

/mp:dev fixture replay my-test-case

Validation Rules

Manifest Validation (plugin.json)

Rule Severity Description

Valid JSON error File must be parseable JSON

name field error Must be a non-empty string

version field error Must be a non-empty string

description field error Must be a non-empty string

contextEntry field error Must reference CONTEXT.md or PLUGIN_CONTEXT.md

CLAUDE.md present error Plugin root must include CLAUDE.md runbook

capabilities present warning Plugin should declare capabilities

capabilities.provides is array error Must be an array of strings

capabilities.requires is array error Must be an array of strings

Command/Skill Validation (.md files)

Rule Severity Description

Has frontmatter error Must start with ---

Frontmatter closed error Must have closing ---

name in frontmatter error Commands and skills must have a name

description in frontmatter warning Should have a description

Top-level heading info Should have # Title after frontmatter

File Structure

plugin-root/ .claude-plugin/ plugin.json # Plugin manifest (validated by HotReloader) CLAUDE.md # Required operator runbook and context budget CONTEXT.md # Minimal operator context entrypoint commands/ *.md # Slash commands (validated for frontmatter) skills/ */SKILL.md # Skills (validated for frontmatter) agents/ *.md # Agents (validated for frontmatter) config/ *.json # Configuration files src/ devstudio/ types.ts # Type definitions server.ts # FileWatcher, HotReloader, Playground, GraphRenderer tests/ fixtures/ *.json # Recorded test fixtures (from playground)

Troubleshooting

Common Issues

"Plugin manifest not found"

• Ensure .claude-plugin/plugin.json exists in the plugin root

• Check that the path passed to /mp:dev is correct

"Missing YAML frontmatter"

• Markdown resource files must start with --- on the first line

• Frontmatter must be closed with a second --- line

"Content hash unchanged but file was modified"

• The FileWatcher uses content hashing, not timestamps

• If only whitespace changed, verify the hash actually differs

• The FNV-1a hash has a very low (but non-zero) collision rate for small changes

"Fixture replay fails with empty output"

• Playground execution is a simulation; real command execution requires the Claude runtime

• Record the actual output using recordOutput() after command execution

Source Files

• Types: src/devstudio/types.ts

• Implementation: src/devstudio/server.ts

• Command: commands/dev.md

• This skill: skills/devstudio/SKILL.md

Skill version: 1.0 Module: dev-studio (marketplace-pro plugin)