Plugin Creation Workflow

Post-creation workflow for new Claude Code plugins in dx-toolkit monorepo. Plugins are lightweight - just commands in markdown files.

---

Plugin vs Package

Plugins (Claude Code plugins):

• Located in plugins/ directory
• Distributed via GitHub releases (not npm)
• Simple structure: just markdown commands + manifest
• Used by Claude Code, Cursor, and other AI agents
• No build process, no dependencies

Packages (npm packages):

• Located in packages/ directory
• Published to npm registry
• Have source code, tests, build process
• Used by developers in their applications

---

Plugin Structure

plugins/{plugin-name}/
├── .claude-plugin/
│   └── plugin.json              # Plugin manifest (required)
├── AGENTS.md                    # Universal AI agent instructions
├── commands/
│   └── {command}.md            # Command implementation files
├── README.md                    # User-facing documentation
└── LICENSE                      # MIT license

That's it! No package.json, no tsconfig.json, no src directory.

---

Post-Creation Workflow

1. Implement Command Files

Commands directory pattern:

• Create commands/{command-name}.md for each slash command
• Use frontmatter with name and description
• Write complete workflow with step-by-step instructions
• Include code examples and configuration blocks

Example command file structure:

---
name: command-name
description: Brief description of what this command does
---

# Command Title

Interactive workflow to achieve X.

## Workflow

1. **Ask: First Question**
   * What information do you need?

2. **Validate Input**
   * Check prerequisites
   * Verify environment variables

3. **Create/Update Files**
   * Use complete templates
   * Show configuration examples

## Complete Templates

### Template Name

\```language
// Complete, runnable code
\```

2. Write AGENTS.md

Purpose: Lightweight alias file for non-Claude Code AI agents

Pattern:

# Plugin Name

> For AI coding agents: Brief description

## When to Use

Trigger this integration when developer mentions:
- "keyword phrase 1"
- "keyword phrase 2"

## Integration Instructions

**Fetch and follow the complete integration workflow:**

`commands/{command-name}.md`

This file contains:
- Complete step-by-step workflow
- Language/framework selection
- Configuration patterns
- Template integration guide
- Validation checklist

## For Claude Code Users

Use the slash command: `/{command-name}`

## Additional Resources

* Plugin README: https://api.you.com/plugins/{plugin-name}/README.md
* Relevant external docs

Key Principle: Never duplicate content. AGENTS.md just points to command files.

3. Write README.md

Tone: Encouraging and accessible (see .claude/skills/documentation)

Required sections:

1. What you get - Bullet points with emojis
2. Installation - Collapsible sections for each platform
3. Quick Start - 4 steps maximum
4. Prerequisites - What users need
5. Troubleshooting - Common issues with solutions

Installation format:

<details open>
<summary><strong>Claude Code</strong></summary>

**Option 1: Via install script (recommended)**

The script automatically configures the marketplace and installs the plugin:

\```bash
curl -fsSL https://raw.githubusercontent.com/youdotcom-oss/dx-toolkit/main/scripts/install-plugin.sh | bash -s {plugin-name} --claude
\```

**Option 2: Via marketplace**

First add the marketplace:
\```bash
/plugin marketplace add youdotcom-oss/dx-toolkit
\```

Then install the plugin:
\```bash
/plugin install {plugin-name}
\```

**Use the plugin:**
\```bash
/{command-name}
\```

</details>

<details>
<summary><strong>Cursor</strong></summary>

\```bash
curl -fsSL https://raw.githubusercontent.com/youdotcom-oss/dx-toolkit/main/scripts/install-plugin.sh | bash -s {plugin-name} --cursor
\```

Then enable in Cursor:
1. Open **Settings → Rules → Import Settings**
2. Toggle **"Claude skills and plugins"**

Cursor will automatically discover and use the plugin.

See [Cursor Rules Documentation](https://cursor.com/docs/context/rules#claude-skills-and-plugins)

</details>

<details>
<summary><strong>Other AI Agents</strong></summary>

For Cody, Continue, Codex, Jules, VS Code, and more:

\```bash
curl -fsSL https://raw.githubusercontent.com/youdotcom-oss/dx-toolkit/main/scripts/install-plugin.sh | bash -s {plugin-name} --agents.md
\```

Your AI agent will automatically discover the plugin via `AGENTS.md`.

Learn more: [agents.md specification](https://agents.md/)

</details>

4. Create plugin.json

Required fields per Claude Code specification:

{
  "name": "plugin-name",
  "version": "0.1.0",
  "description": "Brief description",
  "commands": [
    {
      "name": "command-name",
      "description": "What this command does",
      "path": "commands/command-name.md"
    }
  ],
  "author": {
    "name": "You.com",
    "email": "support@you.com",
    "url": "https://you.com"
  },
  "license": "MIT",
  "repository": "https://github.com/youdotcom-oss/dx-toolkit"
}

Key points:

• Use object format for author (not string)
• Version starts at 0.1.0 for initial release
• Commands array references markdown files in commands/
• No dependencies, no devDependencies

5. Add to marketplace.json

Location: Root marketplace.json

Format:

{
  "name": "plugin-name",
  "version": "0.1.0",
  "description": "Brief description matching plugin.json",
  "category": "workflow",
  "path": "./plugins/plugin-name",
  "publicUrl": "https://github.com/youdotcom-oss/dx-toolkit/releases/tag/plugin-name@v0.1.0",
  "downloadUrl": "https://github.com/youdotcom-oss/dx-toolkit/releases/download/plugin-name@v0.1.0/plugin-name-v0.1.0.tar.gz",
  "keywords": ["keyword1", "keyword2", "keyword3"]
}

Categories:

• workflow - Integration and setup workflows
• enterprise-integration - Enterprise platform integrations

6. Add to MARKETPLACE.md

Location: docs/MARKETPLACE.md

Do NOT include version numbers - they're not auto-updated

Format:

<details open>
<summary><strong>plugin-name</strong></summary>

**One-line description**

Longer description paragraph explaining what the plugin does.

**What you get:**
- 🎯 Feature 1
- 🚀 Feature 2
- ✨ Feature 3

**Quick Install:**
\```bash
# Claude Code
/plugin install plugin-name
# Or: curl -fsSL https://raw.githubusercontent.com/youdotcom-oss/dx-toolkit/main/scripts/install-plugin.sh | bash -s plugin-name --claude

# Cursor
curl -fsSL https://raw.githubusercontent.com/youdotcom-oss/dx-toolkit/main/scripts/install-plugin.sh | bash -s plugin-name --cursor

# Other AI Agents (Cody, Continue, etc.)
curl -fsSL https://raw.githubusercontent.com/youdotcom-oss/dx-toolkit/main/scripts/install-plugin.sh | bash -s plugin-name --agents.md
\```

**Documentation:**
- [Plugin README](https://github.com/youdotcom-oss/dx-toolkit/tree/main/plugins/plugin-name)
- [Relevant External Docs](https://example.com)
- [GitHub Releases](https://github.com/youdotcom-oss/dx-toolkit/releases?q=plugin-name)

</details>

7. Create Publish Workflow

Location: .github/workflows/publish-{plugin-name}.yml

Template:

name: "Plugin: publish {plugin-name}"

on:
  workflow_dispatch:
    inputs:
      version:
        description: "Version to publish (e.g., 1.0.0)"
        required: true
        type: string
      next:
        description: "Next prerelease number (optional, e.g., 1 for v1.0.0-next.1)"
        required: false
        type: string

jobs:
  publish:
    name: Publish Plugin
    uses: ./.github/workflows/_publish-plugin.yml
    with:
      plugin_name: {plugin-name}
      version: ${{ inputs.version }}
      next: ${{ inputs.next }}
    secrets:
      PUBLISH_TOKEN: ${{ secrets.PUBLISH_TOKEN }}

8. Test Locally

# View plugin structure
ls -R plugins/{plugin-name}

# Test commands are accessible
cat plugins/{plugin-name}/commands/{command-name}.md

# Verify plugin.json is valid
cat plugins/{plugin-name}/.claude-plugin/plugin.json | jq .

# Test with Claude Code (if available)
/plugin install {plugin-name}
/{command-name}

9. First Release

Use prerelease for testing:

# Trigger workflow with prerelease version
Actions → Publish {plugin-name} Release → Run workflow
Version: 0.1.0
Next: 1

This creates plugin-name@v0.1.0-next.1 for testing.

First stable release:

Version: 0.1.0
Next: (leave empty)

This creates plugin-name@v0.1.0 as the first stable release.

---

Plugin Naming Conventions

Plugin directory: Must match plugin name in .claude-plugin/plugin.json

Examples:

• Plugin name: teams-anthropic-integration → Directory: plugins/teams-anthropic-integration ✅
• Plugin name: claude-agent-sdk-integration → Directory: plugins/claude-agent-sdk-integration ✅

Version format:

• Git tags: v{version} (e.g., v1.0.0)
• plugin.json and marketplace.json: {version} (no "v" prefix)

---

MCP Server Naming Convention

For plugins that configure MCP servers:

Use ydc as the server name/label for consistency with tool naming:

Claude Agent SDK:

mcp_servers={
    "ydc": {
        "type": "http",
        "url": "https://api.you.com/mcp",
        "headers": {"Authorization": f"Bearer {os.getenv('YDC_API_KEY')}"}
    }
}

allowed_tools=[
    "mcp__ydc__you_search",
    "mcp__ydc__you_express",
    "mcp__ydc__you_contents"
]

OpenAI Agents SDK:

HostedMCPTool(
    tool_config={
        "type": "mcp",
        "server_label": "ydc",
        "server_url": "https://api.you.com/mcp",
        "headers": {"Authorization": f"Bearer {os.environ['YDC_API_KEY']}"},
        "require_approval": "never"
    }
)

Rationale: Tools are named you_search, you_express, etc. Using ydc (You.com abbreviation) as the server identifier provides clear distinction while maintaining consistency.

---

Distribution

Plugins are distributed via GitHub Releases, not npm:

Release URL format:

• Tag: {plugin-name}@v{version}
• Archive: {plugin-name}-v{version}.tar.gz
• Download: https://github.com/youdotcom-oss/dx-toolkit/releases/download/{plugin-name}@v{version}/{plugin-name}-v{version}.tar.gz

Marketplace versioning:

• Format: Date-based CalVer (YYYY.MM.DD)
• Auto-bumped on every plugin release
• Indicates last marketplace update date

---

Troubleshooting

Plugin not showing in Claude Code

• Verify .claude-plugin/plugin.json exists and is valid JSON
• Check plugin name matches directory name
• Ensure plugin is in marketplace.json
• Restart Claude Code after installation

Command not found

• Verify command is listed in plugin.json commands array
• Check command file path matches what's in plugin.json
• Ensure command file has proper frontmatter

Installation fails

• Check plugin archive is accessible at GitHub release URL
• Verify marketplace.json has correct downloadUrl
• Ensure version in marketplace.json matches the release tag

---

See Also

• Plugin Marketplace Documentation
• Documentation Standards
• Git Workflow