Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
4 changes: 2 additions & 2 deletions .claude-plugin/plugin.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "vercel",
"version": "0.32.7",
"name": "vercel-plugin",
"version": "0.40.0",
"description": "Build and deploy web apps and agents",
"author": {
"name": "Vercel",
Expand Down
2 changes: 1 addition & 1 deletion .cursor-plugin/plugin.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "vercel",
"version": "0.32.5",
"version": "0.40.0",
"description": "Build and deploy web apps and agents",
"author": {
"name": "Vercel",
Expand Down
2 changes: 1 addition & 1 deletion .plugin/plugin.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "vercel-plugin",
"version": "0.32.7",
"version": "0.40.0",
"description": "Comprehensive Vercel ecosystem plugin — relational knowledge graph, skills for every major product, specialized agents, and Vercel conventions. Turns any AI agent into a Vercel expert.",
"author": {
"name": "Vercel",
Expand Down
20 changes: 6 additions & 14 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -30,10 +30,6 @@ All hooks are registered in `hooks/hooks.json` and run via `node "${CLAUDE_PLUGI
| SessionStart | `session-start-seen-skills.mjs` | `startup\|resume\|clear\|compact` | — |
| SessionStart | `session-start-profiler.mjs` | `startup\|resume\|clear\|compact` | — |
| SessionStart | `inject-claude-md.mjs` | `startup\|resume\|clear\|compact` | — |
| PreToolUse | `pretooluse-skill-inject.mjs` | `Read\|Edit\|Write\|Bash` | 5s |
| UserPromptSubmit | `user-prompt-submit-skill-inject.mjs` | (all prompts) | 5s |
| PostToolUse | `posttooluse-shadcn-font-fix.mjs` | `Bash` | 5s |
| PostToolUse | `posttooluse-validate.mjs` | `Write\|Edit` | 5s |
| SessionEnd | `session-end-cleanup.mjs` | — | — |

### Hook Source Files (`hooks/src/*.mts`)
Expand All @@ -42,13 +38,9 @@ Source lives in `hooks/src/*.mts` (TypeScript) and compiles to `hooks/*.mjs` (ES

**Entry-point hooks** (wired in hooks.json):
- `session-start-seen-skills.mts` — initializes `VERCEL_PLUGIN_SEEN_SKILLS=""` in `CLAUDE_ENV_FILE`
- `session-start-profiler.mts` — scans config files + package deps → sets `VERCEL_PLUGIN_LIKELY_SKILLS` (+5 priority boost); detects greenfield mode
- `inject-claude-md.mts` — outputs `vercel.md` ecosystem graph (52KB) as SessionStart additionalContext
- `pretooluse-skill-inject.mts` — main injection engine: pattern matching → ranking → dedup → budget enforcement (max 3 skills, 18KB)
- `user-prompt-submit-skill-inject.mts` — prompt signal scoring engine (max 2 skills, 8KB budget)
- `posttooluse-validate.mts` — runs skill-defined validation rules on written/edited files
- `posttooluse-shadcn-font-fix.mjs` — fixes shadcn font loading issues (standalone, no .mts source)
- `session-end-cleanup.mts` — deletes temp dedup + validation files
- `session-start-profiler.mts` — activates only for greenfield directories or detected Vercel/Next.js projects, then scans config files + package deps → sets `VERCEL_PLUGIN_LIKELY_SKILLS` (+5 priority boost)
- `inject-claude-md.mts` — outputs the thin session-start Vercel context plus knowledge update guidance for that same activation set
- `session-end-cleanup.mts` — deletes session-scoped temp files

**Library modules** (imported by entry-point hooks):
- `hook-env.mts` — shared runtime helpers (env parsing, path resolution)
Expand All @@ -61,11 +53,11 @@ Source lives in `hooks/src/*.mts` (TypeScript) and compiles to `hooks/*.mjs` (ES

### Skill Injection Flow

1. **SessionStart**: Profiler scans project → sets `VERCEL_PLUGIN_LIKELY_SKILLS`
1. **SessionStart**: For greenfield directories or detected Vercel/Next.js projects, the profiler scans the project → sets `VERCEL_PLUGIN_LIKELY_SKILLS`
2. **PreToolUse** (on Read/Edit/Write/Bash): Match file paths (glob), bash commands (regex), imports (regex+flags) → apply vercel.json routing → apply profiler boost → rank by priority → dedup → inject up to 3 skills within 18KB budget
3. **UserPromptSubmit**: Score prompt text against `promptSignals` (phrases/allOf/anyOf/noneOf) → inject up to 2 skills within 8KB budget
- **3b. Lexical fallback** (when `VERCEL_PLUGIN_LEXICAL_PROMPT=on`): If phrase/allOf/anyOf scoring yields no matches above `minScore`, re-score using a lexical stemmer that normalizes prompt tokens before comparison — catches natural phrasing that exact-substring matching misses
4. **PostToolUse** (on Write/Edit): Match written file to skills → run `validate` rules → return fix instructions on error
4. **SessionEnd**: Clean up session-scoped temp files

Special triggers in PreToolUse:
- **TSX review**: After N `.tsx` edits (default 3), injects `react-best-practices`
Expand Down Expand Up @@ -154,7 +146,7 @@ Heading extraction is case-insensitive and captures everything from the heading

32 test files across `tests/`. Key categories:

- **Hook integration**: `pretooluse-skill-inject`, `user-prompt-submit`, `posttooluse-validate`, `session-start-profiler`, `session-start-seen-skills`
- **Hook integration**: `session-start-profiler`, `session-start-seen-skills`
- **Pattern matching**: `patterns`, `fuzz-glob`, `fuzz-yaml`, `prompt-signals`, `prompt-analysis`
- **Snapshots**: `snapshot-runner` (golden snapshots of skill injection metadata per vercel.json fixture), `snapshots` (snapshot assertions)
- **Validation**: `validate`, `validate-rules`, `build-skill-map`
Expand Down
28 changes: 10 additions & 18 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,15 +22,15 @@
npx plugins add vercel/vercel-plugin
```

That's it. The plugin activates automatically — no setup, no commands to learn. Just build.
That's it. The plugin installs Vercel context, skills, and a lightweight default hook profile.

## What It Does

This plugin pre-loads AI agents with a **relational knowledge graph** of the entire Vercel ecosystem — every product, library, CLI, API, and service — showing how they relate, when to use each, and providing deep guidance through bundled skills.
This plugin gives AI agents a **relational knowledge graph** of the Vercel ecosystem plus a bundled skill library covering products, libraries, CLI, APIs, and workflows.

## How Do I Use This?

After installing, there's nothing to learn — all Vercel guidance happens automatically. The plugin detects what you're working on from your tool calls, file paths, and project config, then injects the right expertise at the right time. Just use your AI agent as you normally would and the plugin handles the rest.
After installing, the plugin keeps automatic behavior lightweight. Session-start activation now only kicks in for empty directories and detected Vercel/Next.js projects, and Vercel skills are no longer auto-injected on every tool call or every prompt by default. The default post-tool path is now observer-only. The skills remain available for direct use, and the repo still keeps the injection engine for targeted or future opt-in workflows.

## Components

Expand Down Expand Up @@ -94,14 +94,12 @@ A text-form relational graph covering:

Lifecycle hooks that run automatically during your session:

- **Session start context injection** — Injects `vercel.md` (ecosystem graph + conventions) into every session
- **Session start repo profiler** — Scans config files and dependencies to pre-prime skill matching for faster first tool call
- **Pre-tool-use skill injection** — Matches tool calls to skills and injects relevant guidance with dedup
- **Pre-write/edit validation** — Catches deprecated patterns before they're written (sunset packages, old API names, renamed files)
- **Session start context injection** — Injects a thin Vercel session context plus the knowledge-update guidance for empty directories and detected Vercel/Next.js projects
- **Session start repo profiler** — Scans config files and dependencies to set likely-skill hints, but only after that same activation check passes

## Usage

After installing, skills and context are injected automatically. You can also invoke skills directly via slash commands:
After installing, session context is injected automatically only for empty directories and detected Vercel/Next.js projects. Vercel skills are available on demand, and you can invoke them directly via slash commands:

```
/vercel-plugin:nextjs
Expand All @@ -111,31 +109,25 @@ After installing, skills and context are injected automatically. You can also in

## Telemetry

The plugin has two separate telemetry controls:

- `~/.claude/vercel-plugin-telemetry-preference` controls prompt text only.
- `VERCEL_PLUGIN_TELEMETRY=off` disables all telemetry.
Prompt text and bash/tool-call telemetry are not collected.

Behavior:

- `echo 'enabled' > ~/.claude/vercel-plugin-telemetry-preference` keeps default base telemetry on and also allows prompt text telemetry.
- `echo 'disabled' > ~/.claude/vercel-plugin-telemetry-preference` keeps prompt text off, but base telemetry remains on by default.
- `VERCEL_PLUGIN_TELEMETRY=off` disables all telemetry, including prompt text, session metadata, tool names, and skill-injection telemetry.
- Unset `VERCEL_PLUGIN_TELEMETRY`: default DAU-only telemetry. Sends a once-per-day `dau:active_today` phone-home.
- `VERCEL_PLUGIN_TELEMETRY=off`: disables all telemetry, including the default DAU-only session-start event.

Where to set `VERCEL_PLUGIN_TELEMETRY=off`:
Where to set `VERCEL_PLUGIN_TELEMETRY`:

- macOS / Linux: add it to the shell profile for the environment that launches your agent, such as `~/.zshrc`, `~/.bashrc`, `~/.bash_profile`, or `~/.config/fish/config.fish`, then restart that terminal or app session.
- Windows: set it in the PowerShell environment that launches your agent, add it to your PowerShell profile (`$PROFILE`), or set it as a persistent user environment variable.

Examples:

```bash
echo 'disabled' > ~/.claude/vercel-plugin-telemetry-preference
export VERCEL_PLUGIN_TELEMETRY=off
```

```powershell
$env:VERCEL_PLUGIN_TELEMETRY = "off"
setx VERCEL_PLUGIN_TELEMETRY off
```

Expand Down
Loading
Loading