From f9c93821f54d23c3a55612f36a124ea98f30b58e Mon Sep 17 00:00:00 2001 From: Max Strivens <74908625+mstrivens@users.noreply.github.com> Date: Fri, 27 Mar 2026 15:14:23 +0000 Subject: [PATCH] updated onboarding skill --- .claude/skills/connector-onboarding.md | 44 +++++++++++++++++++++++--- CLAUDE.md | 21 ++++++++---- package-lock.json | 8 ++--- package.json | 2 +- 4 files changed, 59 insertions(+), 16 deletions(-) diff --git a/.claude/skills/connector-onboarding.md b/.claude/skills/connector-onboarding.md index 0e70ed7..977367d 100644 --- a/.claude/skills/connector-onboarding.md +++ b/.claude/skills/connector-onboarding.md @@ -127,7 +127,7 @@ Ask the user: **After getting the provider name, ALWAYS attempt to pull the existing connector from StackOne:** ```bash -stackone pull +stackone pull -c ``` This will: @@ -135,7 +135,11 @@ This will: - Place files in `connectors//` - 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 @@ -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 + stackone pull -c ``` - This downloads the existing connector configuration - Places files in `connectors//` - **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., `..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 + ``` + 2. **Set Up the StackOne Agent** - Ensure the StackOne Agent is configured in the project - Verify access to the connector configuration files @@ -297,10 +315,10 @@ If user selects **Schema-Based**, guide through this structured workflow: **First, pull existing connector from StackOne:** ```bash -stackone pull +stackone pull -c ``` -- **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 @@ -309,6 +327,22 @@ stackone pull - `connectors//.connector.s1.yaml` - `connectors//..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., `.unified-.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 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:** diff --git a/CLAUDE.md b/CLAUDE.md index f33562c..e2ede4c 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -57,8 +57,9 @@ When building Schema-Based connectors, follow this workflow: ``` ┌─────────────────────────────────────────────────────────────┐ │ 1. FORK CONNECTOR │ -│ └─ Run `npx @stackone/cli pull ` to get existing │ -│ └─ Fork existing or create new from template │ +│ └─ Run `npx @stackone/cli pull -c ` to get existing │ +│ └─ 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.) │ @@ -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 +npx @stackone/cli pull -c ``` -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., `.unified-.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 + If pull fails: Check local configs, then create new if needed: ```bash ls connectors/ | grep -i ``` -**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: diff --git a/package-lock.json b/package-lock.json index b761960..d541423 100644 --- a/package-lock.json +++ b/package-lock.json @@ -12,7 +12,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" @@ -3034,9 +3034,9 @@ } }, "node_modules/@stackone/connect-sdk": { - "version": "2.34.4", - "resolved": "https://registry.npmjs.org/@stackone/connect-sdk/-/connect-sdk-2.34.4.tgz", - "integrity": "sha512-XsqFbeMdbVT9KRWpH3774OrbUzkkcVBrtYaX55AlLVedS467Pq1KFVCA7jflN8IDlLFVYhsdpaaLJiCXb7+6Yg==", + "version": "2.41.0", + "resolved": "https://registry.npmjs.org/@stackone/connect-sdk/-/connect-sdk-2.41.0.tgz", + "integrity": "sha512-IT86l72rmLHDHoq+QLGEs9O2rTL1Mee7D4HT+CIRItQMeGOx+j7mtDkVn2XoM4qdJ9UOf4SCrh0/Z7cLJWkGfQ==", "dependencies": { "@stackone/core": "*", "@stackone/defender": "*", diff --git a/package.json b/package.json index 344af70..653f78f 100644 --- a/package.json +++ b/package.json @@ -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"