Contributing to MSP Claude Plugins

Thank you for your interest in contributing to MSP Claude Plugins! This guide covers everything from quick fixes to building new platform plugins.

Contribution Tiers
Getting Started
Development Environment Setup
Skill Development Guide
Command Development Guide
MCP Server Integration Guide
Testing Requirements
Style Guide
Pull Request Process
Getting Help

Contribution Tiers

Not every change needs a PRD. We use a tiered system so the process matches the scope of the work.

Tier 1 — Quick Fixes (no PRD needed)

Just fork, branch, and open a PR.

Examples:

Typo fixes in skills or documentation
Field mapping corrections (wrong status codes, incorrect enum values)
Bug fixes in existing commands
Error message improvements
README updates

Tier 2 — Feature Enhancements (lightweight proposal)

Open a Feature Enhancement issue describing what you want to add. Get a maintainer thumbs-up, then submit a PR.

Examples:

New commands for existing plugins
New skill files for existing plugins
Expanded MCP server coverage (new tools/endpoints)
Significant changes to existing behavior

Tier 3 — New Platforms (full PRD)

Building a plugin for a vendor we don't support yet? Submit a PRD first.

Copy the template from _templates/plugin-prd-template.md
Fill it out and submit as a PR with [PRD] prefix
Get community review and maintainer approval
Implement once approved

PRD Requirements Checklist:

Getting Started

Prerequisites

Requirement	Description
GitHub Account	For forking and submitting PRs
Git	Version control
Text Editor	VS Code recommended with Markdown preview
MSP Knowledge	Understanding of PSA/RMM workflows
API Documentation	Access to vendor API docs you're targeting
(Optional) API Access	For testing against live APIs

Fork and Clone

# 1. Fork the repository via GitHub UI (click Fork button)

# 2. Clone your fork
git clone https://github.com/YOUR-USERNAME/msp-claude-plugins.git
cd msp-claude-plugins

# 3. Add upstream remote for syncing
git remote add upstream https://github.com/wyre-technology/msp-claude-plugins.git

# 4. Verify remotes
git remote -v

Syncing Your Fork

# Before starting new work, sync with upstream
git checkout main
git fetch upstream
git merge upstream/main
git push origin main

Development Environment Setup

Directory Structure

msp-claude-plugins/
├── _standards/              # Quality standards (read first!)
├── _templates/              # Templates for all contributions
├── kaseya/                  # Kaseya vendor plugins
│   └── autotask/           # Reference implementation
├── connectwise/             # ConnectWise vendor plugins
├── shared/                  # Vendor-agnostic skills
└── docs/                    # Documentation site

Recommended Tools

Tool	Purpose	Installation
VS Code	Editor with Markdown preview	https://code.visualstudio.com
Markdown All in One	VS Code extension	VS Code marketplace
YAML	VS Code extension for frontmatter	VS Code marketplace
REST Client	API testing	Thunder Client extension
Claude Code	Testing plugins locally	https://claude.ai/code

Environment Variables

When testing MCP integrations, configure these environment variables:

# Autotask
export AUTOTASK_USERNAME="your-api-user@domain.com"
export AUTOTASK_INTEGRATION_CODE="YOUR_INTEGRATION_CODE"
export AUTOTASK_SECRET="YOUR_SECRET"

# ConnectWise
export CW_COMPANY_ID="your-company"
export CW_PUBLIC_KEY="your-public-key"
export CW_PRIVATE_KEY="your-private-key"
export CW_CLIENT_ID="your-client-id"

# Never commit these values!

Skill Development Guide

Skills provide domain knowledge that Claude can reference when helping users.

Skill File Location

vendor/product/skills/skill-name/SKILL.md

Skill Template Structure

---
description: >
  Use this skill when [specific trigger conditions].
  [Additional context about what this skill covers].
triggers:
  - trigger phrase 1
  - trigger phrase 2
  - trigger phrase 3
---

# Skill Title

## Overview
[2-3 paragraphs explaining what this skill covers and why it's important]

## Key Concepts
[Tables, definitions, and core knowledge]

## Field Reference
[Complete field documentation with types and descriptions]

## Business Logic
[Workflows, validation rules, status transitions]

## API Patterns
[Concrete API examples with request/response]

## Common Workflows
[Step-by-step guides for common tasks]

## Error Handling
[Common errors and resolutions]

## Best Practices
[Numbered list of recommendations]

## Related Skills
[Links to related skills]

Example: Learning from Existing Skills

Study the Autotask tickets skill as a reference:

File: kaseya/autotask/skills/tickets/SKILL.md

Key elements to note:

Frontmatter Triggers - Multiple relevant keywords
Status Code Tables - Clear reference data
Business Logic Code - Practical validation examples
API Examples - Real request/response patterns

Skill Quality Checklist

Before submitting a skill, verify:

Frontmatter has accurate, comprehensive triggers
Overview explains the domain clearly
All relevant fields are documented with types
Status codes/enums have complete tables
API examples use realistic (but fake) data
No hardcoded credentials
Business logic includes validation rules
Error handling section is complete
Links to related skills work

Command Development Guide

Commands provide slash-command shortcuts for common operations.

Command File Location

vendor/product/commands/command-name.md

Command Template Structure

---
name: command-name
description: Brief description of what this command does
arguments:
  - name: required-arg
    description: Description of this argument
    required: true
  - name: optional-arg
    description: Description of optional argument
    required: false
---

# Command Title

Brief description of the command's purpose.

## Prerequisites
- List of requirements before using this command
- API credentials configured
- Permissions needed

## Steps
1. **Step title** - Description
   - Sub-step details
   - API calls made

## Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| arg1 | string | Yes | - | Description |
| arg2 | int | No | 10 | Description |

## Examples

### Basic Usage

/command-name "required value"


### With Options

/command-name "value" --option1 "something" --option2 123


## Output

### Success

Operation completed Details...


### Error Handling
| Error | Resolution |
|-------|------------|
| Not found | Verify ID exists |
| Unauthorized | Check credentials |

## Related Commands
- `/other-command` - Description

Command Best Practices

Keep names short and memorable - /create-ticket not /create-new-service-ticket
Use intuitive arguments - First argument should be most important
Provide sensible defaults - Optional args should have good defaults
Show progress - Include output examples showing success/failure
Handle errors gracefully - Document common errors and fixes

MCP Server Integration Guide

MCP (Model Context Protocol) enables direct API connectivity from Claude.

MCP Configuration File

Create .mcp.json in your plugin root:

{
  "mcpServers": {
    "vendor-product": {
      "command": "npx",
      "args": ["-y", "@vendor/mcp-server-product"],
      "env": {
        "API_USERNAME": "${VENDOR_USERNAME}",
        "API_KEY": "${VENDOR_API_KEY}"
      }
    }
  }
}

Environment Variable References

Use ${VARIABLE_NAME} syntax for environment variables
Document all required variables in README.md
Never hardcode credentials

Testing MCP Integration

# 1. Set environment variables
export VENDOR_USERNAME="test-user"
export VENDOR_API_KEY="test-key"

# 2. Start Claude Code with plugin
cd vendor/product
claude --plugin .

# 3. Test MCP tools
# Claude should have access to vendor API tools

MCP Server Development

If creating a new MCP server:

Follow MCP specification
Publish to npm as @vendor/mcp-server-product
Document all available tools
Include authentication guidance
Handle rate limiting appropriately

Testing Requirements

Manual Testing Checklist

Test	Description	Required
Skill Triggers	Verify triggers activate the skill	Yes
API Examples	Validate against actual API docs	Yes
Command Arguments	Test all argument combinations	Yes
Error Cases	Verify error messages are helpful	Yes
MCP Connection	Test MCP server connectivity	If MCP

Testing Against Live API

When you have API access:

# 1. Configure credentials
export VENDOR_API_KEY="your-key"

# 2. Use REST client to test examples
# Verify all API examples in skills actually work

# 3. Document any discrepancies
# Update skill if API behavior differs from docs

Testing Without API Access

If you don't have API access:

Build from official API documentation
Mark contribution as "Documentation-based, untested"
Add note in PR requesting community testing
Look for community members with API access

Style Guide

Markdown Formatting

Element	Style
Headers	Use ATX style (`#`, `##`, `###`)
Lists	Use `-` for unordered, `1.` for ordered
Code	Use fenced code blocks with language
Tables	Use pipes with header separator
Links	Use reference-style for repeated links

Naming Conventions

Type	Convention	Example
Skill directories	kebab-case	`time-entries/`
Command files	kebab-case	`create-ticket.md`
Plugin names	kebab-case	`autotask-psa`
Environment vars	SCREAMING_SNAKE_CASE	`AUTOTASK_API_KEY`

API Example Standards

// Good - uses generic IDs and realistic structure
{
  "companyID": 12345,
  "title": "Email not working",
  "priority": 2,
  "status": 1
}

// Bad - uses real data
{
  "companyID": 987654321,
  "title": "Fix John's email",
  "contactEmail": "john@realcompany.com"
}

Documentation Language

Use active voice
Be concise but complete
Define acronyms on first use
Include examples for complex concepts
Write for MSP technicians (not developers)

Pull Request Process

Commit Message Format

Use Conventional Commits:

<type>(<scope>): <description>

Type	Use Case
`feat`	New feature (skill, command, plugin)
`fix`	Bug fix
`docs`	Documentation only
`style`	Formatting, no code change
`refactor`	Code restructuring
`test`	Adding tests
`chore`	Maintenance tasks

PR Title Format

Type	Format	Example
PRD	`[PRD] scope`	`[PRD] autotask/time-entries`
Feature	`feat(scope): description`	`feat(autotask): Add time entries skill`
Fix	`fix(scope): description`	`fix(autotask): Correct status codes`
Docs	`docs(scope): description`	`docs(readme): Add examples`

Review Process

Automated Checks - Formatting, links, structure
Peer Review - At least 1 approval required
Maintainer Review - For significant changes
Community Testing - For untested contributions

Getting Help

Channel	Use Case
GitHub Issues	Bug reports, feature requests
GitHub Discussions	Questions, ideas, community chat
PR Comments	Code review, implementation questions

Getting API Access

If you need API access for testing:

Vendor Partner Programs - Many vendors have free partner/developer tiers
Sandbox Environments - Ask vendor for test environment
Community Help - Post in discussions asking for testing help
Documentation-Based - Build from docs, mark as untested

New to Contributing?

Look for issues labeled:

good-first-issue - Great starting points
help-wanted - Community help needed
documentation - Lower barrier to entry

Code of Conduct

Please read our Code of Conduct before contributing.

We are committed to providing a welcoming and inclusive environment for all contributors regardless of background, identity, or experience level.

Questions? Open an issue or start a discussion.
Issues • Discussions

FilesExpand file tree

CONTRIBUTING.md

Latest commit

History