distribute-plugins

<essential_principles>

1. Validate Before Publishing. Never distribute a plugin that hasn't passed structural validation and skill audits. Broken plugins damage trust and are hard to unpublish.

2. Semantic Versioning. Version numbers communicate intent. MAJOR for breaking changes. MINOR for new features. PATCH for fixes. Users depend on this contract.

3. No Secrets in Distribution. Hardcoded paths, credentials, API keys, and personal data must be caught before packaging. One leaked secret in a published plugin is a security incident.

4. Reproducible Installs. Every published version must install cleanly from the distribution source. If it works on your machine but not on a clean install, it's not ready.

</essential_principles>

<quick_start>

1. Point to the plugin directory
2. Pre-distribution checks run automatically (audit, validation, secrets scan)
3. Choose the version bump type (major, minor, patch)
4. Package is built (excluding dev files)
5. Choose distribution method (GitHub release, marketplace, path install)
6. Publish with documentation </quick_start>

<step_1> Pre-Distribution Checklist

Run all checks before packaging. Every item must pass:

#	Check	How to Verify
D01	All skills pass audit	Run audit-extensions on each skill
D02	plugin.json is valid	Parse JSON, verify required fields
D03	plugin.json has license field	Must specify a license (MIT, Apache-2.0, etc.)
D04	README.md exists	Must include installation instructions
D05	No hardcoded absolute paths	Grep for /Users/, /home/, C:\ patterns
D06	No credentials or secrets	Grep for API_KEY, SECRET, TOKEN, password patterns
D07	No .env files included	Check for .env, .env.local, .env.production
D08	All references resolve	Every file referenced in SKILL.md routing/index exists
D09	All skill names match directories	YAML name field = directory name for every skill
D10	No empty skill directories	Every skill dir has a SKILL.md with content

If any check fails, report the failures and stop. Do not proceed to packaging with known issues. </step_1>

<step_2> Semantic Versioning

Determine the version bump based on changes since last release:

MAJOR version (X.0.0) -- Breaking changes:

• Renamed or removed skills
• Changed skill behavior that users depend on
• Removed commands or subagents
• Changed plugin.json structure
• Renamed the plugin itself

MINOR version (x.Y.0) -- New features:

• Added new skills
• Added new workflows to existing skills
• Added new commands or subagents
• Added new references or templates
• New configuration options

PATCH version (x.y.Z) -- Fixes:

• Bug fixes in skill content
• Typo corrections
• Updated references for accuracy
• Performance improvements
• Documentation updates

Version file: Update the version field in plugin.json.

If no previous version exists, start at 1.0.0.

Changelog: Generate or update CHANGELOG.md with:

## [X.Y.Z] - YYYY-MM-DD

### Added
- [New features]

### Changed
- [Modified features]

### Fixed
- [Bug fixes]

### Removed
- [Removed features]

</step_2>

<step_3> Packaging

Create the distribution package:

Exclude from package:

• __pycache__/
• node_modules/
• *.pyc
• .DS_Store
• evals/ (test data, not runtime)
• .env*
• .git/
• *.log
• .claude/ (user-specific config)
• *.tmp
• *.bak

Include in package:

• plugin.json (root manifest)
• skills/ (all skill directories with SKILL.md, workflows/, references/, templates/, scripts/)
• agents/ (all subagent configurations)
• commands/ (all slash commands)
• hooks/ (all hook configurations)
• scripts/ (plugin-level scripts)
• shared/ (shared rules, templates, configs)
• README.md
• LICENSE
• CHANGELOG.md