chore:updated onboarding skill#25
Conversation
![cubic-dev-ai[bot]](https://avatars.githubusercontent.com/in/1082092?s=60&v=4){kind=small}
There was a problem hiding this comment.
Pull request overview
Updates connector onboarding guidance and bumps a StackOne SDK dependency version as part of the repo’s onboarding/agent workflow documentation.
Changes:
- Bump
@stackone/connect-sdkdependency version inpackage.json/package-lock.json - Update onboarding docs to recommend pulling an existing connector with a new CLI flag and to extend via partials +
$ref - Add stronger guidance to avoid duplicating auth when extending a pulled connector
Reviewed changes
Copilot reviewed 3 out of 4 changed files in this pull request and generated 6 comments.
| File | Description |
|---|---|
| package.json | Bumps @stackone/connect-sdk version |
| package-lock.json | Updates lockfile entries for the bumped SDK version |
| CLAUDE.md | Updates schema-based onboarding workflow and CLI pull command example |
| .claude/skills/connector-onboarding.md | Updates onboarding skill steps for pulling/extension guidance and partial conventions |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| ```bash | ||
| # Pull existing connector from StackOne registry | ||
| npx @stackone/cli pull <provider> | ||
| npx @stackone/cli pull -c <provider> |
There was a problem hiding this comment.
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.
| npx @stackone/cli pull -c <provider> | |
| npx @stackone/cli pull --connector <provider> |
| │ 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 │ |
There was a problem hiding this comment.
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.
| │ └─ Run `npx @stackone/cli pull -c <provider>` to get existing │ | |
| │ └─ Run `npx @stackone/cli pull --connector <provider>` to get existing │ |
| 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`) |
There was a problem hiding this comment.
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.
| - **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`) |
|
|
||
| ```bash | ||
| stackone pull <provider> | ||
| stackone pull -c <provider> |
There was a problem hiding this comment.
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.
| stackone pull -c <provider> | |
| stackone pull --connector <provider> |
| - **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 | ||
| ``` | ||
|
|
There was a problem hiding this comment.
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.
| - **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
| **⚠️ 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`) |
There was a problem hiding this comment.
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.
| - **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`) |
Summary by cubic
Standardized connector onboarding to always pull existing configs with
stackone pull -c <provider>and extend via partials +$refwithout duplicating connectors or auth. Also bumped@stackone/connect-sdkto2.41.0.Refactors
-cflag when pulling connectors.$ref, never duplicate auth or keys.Dependencies
@stackone/connect-sdkfrom2.34.4to2.41.0.Written for commit f9c9382. Summary will update on new commits.