assistant-builder

Assistant Builder

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

Quick Reference

I want to...	Script	Type
Create new project	`scaffold_project.py`	Interactive
Add skill to project	`add_skill.py`	Interactive
Generate CLI library	`scaffold_library.py`	Interactive
Validate structure	`validate_project.py`	Check
Migrate old project	`migrate_project.py`	Transform
Show reference patterns	`show_reference.py`	Info
List templates	`list_templates.py`	Info
Show template	`show_template.py`	Info

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:

Project	Skills	Type	Strength
Jira-Assistant-Skills	14	Custom Library	Mock architecture
Confluence-Assistant-Skills	17	Custom Library	Risk documentation
Splunk-Assistant-Skills	14	Custom Library	Test infrastructure

# 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:

Risk	Symbol	Description
Safe	`-`	Read-only operations
Caution	`⚠️`	Single-item modifications
Warning	`⚠️⚠️`	Bulk/destructive operations
Danger	`⚠️⚠️⚠️`	Irreversible operations

About this skill