Contributing to Destinations API Claude Plugin

Thank you for your interest in contributing to the Destinations API Claude Plugin! This guide will help you get started with plugin development, testing, and submitting contributions.

Getting Started
Development Workflow
Plugin Architecture
Adding New Features
Testing Guidelines
Code Style
Submitting Changes
Release Process

Getting Started

Prerequisites

Claude Code CLI installed
Git for version control
Basic understanding of Claude Code plugin architecture
Familiarity with telecommunications concepts (MCC/MNC, E.164, billing increments)

Development Setup

Fork and clone the repository:

git clone https://github.com/YOUR_USERNAME/destinations-api-claude-plugin.git
cd destinations-api-claude-plugin

Create a local development marketplace:

# Navigate to parent directory
cd ..
mkdir dev-marketplace
cd dev-marketplace
mkdir .claude-plugin

# Create marketplace manifest
cat > .claude-plugin/marketplace.json << 'EOF'
{
  "name": "dev-marketplace",
  "metadata": {
    "description": "Local development marketplace for testing"
  },
  "owner": {
    "name": "Developer"
  },
  "plugins": [
    {
      "name": "destinations-api",
      "source": "../destinations-api-claude-plugin",
      "description": "Destinations API plugin (development version)"
    }
  ]
}
EOF

Install the development plugin:

# From parent directory containing both dev-marketplace and plugin
claude

# In Claude Code:
/plugin marketplace add ./dev-marketplace
/plugin install destinations-api@dev-marketplace

Verify installation:

# Check that commands appear
/help

# Test a command
/destinations-api:destinations-search Cambodia

Development Workflow

Iterative Development

After making changes to the plugin:

# In Claude Code session:

# 1. Uninstall current version
/plugin uninstall destinations-api@dev-marketplace

# 2. Reinstall to pick up changes
/plugin install destinations-api@dev-marketplace

# 3. Test your changes
/help  # Verify commands appear
/destinations-api:destinations-search test  # Test functionality

Testing Changes

Always test these aspects after modifications:

Command availability - Commands appear in /help
Agent availability - Agents appear in /agents (if applicable)
Functionality - Commands execute without errors
API integration - WebFetch calls succeed
Response formatting - Output is clear and well-formatted
Error handling - Graceful handling of API errors

Plugin Architecture

Directory Structure

destinations-api-claude-plugin/
├── .claude-plugin/
│   ├── plugin.json              # Plugin metadata
│   └── marketplace.json         # Marketplace listing (for GitHub distribution)
├── commands/                     # Slash commands
│   ├── destinations-search.md
│   ├── billing-updates.md
│   ├── lookup-number.md
│   └── compare-billing.md
├── agents/                       # Specialized agents
│   ├── telecom-routing-advisor.md
│   ├── billing-trend-analyst.md
│   └── fraud-detection-helper.md
├── hooks/                        # Event hooks
│   └── hooks.json
├── docs/                         # Documentation
│   ├── API-REFERENCE.md
│   └── CONTRIBUTING.md
├── README.md                     # User-facing documentation
├── CLAUDE.md                     # Developer instructions for Claude Code
├── CHANGELOG.md                  # Version history
└── LICENSE                       # License information

Component Types

1. Slash Commands (`commands/*.md`)

Slash commands are user-invoked operations that Claude Code expands into full prompts.

Structure:

---
description: Brief description shown in /help
---

# Command Name

Instructions for Claude Code on how to execute this command...

Key Elements:

Frontmatter: YAML metadata with description field
Instructions: Step-by-step guidance for Claude Code
API usage: How to construct WebFetch calls
Output format: How to present results to user

Example:

---
description: Search destinations by country or prefix
---

# Search Command

1. Parse user query for country name or prefix
2. Construct API URL: https://destinations-api.telecomsxchange.com/search/
3. Use WebFetch tool to query API
4. Format results as table
5. Explain billing increments

2. Agents (`agents/*.md`)

Agents are specialized assistants that Claude Code can use autonomously for complex tasks.

Structure:

---
description: What this agent specializes in
---

# Agent Name

## Your Capabilities
- List of specialized skills

## How to Use the API
- API endpoints and parameters

## Analysis Framework
- Step-by-step methodology

## Output Format
- How to present analysis

When to Create an Agent:

Multi-step analysis workflows
Complex decision-making processes
Tasks requiring domain expertise
Operations that benefit from specialized context

3. Hooks (`hooks/hooks.json`)

Hooks execute shell commands in response to Claude Code events.

Structure:

{
  "hooks": [
    {
      "name": "hook-identifier",
      "description": "What this hook does",
      "event": "event-name",
      "command": "shell command to execute"
    }
  ]
}

Available Events:

before-web-fetch - Before API requests
after-web-fetch - After API responses
user-prompt-submit - When user submits a prompt
before-tool-use - Before any tool execution
after-tool-use - After any tool execution

Use Cases:

Rate limit reminders
Logging and monitoring
Input validation
Response caching suggestions

Adding New Features

Adding a New Slash Command

Create command file:

touch commands/my-new-command.md

Write command definition:

---
description: Brief description for /help
---

# My New Command

You are helping the user [describe purpose]. Follow these steps:

1. **Parse the user's query** to identify:
   - [parameter 1]
   - [parameter 2]

2. **Construct the API request:**
   - Endpoint: `https://destinations-api.telecomsxchange.com/[endpoint]`
   - Parameters: [list parameters]

3. **Use the WebFetch tool:**

WebFetch(url, prompt)


4. **Present the results:**
- [format specification]

**Example queries to handle:**
- "Query example 1"
- "Query example 2"

Test the command:

# Reinstall plugin
/plugin uninstall destinations-api@dev-marketplace
/plugin install destinations-api@dev-marketplace

# Verify it appears
/help

# Test it
/destinations-api:my-new-command test query

Adding a New Agent

Create agent file:

touch agents/my-new-agent.md

Write agent definition:

---
description: What this agent specializes in
---

# My New Agent

You are a specialized agent for [purpose]. Your role is to [detailed description].

## Your Capabilities

1. **Capability 1**
   - Specific skill
   - Use case

2. **Capability 2**
   - Specific skill
   - Use case

## How to Use the Destinations API

[API usage instructions specific to this agent's needs]

## Analysis Framework

When [performing task]:

1. **Step 1** - [description]
2. **Step 2** - [description]
3. **Step 3** - [description]

## Output Format

Present analysis as:

[Example output format]


Always cite specific data points and provide clear recommendations.

Test the agent:

# Reinstall plugin
/plugin uninstall destinations-api@dev-marketplace
/plugin install destinations-api@dev-marketplace

# Test by asking Claude to use it
# In Claude Code: "Please use the my-new-agent to analyze..."

Adding a Hook

Edit hooks configuration:

# Open hooks/hooks.json

Add new hook:

{
  "hooks": [
    {
      "name": "my-new-hook",
      "description": "What this hook does",
      "event": "before-web-fetch",
      "command": "echo 'Hook executed' >&2"
    }
  ]
}

Available variables in hook commands:

$URL - URL being fetched (web-fetch events)
$PROMPT - User's prompt text (prompt-submit events)
$TOOL - Tool being used (tool-use events)

Test the hook:

# Reinstall plugin
/plugin uninstall destinations-api@dev-marketplace
/plugin install destinations-api@dev-marketplace

# Trigger the event (e.g., make a web fetch request)

Testing Guidelines

Manual Testing Checklist

Before submitting changes, test:

Plugin installs without errors
All commands appear in /help
Commands execute successfully with valid inputs
Error handling works for invalid inputs
API rate limits are respected (test with multiple requests)
Output formatting is clear and consistent
Documentation matches actual behavior
Hooks execute at appropriate times (if modified)

Testing API Integration

# Test search endpoint
/destinations-api:destinations-search Cambodia

# Test billing updates
/destinations-api:billing-updates recent

# Test phone lookup
/destinations-api:lookup-number +855123456789

# Test comparison
/destinations-api:compare-billing Cambodia vs Thailand

Testing Edge Cases

Empty results - Search for non-existent prefix
Rate limiting - Make many requests quickly
Invalid input - Malformed phone numbers, invalid countries
Pagination - Search with many results (e.g., United States)
Special characters - Countries with spaces, symbols

Testing Agents

Agents are tested by asking Claude Code to invoke them:

User: Please use the telecom routing advisor agent to analyze routing for Cambodia mobile traffic

Expected: Agent activates and performs analysis using Destinations API

Code Style

Markdown Formatting

Use consistent heading levels
Include code blocks with language tags
Use tables for structured data
Keep line length reasonable (80-120 characters)

Command Writing Style

Imperative voice - "Parse the query", "Construct the URL"
Numbered steps - Clear sequential instructions
Bold key terms - Emphasize important concepts
Examples - Provide concrete usage examples

Documentation Style

Clear headings - Descriptive and hierarchical
Complete examples - Show full request/response
Consistent terminology - Use same terms throughout
User-focused - Write for plugin users, not just developers

Submitting Changes

Pull Request Process

Create a feature branch:

git checkout -b feature/my-new-feature

Make your changes and commit:

git add .
git commit -m "Add: New feature description"

Commit Message Format:

Type: Brief description

Detailed explanation of changes (if needed)

- Bullet points for key changes
- Related issue numbers (#123)

Commit Types:

Add: - New features, commands, agents
Fix: - Bug fixes
Update: - Modifications to existing features
Docs: - Documentation changes
Refactor: - Code restructuring without behavior changes
Test: - Testing improvements

Push to your fork:

git push origin feature/my-new-feature

Create pull request:

Go to GitHub repository
Click "New Pull Request"
Select your feature branch
Fill out PR template with:
- Description of changes
- Testing performed
- Screenshots (if UI changes)
- Related issues

Pull Request Checklist

Release Process

Version Numbering

This project follows Semantic Versioning:

MAJOR (1.x.x) - Breaking changes
MINOR (x.1.x) - New features, backward compatible
PATCH (x.x.1) - Bug fixes, backward compatible

Creating a Release

Update version in plugin.json:

{
  "name": "destinations-api",
  "version": "1.1.0",
  ...
}

Update CHANGELOG.md:

## [1.1.0] - 2025-10-XX

### Added
- New feature description

### Fixed
- Bug fix description

### Changed
- Modification description

Update README.md if needed (examples, features)
Commit version bump:

git add .
git commit -m "Release: v1.1.0"
git tag v1.1.0
git push origin main --tags

Create GitHub release:

Go to repository releases
Create new release from tag
Copy CHANGELOG entry to release notes
Publish release

Best Practices

API Usage

Cache responses when possible to reduce API calls
Use pagination with high limits instead of multiple requests
Respect rate limits (100 req/min)
Handle errors gracefully with user-friendly messages

User Experience

Clear output - Use tables, bullet points, clear formatting
Helpful errors - Suggest solutions, not just report problems
Consistent style - Match existing command output format
Complete information - Include all relevant data in results

Documentation

Keep docs in sync - Update docs when changing functionality
Provide examples - Show real usage, not just syntax
Explain concepts - Don't assume user knowledge
Link resources - Reference API docs, standards (E.164, etc.)

Getting Help

Resources

API Documentation: https://destinations-api.telecomsxchange.com/docs
Claude Code Docs: https://docs.claude.com/en/docs/claude-code
Plugin Development: See CLAUDE.md for developer guidance

Questions and Issues

Bug reports: Open an issue on GitHub
Feature requests: Open an issue with [Feature Request] tag
Questions: Use GitHub Discussions

Community

Review existing issues and PRs
Help answer questions from other contributors
Share your use cases and feedback

License

By contributing, you agree that your contributions will be licensed under the same license as the project (see LICENSE file).

Thank you for contributing to the Destinations API Claude Plugin!

Your contributions help make telecommunications data more accessible to developers worldwide.

FilesExpand file tree

CONTRIBUTING.md

Latest commit

History

CONTRIBUTING.md

File metadata and controls

Contributing to Destinations API Claude Plugin

Table of Contents

Getting Started

Prerequisites

Development Setup

Development Workflow

Iterative Development

Testing Changes

Plugin Architecture

Directory Structure

Component Types

1. Slash Commands (commands/*.md)

2. Agents (agents/*.md)

3. Hooks (hooks/hooks.json)

Adding New Features

Adding a New Slash Command

Adding a New Agent

Adding a Hook

Testing Guidelines

Manual Testing Checklist

Testing API Integration

Testing Edge Cases

Testing Agents

Code Style

Markdown Formatting

Command Writing Style

Documentation Style

Submitting Changes

Pull Request Process

Pull Request Checklist

Release Process

Version Numbering

Creating a Release

Best Practices

API Usage

User Experience

Documentation

Getting Help

Resources

Questions and Issues

Community

License

1. Slash Commands (`commands/*.md`)

2. Agents (`agents/*.md`)

3. Hooks (`hooks/hooks.json`)