Assistant Builder

Build production-ready Claude Code plugin projects that wrap CLIs or APIs.

Quick Reference

Project Types

1. CLI Wrapper Projects

Wrap an existing CLI tool (like glab, gh, aws, kubectl):

python scaffold_project.py \
  --type cli-wrapper \
  --name "GitLab-Assistant-Skills" \
  --topic "gitlab" \
  --cli-tool "glab" \
  --cli-install "brew install glab"

Generated structure:

• .claude-plugin/ with plugin.json
• skills/gitlab-assistant/ (hub router)
• skills/gitlab-{resource}/ per skill
• skills/shared/docs/ (SAFEGUARDS, QUICK_REFERENCE)
• No library package (uses existing CLI)

2. Custom Library Projects

Build new CLI for an API (like Jira, Confluence, Splunk):

python scaffold_project.py \
  --type custom-library \
  --name "MyAPI-Assistant-Skills" \
  --topic "myapi" \
  --api "My API" \
  --api-url "https://api.example.com" \
  --auth api_key

Generated structure:

• myapi-assistant-skills-lib/ with:

- pyproject.toml with CLI entry point - HTTP client, error handler, validators - Click CLI commands structure

• .claude-plugin/ with plugin.json
• skills/ (pure documentation)
• requirements.txt referencing library

3. Hybrid Projects

Wrap CLI and extend with custom functionality:

python scaffold_project.py \
  --type hybrid \
  --name "GitHub-Assistant-Skills" \
  --topic "github" \
  --cli-tool "gh" \
  --api-url "https://api.github.com"

Adding Skills

cd /path/to/project
python add_skill.py \
  --name "merge-request" \
  --description "Merge request operations" \
  --operations "list,get,create,update,delete"

Generated:

• skills/{topic}-{name}/SKILL.md with CLI command references
• skills/{topic}-{name}/docs/ subdirectory
• Updates to plugin.json

Generating CLI Libraries

For custom library projects, scaffold a complete Python package:

python scaffold_library.py \
  --name "myapi-assistant-skills-lib" \
  --topic "myapi" \
  --api "My API" \
  --api-url "https://api.example.com"

Generated:

• Complete Click CLI with commands
• HTTP client with retry/pagination
• Configuration management
• Error handling hierarchy
• Output formatters
• Input validators
• Test infrastructure

Validating Projects

python validate_project.py /path/to/project

Checks:

• .claude-plugin/plugin.json exists
• VERSION file present
• Root conftest.py exists
• No scripts in skills/ directories
• Hub/router skill present
• Risk levels documented
• Shared documentation complete

Migrating Existing Projects

Transform old .claude/skills/ structure to new .claude-plugin/ pattern:

# Analyze and preview
python migrate_project.py /path/to/old/project --dry-run

# Migrate in place (creates backup)
python migrate_project.py /path/to/old/project

# Migrate to new location
python migrate_project.py /path/to/old/project --output /path/to/new/project

Transforms:

• Moves skills from .claude/skills/ to skills/
• Creates .claude-plugin/ with plugin.json
• Generates VERSION, conftest.py, pytest.ini
• Creates shared documentation

Reference Projects

Learn from production implementations:

# Show patterns from specific project
python show_reference.py --project jira --topic client-pattern

# Compare patterns across projects
python show_reference.py --topic testing-patterns --compare-all

# List available topics
python show_reference.py --list-topics

Production Architecture

The production pattern is thin documentation wrappers around a publishable CLI library:

my-project/
├── .claude-plugin/           # Plugin manifest
│   ├── plugin.json
│   ├── marketplace.json
│   └── commands/             # Slash commands
├── skills/                    # Pure documentation
│   ├── {topic}-assistant/    # Hub/router skill
│   ├── {topic}-{skill}/      # Feature skills (SKILL.md only)
│   └── shared/docs/          # SAFEGUARDS, QUICK_REFERENCE
├── {topic}-assistant-skills-lib/  # Optional: CLI library
├── conftest.py               # Root test fixtures
├── pytest.ini                # Test configuration
├── VERSION                   # Single version source
└── CLAUDE.md                # Project guidance

Key principles:

• Skills are documentation, not code
• Scripts live in separate library packages
• Hub/router skill routes requests
• Risk levels documented everywhere
• VERSION is single source of truth

Risk Level System

All operations marked with risk indicators:

Related Documentation

• [Quick Reference](./docs/QUICK-REFERENCE.md)
• [Workflows](./docs/WORKFLOWS.md)
• [Examples](./docs/EXAMPLES.md)
• [Migration Guide](./docs/MIGRATION.md)