feat(skills): add vercel-connect skill by jpsingaraju · Pull Request #94 · vercel/vercel-plugin

jpsingaraju · 2026-05-28T20:48:23Z

Summary

Adds a Claude skill for Vercel Connect — guides agents through obtaining scoped OAuth tokens for third-party services (Slack, GitHub, Linear, generic OAuth) via Vercel Connect.

The skill covers all three integration paths:

CLI — vercel connect create/list/token workflow, including the project-folder requirement for auto-configuration
TypeScript SDK — @vercel/connect (getToken), plus the /ash subpath (connect() helper, connectSlackCredentials() for Ash Slack channels)
HTTP API — for non-JS callers

Origin

Ported from the source repo's skills/vercel-connect/SKILL.md (vercel/connect), which is being archived. The @vercel/connect package itself is being moved into vercel/vercel in a companion PR: vercel/vercel#16462

Frontmatter

Enriched to match the existing vercel-plugin pattern (auth, ai-gateway, vercel-cli, etc.):

metadata.priority, docs, sitemap
metadata.importPatterns — triggers on @vercel/connect and its subpaths
metadata.bashPatterns — triggers on vercel connect / vc connect commands and package installs
metadata.pathPatterns — triggers on agent/connections/** and agent/channels/** (Ash usage)
metadata.promptSignals — phrases like "slack token", "github oauth token", etc.
retrieval.aliases / intents / entities / examples
chainTo — escalates from hand-managed SLACK_BOT_TOKEN / SLACK_SIGNING_SECRET env vars to the connectSlackCredentials() helper

Test plan

CI green
Skill loads correctly when relevant signals fire (test by importing @vercel/connect in a sample project and confirming Claude pulls the skill)
Confirm tone / structure consistency with other vercel-plugin skills before merging

🤖 Generated with Claude Code

Adds a Claude skill for Vercel Connect — guides agents through the CLI workflow (`vercel connect create/list/token`), the @vercel/connect SDK (getToken, /ash subpath, connectSlackCredentials), and the HTTP API for non-JS callers. Source: ported from vercel/connect's skills/vercel-connect/SKILL.md, with frontmatter enriched to match vercel-plugin's pattern (metadata.priority, docs, importPatterns, bashPatterns, promptSignals, retrieval, chainTo). The @vercel/connect package itself is being moved to vercel/vercel in a companion PR: vercel/vercel#16462 Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

The validate script requires every skills/ directory to have a matching ⤳ skill: reference in vercel.md's ecosystem graph. Adds a VERCEL CONNECT block under Security alongside AUTHENTICATION INTEGRATIONS, listing the CLI / SDK / HTTP API integration paths and OIDC + Ash dependencies. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Run scripts/generate-catalog.ts to include the new vercel-connect skill in generated/skill-catalog.md. The validate script requires the catalog to list every skill in skills/. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Companion to the catalog regen — generate-catalog also refreshed the manifest with 142 lines of vercel-connect entries (trigger patterns, retrieval metadata, chainTo). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Adds the @vercel/connect package (v0.0.6-alpha.1) to the monorepo, sourced from the standalone vercel/connect repo (which will be archived once this lands). The package provides scoped OAuth tokens for third-party services (Slack, GitHub, Linear, generic OAuth) via Vercel OIDC. It exposes: - @vercel/connect — core getToken/authorization helpers - @vercel/connect/ash — declarative helper for Ash agent connections - @vercel/connect/authjs — Auth.js provider - @vercel/connect/betterauth — better-auth provider Includes 5 unreleased changesets that were pending in the source repo: connect-ash-vercel-connect-marker, connect-authorization-helper, rename-callback-url, token-error-codes, wicked-ends-stick. The companion Claude skill for this package lives in vercel/vercel-plugin (see vercel/vercel-plugin#94). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

- Rename `<provider>` placeholder to `<service>` in CLI examples - Expand Available Services table: add MCP servers, Snowflake, Salesforce, and generic OAuth alongside Slack and GitHub - Update Ash example: use `/mcp` endpoint (not `/sse`) and the correct URL-style connector ID (`mcp.linear.app/myagent` rather than `linear`) - Update Workflow URL example to `/mcp` - Expand frontmatter retrieval + promptSignals with MCP, Snowflake, and Salesforce terms so prompts like "connect to mcp server" trigger the skill - Regenerate skill-manifest.json + skill-catalog.md Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

fixed

## Summary Moves the `@vercel/connect` package from the standalone [vercel/connect](https://github.com/vercel/connect) repository into this monorepo, preserving git history. The `vercel/connect` repo will be archived once this and its companion PR land. ## What's included - **`packages/connect/`** — the package itself (`@vercel/connect`), currently at `v0.0.6-alpha.1`. - `packages/connect/docs/ash-authorization-helper.md` — design doc, moved in from the source repo's `research/` directory. - **5 unreleased changesets** — `.changeset/connect-ash-vercel-connect-marker.md`, `.changeset/connect-authorization-helper.md`, `.changeset/rename-callback-url.md`, `.changeset/token-error-codes.md`, `.changeset/wicked-ends-stick.md`. - **`pnpm-lock.yaml`** regeneration. ## What's *not* included - The source repo's `skills/vercel-connect/` Claude skill — being contributed to [vercel/vercel-plugin](https://github.com/vercel/vercel-plugin) instead (the canonical home for the public Vercel Claude Code plugin). Companion PR: **vercel/vercel-plugin#94 - The source repo's standalone release pipeline (`.github/workflows/release*.yml`), root README/LICENSE, and `pnpm-workspace.yaml` — this monorepo's existing infrastructure supersedes them. ## How history was preserved 1. Cloned `vercel/connect` to a scratch directory. 2. Ran `git filter-repo` to keep only the paths above and rename `research/ash-authorization-helper.md` → `packages/connect/docs/ash-authorization-helper.md`. Dropped everything else. 3. Merged the rewritten history into a branch off `main` with `--allow-unrelated-histories`, then rebased to flatten the merge commit for a linear PR history. `git log --follow packages/connect/src/token.ts` (or any other source file) shows the original commit authors and PR numbers from `vercel/connect`. ## Things to flag - **Release cadence changes.** `@vercel/connect` previously released from its own repo via `release.yml` / `release-snapshot.yml`. In this monorepo it'll release through the shared changesets pipeline. Next version after merge should be a deliberate decision — probably keep `0.0.6-alpha.1` and bump from there. - **`access: restricted` → `access: public`.** The source repo's changeset config was `restricted`; this monorepo's is `public`. The package's own `publishConfig.access` is already `public`, so behavior is consistent — flagging just to confirm. - **pnpm version**: source repo was on pnpm 11.2.2, this monorepo is on 8.3.1. Install completed cleanly; pnpm 11 features like `allowBuilds` were intentionally not carried over (not applicable in pnpm 8). ## Test plan - [ ] CI green on this branch - [ ] `pnpm --filter @vercel/connect typecheck` passes locally - [ ] `pnpm --filter @vercel/connect build` passes locally - [ ] Confirm changesets pipeline picks up the 5 pending entries on next release 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Strip Ash from the vercel-connect skill (the @vercel/connect package renamed Ash -> Eve in vercel/vercel#16541 and is moving away from adapter-specific guidance in this skill). Frontmatter: - Remove importPatterns `@vercel/connect/ash` - Remove pathPatterns `agent/connections/**` and `agent/channels/**` - Remove retrieval.entities `Ash`, retrieval.examples / intents referencing Ash agents - Remove the two chainTo rules tied to Ash imports and SLACK_BOT_TOKEN / SLACK_SIGNING_SECRET (the latter pointed at the Ash-only `connectSlackCredentials` helper) - Drop "building Ash agent connections" from description Body: - Delete `#### Ash agents — @vercel/connect/ash` section - Delete `##### Slack channel — connectSlackCredentials` subsection Factual fixes against vercel/vercel:packages/connect/ (current `main`): 1. HTTP API Python example: response field is `token`, not `accessToken` (src/token.ts:51-69). 2. HTTP API examples now include the required `Authorization: Bearer <VERCEL_OIDC_TOKEN>` header — without it the request 401s (src/token.ts:148-158). 3. "Modes of tokens" now lists all three subject types: `user`, `app`, and `jwt-bearer`. The third was added in vercel/vercel#16520 (src/token.ts:4-29) and was missing from the skill. 4. Workflow step 2: "register-token" terminology replaced with the actual CLI command name `vercel connect create`. No restructure, no new API surface added (revokeToken, /ai-sdk, /mcp, /betterauth, /authjs, startAuthorization, typed errors are intentionally out of scope for this update). Net: -69 / +19 lines. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

jpsingaraju · 2026-06-09T19:32:37Z

Pushed 22f96ce with two scoped changes against this branch.

Strip: Ash adapter content

Removed the @vercel/connect/ash sections + related frontmatter because the package was renamed Ash → Eve in vercel/vercel#16541, and we'd rather not document adapter-specific helpers in the core skill while the surface settles.

Frontmatter: dropped importPatterns: '@vercel/connect/ash', pathPatterns: 'agent/connections/**' and 'agent/channels/**', retrieval.entities: Ash, the Ash-flavored examples/intents, and both chainTo rules (Ash import detection + SLACK_BOT_TOKEN/SLACK_SIGNING_SECRET chain — the latter pointed at the Ash-only connectSlackCredentials helper, so it had nothing left to escalate to).
Body: deleted #### Ash agents — @vercel/connect/ash and ##### Slack channel — connectSlackCredentials.

Fixes: 4 factual bugs vs current vercel/vercel:packages/connect/

HTTP API Python example used the wrong response field. Was connect_response.json()["accessToken"], should be ["token"] per src/token.ts:51-69. Anyone copying the example was getting undefined.
HTTP API examples had no auth header. Added Authorization: Bearer <VERCEL_OIDC_TOKEN> to both the bash template and the Python example, plus a one-liner noting where the token comes from (vc env pull / runtime env). The endpoint requires it (src/token.ts:148-158) — without it the request 401s.
"Modes of tokens" only listed two subject types — source has three. Added jwt-bearer alongside user and app, per src/token.ts:4-29 (added in [@vercel/connect] Add JWT bearer subject types vercel#16520). Short paragraph on when to use each.
Workflow step 2 referred to "the register-token command". Replaced both occurrences with vercel connect create to match the actual CLI surface.

Intentionally out of scope

Keeping this PR's footprint small. The following gaps vs. current @vercel/connect are not addressed here — happy to do them in a follow-up if you'd like:

revokeToken (added in Add Connect revokeToken API vercel#16559)
@vercel/connect/ai-sdk and @vercel/connect/mcp subpath entrypoints ([@vercel/connect] add /ai-sdk and /mcp subpath entrypoints vercel#16529) — including the connectAuthProvider + ConsentRequiredError flow that's the README's flagship example
@vercel/connect/betterauth and @vercel/connect/authjs drop-in providers
startAuthorization and its options (callbackUrl, webhook, deviceCode, expiresInMs)
Typed error classes (ConnectError, NoValidTokenError, UserAuthorizationRequiredError, ConnectorInstallationRequiredError) and their error codes
getTokenResponse full shape (metadata, expiresAt, connector.{id,uid,type}, etc.)
Default-scope semantics (scopes: ['*'])
Built-in LRU cache + validityBufferMs (which makes the workflow's "reuse tokens" advice obsolete for SDK users)

Net diff

1 file, +19 / -69 lines (339 → 289). No regenerated manifest/catalog in this commit — happy to add a follow-up chore: regenerate if those are required for CI green.

@dvoytenko

Per @dvoytenko review on #94 — Salesforce isn't a supported Connect service yet, drop it for now. Removed: - Services table row - description copy - retrieval.entities, retrieval.intents, promptSignals.phrases Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Merges the microfrontends skill (#97) from main and regenerates the shared registry artifacts so both skills coexist. Conflicts resolved: - generated/skill-manifest.json — regenerated via `bun run build:manifest` (28 skills total, includes both vercel-connect and microfrontends) - generated/skill-catalog.md — regenerated via `bun run scripts/generate-catalog.ts` - vercel.md — auto-merged cleanly; both skill graph nodes preserved Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

jpsingaraju mentioned this pull request May 28, 2026

chore: move @vercel/connect from vercel/connect repo vercel/vercel#16462

Merged

4 tasks

jpsingaraju and others added 3 commits May 28, 2026 13:51

jpsingaraju marked this pull request as ready for review May 28, 2026 21:02

dvoytenko previously requested changes May 28, 2026

View reviewed changes

dvoytenko approved these changes May 29, 2026

View reviewed changes

jpsingaraju marked this pull request as draft May 29, 2026 00:12

jpsingaraju marked this pull request as ready for review June 9, 2026 19:35

dvoytenko approved these changes Jun 9, 2026

View reviewed changes

Comment thread skills/vercel-connect/SKILL.md Outdated

jpsingaraju and others added 2 commits June 9, 2026 12:39

jpsingaraju merged commit 5641bff into main Jun 9, 2026
3 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(skills): add vercel-connect skill#94

feat(skills): add vercel-connect skill#94
jpsingaraju merged 8 commits into
mainfrom
feat/add-vercel-connect-skill

jpsingaraju commented May 28, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

jpsingaraju commented Jun 9, 2026

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

jpsingaraju commented May 28, 2026

Summary

Origin

Frontmatter

Test plan

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

jpsingaraju commented Jun 9, 2026

Strip: Ash adapter content

Fixes: 4 factual bugs vs current vercel/vercel:packages/connect/

Intentionally out of scope

Net diff

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants