feat(claude): add api-version-upgrade skill by harsh-joshi99 · Pull Request #3716 · segmentio/action-destinations

harsh-joshi99 · 2026-04-13T06:03:07Z

Summary

Adds the api-version-upgrade Claude skill to claude/skills/ so all contributors have access to it directly from the repo
Includes SKILL.md (full workflow) and three reference docs: common patterns, feature flags best practices, and testing guide

What the skill does

Automates the complete workflow for upgrading API versions in action destinations:

Detects current version, fetches and analyzes changelogs for breaking changes
Implements upgrades behind feature flags using the versioning-info.ts canary pattern
Updates all API call sites to use getApiVersion(features)
Adds tests for both stable and canary versions
Creates a PR with breaking changes documentation

Test plan

Verify skill files are present at claude/skills/api-version-upgrade/
Confirm skill is invocable via /api-version-upgrade in Claude Code sessions within this repo

🤖 Generated with Claude Code

Adds the api-version-upgrade Claude skill to the repo so it's available to all contributors working in this codebase. Includes the main SKILL.md workflow and reference docs for common patterns, feature flags, and testing. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Copilot

Pull request overview

Adds a new Claude skill (api-version-upgrade) to standardize and automate API version upgrade work for action destinations, including feature-flag canary patterns, changelog analysis, and testing guidance.

Changes:

Introduces claude/skills/api-version-upgrade/SKILL.md with an end-to-end upgrade workflow (steps, commands, templates).
Adds reference docs covering common versioning patterns, feature-flag best practices, and a testing guide for upgrades.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 6 comments.

File	Description
`claude/skills/api-version-upgrade/SKILL.md`	Main workflow doc for performing API version upgrades behind a feature flag, including testing + PR creation steps
`claude/skills/api-version-upgrade/references/testing-guide.md`	Guidance on running/updating tests during API upgrades
`claude/skills/api-version-upgrade/references/feature-flags.md`	Reference on feature-flag lifecycle, naming, rollout/monitoring guidance
`claude/skills/api-version-upgrade/references/common-patterns.md`	Catalog of versioning patterns used in destinations, with example snippets

Copilot · 2026-04-13T06:08:57Z

+#### Run All Destination Tests
+
+```bash
+# From repository root
+TZ=UTC yarn test --testPathPattern="destinations/{destination}" --no-coverage
+```


The test commands here likely won’t work as written: from repo root, yarn test runs NX (nx run-many -t test) and doesn’t accept Jest’s --testPathPattern the way these examples assume. Repo guidance uses TZ=UTC yarn cloud test --testPathPattern=src/destinations/<destination> / yarn cloud jest --testPathPattern="<destination>" (see CLAUDE.md). Update these commands (and the pattern string) to match the repo’s actual test entrypoints/paths (src/destinations/...).

Copilot · 2026-04-13T06:08:57Z

+# NOTE: `yarn cloud jest --testPathPattern` fails in newer Jest versions with
+# "Option was replaced by --testPathPatterns". Use npx jest directly instead:
+cd packages/destination-actions && TZ=UTC npx jest "{destination}" --no-coverage


This note appears inaccurate for this repo: yarn cloud jest --testPathPattern=... is explicitly documented in CLAUDE.md as the way to run a specific cloud destination test suite, and @segment/action-destinations is still on Jest 27 where --testPathPattern is valid. Suggest removing/adjusting this warning and using the documented command (also keeping TZ=UTC).

Suggested change

# NOTE: `yarn cloud jest --testPathPattern` fails in newer Jest versions with

# "Option was replaced by --testPathPatterns". Use npx jest directly instead:

cd packages/destination-actions && TZ=UTC npx jest "{destination}" --no-coverage

TZ=UTC yarn cloud jest --testPathPattern="{destination}" --no-coverage

Copilot · 2026-04-13T06:08:58Z

+### Run the validation script
+
+```bash
+KLAVIYO_TEST_API_KEY=xxx \
+KLAVIYO_TEST_LIST_ID=your-list-id \
+npx ts-node packages/destination-actions/src/destinations/{destination}/__validation__/validate.ts
+```


This step references a destination-local validation script at src/destinations/{destination}/__validation__/validate.ts, but there are currently no __validation__ directories under packages/destination-actions/src/destinations in this repo. Either make this step explicitly about creating that script (with a recommended template/location), or remove it to avoid sending contributors to a non-existent path.

Copilot · 2026-04-13T06:08:58Z

+- Writes `__validation__/validation-report.md` — **commit this to the PR**
+- Exits non-zero if any structural differences are found
+
+### Expected outcome
+
+```
+✅ All N endpoints are structurally identical across both revisions. Safe to promote canary.
+```
+
+If differences are found, review `validation-report.md` for the specific fields that changed and update the implementation accordingly before proceeding.
+
+### Notes
+
+- `validation-report.md` is gitignored by default but should be **force-added** to the upgrade PR as evidence
+- Delete it during the cleanup phase (Step 8) when the canary is promoted to stable


The guidance to commit __validation__/validation-report.md and to “force-add” it because it’s “gitignored by default” doesn’t match the repo: .gitignore doesn’t ignore that path, and committing generated reports can easily leak PII or sensitive API responses. Recommend changing this to (a) avoid claiming it’s gitignored, and (b) only attach a sanitized summary to the PR description or a gist/artifact, unless there’s an established repo convention for committing these reports.

Copilot · 2026-04-13T06:08:58Z

+// AFTER (functions.ts) - add feature flag support
+export const FLAGON_NAME = 'klaviyo-canary-version'
+export function getApiRevision(features?: Features): string {
+  return features && features[FLAGON_NAME] ? KLAVIYO_CANARY_API_REVISION : KLAVIYO_API_REVISION


The Klaviyo migration example is internally inconsistent: it defines KLAVIYO_API_VERSION / KLAVIYO_CANARY_API_VERSION, but getApiRevision() returns KLAVIYO_CANARY_API_REVISION / KLAVIYO_API_REVISION (which aren’t defined in the snippet). Align the constant names (either *_API_VERSION everywhere or *_API_REVISION everywhere) so the example is copy/paste-correct.

Suggested change

return features && features[FLAGON_NAME] ? KLAVIYO_CANARY_API_REVISION : KLAVIYO_API_REVISION

return features && features[FLAGON_NAME] ? KLAVIYO_CANARY_API_VERSION : KLAVIYO_API_VERSION

Copilot · 2026-04-13T06:08:58Z

+**MANDATORY**: At the start of every step, print the step header exactly as shown below. At the end of every step, print the completion line. Do not summarize inline — use the structured format consistently.
+
+### Step header format
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+[STEP N/8] <STEP TITLE>
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```


The “print the step header exactly as shown” requirement says [STEP N/8], but the workflow includes Step 0 and Step 8 (and even a Step 5.5). That makes both the denominator (/8) and the allowed shape of N inconsistent. Suggest updating the standard to match the actual step numbering (e.g. /9 with integer steps, or explicitly allow 5.5 and explain how totals are counted).

Copilot AI review requested due to automatic review settings April 13, 2026 06:03

github-actions bot added the team:segment-core label Apr 13, 2026

Copilot started reviewing on behalf of harsh-joshi99 April 13, 2026 06:03 View session

harsh-joshi99 marked this pull request as draft April 13, 2026 06:04

Copilot AI reviewed Apr 13, 2026

View reviewed changes

joe-ayoub-segment added the not-partner-eng-review (cloud) label Apr 13, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(claude): add api-version-upgrade skill#3716

feat(claude): add api-version-upgrade skill#3716
harsh-joshi99 wants to merge 1 commit intomainfrom
add-api-version-upgrade-skill

harsh-joshi99 commented Apr 13, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Apr 13, 2026

Uh oh!

Copilot AI Apr 13, 2026

Uh oh!

Copilot AI Apr 13, 2026

Uh oh!

Copilot AI Apr 13, 2026

Uh oh!

Copilot AI Apr 13, 2026

Uh oh!

Copilot AI Apr 13, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

	return features && features[FLAGON_NAME] ? KLAVIYO_CANARY_API_REVISION : KLAVIYO_API_REVISION
	return features && features[FLAGON_NAME] ? KLAVIYO_CANARY_API_VERSION : KLAVIYO_API_VERSION

Conversation

harsh-joshi99 commented Apr 13, 2026

Summary

What the skill does

Test plan

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Apr 13, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 13, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 13, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 13, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 13, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 13, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants