# plugin-package

> Package a Claude Code plugin for distribution

- Author: Edison
- Repository: soilmass/claudeutils
- Version: 20260127023329
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-06
- Source: https://github.com/soilmass/claudeutils
- Web: https://mule.run/skillshub/@@soilmass/claudeutils~plugin-package:20260127023329

---

---
name: plugin-package
description: Package a Claude Code plugin for distribution
argument-hint: "<plugin-dir> [--output <dir>] [--format tgz|zip]"
user-invocable: true
model: sonnet
---

# plugin-package

Package a validated and tested Claude Code plugin into a distributable archive.

## When to Use

Use this skill when:
- Plugin has passed validation and testing
- You want to distribute the plugin
- You need to create a release artifact
- You want to share the plugin with others

## Prerequisites

- Plugin must pass `/plugin-validate`
- Plugin must pass `/plugin-test`
- Workflow must be in publish phase

## Arguments

| Argument | Required | Description |
|----------|----------|-------------|
| `plugin-dir` | Yes | Path to the plugin directory |
| `--output` | No | Output directory (default: dist/) |
| `--format` | No | Package format: tgz, zip (default: tgz) |
| `--no-checksum` | No | Skip checksum generation |

## Example Usage

```
/plugin-package ./my-plugin
```

```
/plugin-package ./my-plugin --output ./releases --format zip
```

## Workflow

When invoked, follow these steps:

### Step 1: Pre-Package Validation

1. Verify plugin directory exists
2. Check validation has passed
3. Check tests have passed
4. Verify we're in publish phase
5. If not ready, report what's needed

### Step 2: Read Plugin Metadata

Extract from `plugin.json`:
- name
- version
- description
- author
- license

### Step 3: Verify Documentation

Check required files exist:
- README.md (with installation section)
- CHANGELOG.md (with current version entry)
- LICENSE

If missing, warn but continue.

### Step 4: Clean Build Artifacts

Remove from package:
- `node_modules/`
- `.git/`
- `state/`
- `*.log`
- `.env`
- `.DS_Store`
- `.plugin-design/` (optional, design docs)

### Step 5: Create Package

**For tgz format:**
```bash
tar -czf <name>-<version>.tgz \
  --exclude='node_modules' \
  --exclude='.git' \
  --exclude='state' \
  --exclude='*.log' \
  --exclude='.env' \
  -C <parent-dir> <plugin-name>
```

**For zip format:**
```bash
zip -r <name>-<version>.zip <plugin-dir> \
  -x '*/node_modules/*' \
  -x '*/.git/*' \
  -x '*/state/*' \
  -x '*.log' \
  -x '.env'
```

### Step 6: Generate Checksums

```bash
sha256sum <package-file> > <package-file>.sha256
```

### Step 7: Create Distribution Manifest

Create `dist/manifest.json`:

```json
{
  "name": "<plugin-name>",
  "version": "<version>",
  "description": "<description>",
  "author": "<author>",
  "license": "<license>",
  "package": "<package-filename>",
  "format": "tgz",
  "size": <bytes>,
  "sha256": "<hash>",
  "createdAt": "<ISO timestamp>",
  "contents": {
    "skills": ["<skill-list>"],
    "agents": ["<agent-list>"],
    "hooks": true,
    "mcp": true
  },
  "requirements": {
    "claude-code": ">=1.0.0"
  }
}
```

### Step 8: Update Workflow State

1. Record package creation
2. Mark workflow as complete
3. Store package path

### Step 9: Report Results

```
Package Created: <plugin-name> v<version>
=========================================

Package:  dist/<name>-<version>.tgz
Size:     <size> KB
SHA256:   <hash>

Contents:
  Skills:      3
  Agents:      1
  Hooks:       2
  MCP Servers: 1

Distribution Files:
  dist/
  ├── <name>-<version>.tgz
  ├── <name>-<version>.tgz.sha256
  └── manifest.json

Installation:
  # Extract and use
  tar -xzf <name>-<version>.tgz
  claude --plugin-dir ./<name>

Publishing Options:
  1. GitHub Release
     - Upload .tgz and .sha256 files
     - Include manifest.json in release notes

  2. npm Registry
     npm publish dist/<name>-<version>.tgz

  3. Direct Distribution
     - Share the .tgz file
     - Provide SHA256 for verification

Plugin workflow complete!
```

## Package Contents

The package includes:
```
<plugin-name>/
├── .claude-plugin/
│   └── plugin.json
├── skills/
│   └── <skill>/SKILL.md
├── agents/
│   └── <agent>.md
├── hooks/
│   ├── hooks.json
│   └── scripts/*.sh
├── .mcp.json
├── README.md
├── CHANGELOG.md
└── LICENSE
```

## Excluded Files

Never include in package:
- `node_modules/` - users will install dependencies
- `.git/` - version control
- `state/` - runtime state
- `.env` - secrets
- `*.log` - logs
- `.DS_Store` - macOS artifacts
- `.plugin-design/` - design docs (optional)

## Error Handling

- If not in publish phase: Block and show required steps
- If validation not passed: Block and suggest /plugin-validate
- If tests not passed: Block and suggest /plugin-test
- If documentation missing: Warn but allow (with flag)
- If package creation fails: Report error with details

## Verification

After creating package, verify:
```bash
# Check package contents
tar -tzf <package>.tgz

# Verify checksum
sha256sum -c <package>.sha256

# Test installation
mkdir test-install && cd test-install
tar -xzf ../<package>.tgz
claude --plugin-dir ./<name> --debug
```

## Integration Points

- Blocked by pre-test-check if not in publish phase
- Finalized by post-package-finalize hook
- Workflow state marked complete on success