Skip to content

chore:updated onboarding skill #25

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
mstrivens merged 1 commit into from
Mar 27, 2026
+59 −16
Merged

chore:updated onboarding skill #25

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
44 changes: 39 additions & 5 deletions .claude/skills/connector-onboarding.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -127,15 +127,19 @@ Ask the user:
**After getting the provider name, ALWAYS attempt to pull the existing connector from StackOne:**

```bash
stackone pull <provider>
stackone pull -c <provider>
Copy link

Copilot AI Mar 27, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

stackone pull -c <provider> is introduced here, but other repo docs/reference materials still show stackone pull <provider>/npx @stackone/cli pull <provider> without -c, and the official CLI reference documents pull --connector <provider>. Please confirm the correct CLI syntax and keep onboarding docs consistent so new users don’t hit a command error.

Suggested change
stackone pull -c <provider>
stackone pull --connector <provider>

Copilot uses AI. Check for mistakes.
```

This will:
- Download the existing connector if it exists in StackOne's registry
- Place files in `connectors/<provider>/`
- Provide a foundation to build upon

**If pull succeeds**: Fork and modify the existing connector
**If pull succeeds**:
- Create a NEW partial file for your new actions
- Add a `$ref` to the existing connector to include your partial
- **DO NOT** create a separate connector or duplicate auth config

**If pull fails** (connector doesn't exist): Check local configs and create new if needed:
```bash
ls connectors/ | grep -i <provider>
Expand Down Expand Up @@ -223,12 +227,26 @@ If user selects **Extend Existing Connector**, follow the StackOne Agent workflo
1. **Fork Existing Connector**
```bash
# Pull the existing connector from StackOne
stackone pull <provider>
stackone pull -c <provider>
```
- This downloads the existing connector configuration
- Places files in `connectors/<provider>/`
- **If pull fails**: The connector doesn't exist - redirect to Path A1 (Create New Connector)

**⚠️ CRITICAL: When extending a forked connector:**
- **DO NOT** create a new connector file with a different key
- **DO NOT** duplicate the authentication config
- **DO** create a new partial file for your new actions (e.g., `<provider>.<resource>.s1.partial.yaml`)
- **DO** add a `$ref` to the existing connector file to include your new partial
- **DO** leverage the existing auth config as-is

Example structure after extending:
```
connectors/bamboohr/
bamboohr_v1-0-0.s1.yaml # Existing pulled connector (may need $ref added)
bamboohr.new-actions.s1.partial.yaml # Your NEW partial with new actions
```

Comment on lines +239 to +249
Copy link

Copilot AI Mar 27, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The newly added examples mix partial naming conventions (e.g., <provider>.<resource>.s1.partial.yaml vs <provider>.unified-<resource>.s1.partial.yaml). Please standardize the partial filename pattern and corresponding $ref guidance so contributors create files that match the repo’s established structure.

Suggested change
- **DO** create a new partial file for your new actions (e.g., `<provider>.<resource>.s1.partial.yaml`)
- **DO** add a `$ref` to the existing connector file to include your new partial
- **DO** leverage the existing auth config as-is
Example structure after extending:
```
connectors/bamboohr/
bamboohr_v1-0-0.s1.yaml # Existing pulled connector (may need $ref added)
bamboohr.new-actions.s1.partial.yaml # Your NEW partial with new actions
```
- **DO** create a new partial file for your new actions (e.g., `<provider>.unified-<resource>.s1.partial.yaml`)
- **DO** add a `$ref` to the existing connector file to include your new partial (see example below)
- **DO** leverage the existing auth config as-is
Example structure after extending:

connectors/bamboohr/
bamboohr.unified-hris.s1.yaml # Existing pulled connector (add $ref to partial)
bamboohr.unified-hris.s1.partial.yaml # Your NEW partial with additional actions


Example `$ref` inside `bamboohr.unified-hris.s1.yaml`:
```yaml
actions:
  $ref:
    - ./bamboohr.unified-hris.s1.partial.yaml

Copilot uses AI. Check for mistakes.
2. **Set Up the StackOne Agent**
- Ensure the StackOne Agent is configured in the project
- Verify access to the connector configuration files
Expand Down Expand Up @@ -297,10 +315,10 @@ If user selects **Schema-Based**, guide through this structured workflow:

**First, pull existing connector from StackOne:**
```bash
stackone pull <provider>
stackone pull -c <provider>
```

- **If pull succeeds**: Review and modify the existing connector files
- **If pull succeeds**: Review the existing connector files
- **If pull fails**: Check local configs and create new if needed:
```bash
ls connectors/ | grep -i <provider>
Expand All @@ -309,6 +327,22 @@ stackone pull <provider>
- `connectors/<provider>/<provider>.connector.s1.yaml`
- `connectors/<provider>/<provider>.<resource>.s1.partial.yaml`

**⚠️ CRITICAL: When adding unified actions to a forked connector:**
- **DO NOT** create a new connector file with a different key
- **DO NOT** duplicate the authentication config
- **DO** create a new partial file for your unified actions (e.g., `<provider>.unified-<resource>.s1.partial.yaml`)
Copy link

Copilot AI Mar 27, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This section uses the <provider>.unified-<resource>.s1.partial.yaml naming, but earlier sections/examples use <provider>.<resource>.s1.partial.yaml. Please make this consistent across the onboarding skill (and ideally match the repo’s existing connector partial naming) to reduce confusion.

Suggested change
- **DO** create a new partial file for your unified actions (e.g., `<provider>.unified-<resource>.s1.partial.yaml`)
- **DO** create a new partial file for your unified actions (e.g., `<provider>.<resource>.s1.partial.yaml`)

Copilot uses AI. Check for mistakes.
- **DO** add a `$ref` to the existing connector file to include your new partial
- **DO** leverage the existing auth config as-is

Example structure after adding unified actions:
```
connectors/bamboohr/
bamboohr_v1-0-0.s1.yaml # Existing pulled connector (add $ref to it)
bamboohr.unified-documents.s1.partial.yaml # Your NEW partial with unified actions
```

The existing connector already has working auth - don't recreate it.

### Step 2: Build Auth

**Before any action work, validate authentication:**
Expand Down
21 changes: 15 additions & 6 deletions CLAUDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -57,8 +57,9 @@ When building Schema-Based connectors, follow this workflow:
```
┌─────────────────────────────────────────────────────────────┐
│ 1. FORK CONNECTOR │
│ └─ Run `npx @stackone/cli pull <provider>` to get existing │
│ └─ Fork existing or create new from template │
│ └─ Run `npx @stackone/cli pull -c <provider>` to get existing │
Copy link

Copilot AI Mar 27, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This workflow diagram uses npx @stackone/cli pull -c <provider>, but other repo docs/reference materials use pull <provider> and the official CLI reference documents pull --connector <provider>. Please confirm the correct CLI syntax and update the diagram to match, otherwise the onboarding flow may start with a command that fails.

Suggested change
│ └─ Run `npx @stackone/cli pull -c <provider>` to get existing │
│ └─ Run `npx @stackone/cli pull --connector <provider>` to get existing │

Copilot uses AI. Check for mistakes.
│ └─ Create NEW partial for your actions (don't duplicate auth) │
│ └─ Add $ref to existing connector to include your partial │
├─────────────────────────────────────────────────────────────┤
│ 2. BUILD AUTH │
│ └─ Configure authentication (API Key, OAuth, etc.) │
Expand Down Expand Up @@ -103,22 +104,30 @@ When building Schema-Based connectors, follow this workflow:
First, pull the existing connector from StackOne:
```bash
# Pull existing connector from StackOne registry
npx @stackone/cli pull <provider>
npx @stackone/cli pull -c <provider>
Copy link

Copilot AI Mar 27, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

pull -c <provider> is introduced here, but the repo’s existing CLI reference docs still show npx @stackone/cli pull <provider-name> (no -c), and the official CLI reference documents pull --connector <provider> instead. Please align on the correct syntax/flag and update this command (and any other references) to avoid broken onboarding instructions.

Suggested change
npx @stackone/cli pull -c <provider>
npx @stackone/cli pull --connector <provider>

Copilot uses AI. Check for mistakes.
```

If pull succeeds: Fork and modify the existing connector
If pull succeeds:
- **DO NOT** create a new connector file with a different key
- **DO NOT** duplicate the authentication config
- **DO** create a new partial file for your unified actions (e.g., `<provider>.unified-<resource>.s1.partial.yaml`)
Copy link

Copilot AI Mar 27, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The example partial filename pattern here (<provider>.unified-<resource>.s1.partial.yaml) is inconsistent with other guidance in this repo (e.g., connectors/ashby/ashby.candidates.s1.partial.yaml and other sections that use <provider>.<resource>.s1.partial.yaml). Please pick one convention and use it consistently to avoid confusing contributors.

Suggested change
- **DO** create a new partial file for your unified actions (e.g., `<provider>.unified-<resource>.s1.partial.yaml`)
- **DO** create a new partial file for your unified actions (e.g., `<provider>.<resource>.s1.partial.yaml`)

Copilot uses AI. Check for mistakes.
- **DO** add a `$ref` to the existing connector file to include your new partial
- **DO** leverage the existing auth config as-is

If pull fails: Check local configs, then create new if needed:
```bash
ls connectors/ | grep -i <provider>
```

**Step 2: Build Auth**
**Step 2: Build Auth** (only if creating new connector)

Before anything else, configure and validate authentication:
If creating a new connector (not extending existing), configure and validate authentication:
- Determine auth type (API Key, OAuth 2.0, etc.)
- Configure `authentication` section in connector YAML
- Test auth works with a simple action

**If extending an existing connector, skip this step** - the pulled connector already has working auth.

**Step 3: Connect Account**

Push connector and create a test account:
Expand Down
8 changes: 4 additions & 4 deletions package-lock.json
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 1 addition & 1 deletion package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@
"dependencies": {
"@stackone/agent-config": "^1.4.0",
"@stackone/cli": "1.24.0",
"@stackone/connect-sdk": "2.34.4",
"@stackone/connect-sdk": "2.41.0",
"@stackone/core": "2.27.2",
"@stackone/expressions": "0.25.0",
"@stackone/utils": "0.19.0"
Expand Down
Loading