---
name: connector-onboarding
description: |
  Structured onboarding flow for building connectors. ONLY invoked via explicit /connector-onboarding command.

  **Triggers:**
  - "/connector-onboarding" slash command ONLY
  - DO NOT auto-trigger for "build a connector", "create connector", etc.

  **What it does:**
  1. Asks user to choose connector type (Agentic or Schema-Based)
  2. For Agentic: asks if creating new or extending existing
  3. Collects provider details
  4. Routes to appropriate build workflow
  5. Provides tips for future sessions
---

# Connector Onboarding Skill

## Overview

Guided onboarding flow that helps users choose the right connector-building approach. Routes to appropriate downstream workflows based on user selections.

## When to Use

**ONLY trigger when:** User explicitly runs `/connector-onboarding`

**DO NOT trigger for:**
- "build a connector" - just ask "What provider?" and proceed
- "build a schema based connector" - check for `stackone-unified-connectors` skill, ask provider, proceed
- "create a connector for X" - proceed directly with appropriate workflow
- Vague requests - ask simple clarifying questions, don't launch full onboarding

## Prerequisites

| Required | Description |
|----------|-------------|
| **User invocation** | Must be triggered via `/connector-onboarding` command only |

## Optional External Skills

Some connector types require additional skills from the StackOne plugin marketplace:

| Skill | Required For | Marketplace Plugin |
|-------|--------------|-------------------|
| `stackone-unified-connectors` | Schema-Based connectors (Path B) | `stackone-unified-connectors` |

**Checking skill availability:**
- Before routing to Path B, check if `stackone-unified-connectors` skill is available
- If not available, follow the "Missing Skill Flow" below

## Execution Flow

### Phase 1: Connector Type Selection

Use `AskUserQuestion` to present options:

| Option | Description |
|--------|-------------|
| **A) Agentic Actions** | Returns raw provider data as-is. Maximum API coverage and flexibility. |
| **B) Schema-Based** | Transforms data to your schema. Consistent output across providers. |
| **C) Skip Walkthrough** | For experienced users. Proceed directly with minimal prompts. |

### Phase 1.5: Agentic Sub-Selection (REQUIRED for Path A)

If user selected **Agentic Actions**, use `AskUserQuestion`:

| Option | Description |
|--------|-------------|
| **A) Create New** | Build from scratch. Full API discovery, configure auth, build all actions. |
| **B) Extend Existing** | Add actions to existing connector. Uses StackOne Agent for guided development. |

### Phase 2: Provider Details

Ask for:
1. **Provider name** (e.g., "BambooHR", "Slack")
2. **API version** (if applicable)

Then fork existing connector:

```bash
stackone pull <provider>
```

- **If succeeds:** Modify existing connector files
- **If fails:** Create new in `connectors/<provider>/`

---

## Workflow Routing

### Path A1: Create New Agentic Connector

**Route to:** `build-connector` skill

Steps:
1. Fork/Create connector files
2. Build and validate authentication
3. Connect account via StackOne dashboard
4. Research and discover all API actions
5. Build comprehensive YAML configuration
6. Validate and test all actions

### Path A2: Extend Existing Connector

**Route to:** StackOne Agent guided workflow

Steps:
1. Fork existing connector (`stackone pull <provider>`)
2. User describes use case for new actions
3. Agent analyzes existing configuration
4. Agent runs existing actions to scope API
5. Agent creates implementation plan
6. Agent writes new action configurations
7. Agent provides summary and validation steps

### Path B: Schema-Based Connector

**Requires:** `stackone-unified-connectors` skill (external plugin)

**Route to:** `stackone-unified-connectors` skill

**Before routing, check if skill is available:**

1. Check if `stackone-unified-connectors` skill exists in the user's available skills
2. If available → Route to the skill
3. If not available → Follow "Missing Skill Flow" below

**What the skill provides:**
- StackOne unified schema definitions (HRIS, ATS, CRM, etc.)
- Field mapping workflows
- Schema validation and testing
- Integration with StackOne unified API patterns

---

### Missing Skill Flow (Path B only)

If user selects Schema-Based but `stackone-unified-connectors` is not available:

**Step 1:** Inform the user:
> "Schema-based connectors require the `stackone-unified-connectors` skill, which provides StackOne's unified schemas and mapping workflows. This skill is available from the StackOne plugin marketplace."

**Step 2:** Use `AskUserQuestion` to present options:

| Option | Description |
|--------|-------------|
| **A) Add the skill** | I'll provide instructions for adding the skill from the marketplace. |
| **B) Build Agentic instead** | Switch to agentic connector (returns raw provider data, no schema mapping). |
| **C) Cancel** | Exit onboarding and return later. |

**If user selects "Add the skill":**

Provide these instructions:

```
To add the stackone-unified-connectors skill:

1. Install the plugin from the StackOne marketplace:

   Add to your Claude Code settings or .mcp.json:
   {
     "plugins": [
       "stackone-unified-connectors"
     ]
   }

2. Restart your Claude Code session

3. Run /connector-onboarding again and select Schema-Based

The skill will be available at: skills/stackone-unified-connectors/SKILL.md
```

**If user selects "Build Agentic instead":**
- Route to Path A (ask A1 vs A2 sub-selection)

**If user selects "Cancel":**
- Exit gracefully with a summary of what was discussed

### Path C: Skip Walkthrough

Proceed directly without additional prompts. Only ask when information is critically missing.

---

## End of Onboarding

After routing to appropriate workflow, inform user:

**Future session shortcuts:**
- Agentic Actions: "build a connector for [provider]"
- Extend existing: "add [actions] to the [provider] connector"
- Schema-Based: "start unified build for [provider]" (requires `stackone-unified-connectors` skill)

**Pro tip:** For schema-based builds, ensure you have the `stackone-unified-connectors` plugin installed for access to StackOne's unified schemas.

---

## Quick Reference

```bash
# Validate connector
stackone validate connectors/<provider>/<provider>.connector.s1.yaml

# Push connector
stackone push connectors/<provider>/<provider>.connector.s1.yaml --profile <profile>

# Test action
stackone run connectors/<provider>/<provider>.connector.s1.yaml --account-id <id> --action-id <action> --profile <profile>
```

## Key Principles

1. **Explicit invocation only** - Never auto-trigger, only via `/connector-onboarding`
2. **Route, don't duplicate** - Hand off to appropriate build skills
3. **Minimum friction** - Skip steps when information is already known
4. **Fork first** - Always try `stackone pull` before creating new
5. **Check dependencies** - Verify external skills are available before routing
6. **Graceful fallbacks** - Offer alternatives when required skills are missing

## Anti-Patterns

- Triggering for generic "build connector" requests
- Asking all questions when user already knows what they want
- Duplicating detailed build instructions (route to skills instead)
- Skipping Phase 1.5 for Agentic path
- Creating new connectors without trying to pull existing first
- Proceeding with schema-based build without checking for `stackone-unified-connectors` skill
- Attempting to inline unified schema definitions instead of routing to the proper skill