- Fix skill store cross-root slug lookup: installed skills under registrySlug
names (e.g., next-best-practices) now resolve when queried by engine name
(e.g., nextjs). Full-body injection rate went from 5% to 78% in evals.
- Fix on-demand install: remove dead hooks.json registrations (library module
with no entry point), keep inline calls from pretooluse/user-prompt-submit.
Non-registry skills now dedup normally instead of wastefully reinjectiing
summary-only content that can never upgrade.
- Add suppressWhenProjectFacts to engine rules: next-upgrade and turbopack
suppressed in greenfield mode (was 12 useless injections per session).
- Add deriveRegistryInstallSet to orchestrator-install-plan (was missing
export that crashed on-demand-skill-install on every invocation).
- Sync all engine rule registries from skills.sh API via build-registry.ts.
22 skills now have registry backing across 11 official Vercel repos.
Exclude vercel-labs/vercel-plugin and vercel/vercel-plugin self-references.
- Add build:registry to the build pipeline (hooks → registry → manifest).
- Create 7 new engine rules: electron, vercel-composition-patterns,
vercel-react-native-skills, web-design-guidelines, deploy-to-vercel,
vercel-react-view-transitions, workflow-init.
- Add .claude/skills/ to .gitignore (installed skill caches).
- Add Verification Checklist to CLAUDE.md.
The orchestrator architecture now resolves skill metadata from the engine-derived manifest and the home cache, so these changes remove assumptions that a local skills/ tree still exists. This keeps the explain tooling, manifest compiler, and profiler behavior consistent with the zero-bundle runtime contract and prevents false failures during first-session detection and tests.
Ploop-Iter: 5
Align the orchestrator with the engine-first architecture so registry-backed skills resolve from the project and home caches without depending on the removed pre-engine build path.
This keeps first-session skill detection and doctor validation stable while the runtime shifts to compiled engine metadata and registry installs, reducing drift between session-start behavior, manifest generation, and test fixtures.
Ploop-Iter: 4
Align the zero-bundle orchestrator path with the engine-backed runtime so installs, cached skill resolution, and hook behavior stay consistent across fresh sessions and delegated actions.
Remove legacy build-time artifacts that no longer participate in the engine pipeline, and harden the smoke coverage around engine-backed caches and registry-driven installs so future cleanup work does not reintroduce stale skills/ assumptions.
Ploop-Iter: 3
Align the orchestrator branch with the engine-first runtime so skill
resolution, registry metadata, and operator docs all describe the
same source of truth.
Make first-session registry installs resilient in restricted
environments by treating install-plan persistence as best-effort,
which prevents hook execution from failing when the home-state cache
cannot be written.
Ploop-Iter: 2
Align the shipped architecture around engine-native rules and the zero-bundle
runtime so orchestration, documentation, and maintenance all reflect the
same source of truth.
Remove the pre-engine build and template pipeline to eliminate dead paths
that were masking drift and making test failures harder to reason about.
Make session-start installation honor registry-backed skills accurately,
including per-registry grouping and alias slugs, so first-session cache
warming can produce a usable zero-bundle cache instead of leaving mapped
skills unresolved.
Update doctor coverage and supporting tests so the orchestrator branch
catches hook-registration regressions and cache-resolution mistakes before
release.
Ploop-Iter: 1
This is a fundamental architectural shift: the plugin no longer ships
skill content. Instead it ships a rules engine (engine/*.md) that
defines WHEN to load skills, and relies on the npx skills registry
(skills.sh/vercel, skills.sh/vercel-labs) to provide WHAT skills say.
## What changed
### New: engine/ directory (40 human-editable rule files)
Each file is a markdown document with YAML frontmatter containing:
- pathPatterns, bashPatterns, importPatterns (file/command matching)
- promptSignals (user prompt scoring: phrases, allOf, anyOf, noneOf)
- validate rules (PostToolUse file validation with severity levels)
- chainTo rules (conditional skill chaining with skipIfFileContains)
- retrieval metadata (aliases, intents, entities for discovery)
- priority, docs URLs, sitemap URLs
- registry source (e.g. "vercel/vercel-skills")
The markdown body serves as a summary fallback when the full skill
content isn't cached locally.
### New: scripts/build-manifest.ts (rewritten)
Now reads engine/*.md instead of skills/*/SKILL.md. Compiles
glob→regex at build time and outputs generated/skill-rules.json.
No dependency on VERCEL_PLUGIN_SKILLS_DIR or local skill sources.
### New: test infrastructure
- tests/helpers/mock-skill-cache.ts — generates a temp
~/.vercel-plugin/skills/ directory with stub SKILL.md files
derived from skill-rules.json for test use
- tests/helpers/preload-mock-cache.ts — bun test preload that
sets VERCEL_PLUGIN_HOME_DIR before any test runs
- bunfig.toml updated with preload
### Removed: skills/ directory (all 40 bundled skills)
The plugin no longer ships skill bodies. At runtime, hooks resolve
skill content from:
1. ~/.vercel-plugin/projects/<hash>/.skills/ (project cache)
2. ~/.vercel-plugin/skills/ (global cache, populated by npx skills)
3. generated/skill-rules.json (metadata-only fallback)
### Removed: 13 test files
Tests that validated build-time skills/ scanning, SKILL.md
frontmatter parsing, snapshot generation, and other behaviors
tied to bundled skills. The remaining 1383 tests pass.
## Architecture going forward
The decoupling is complete:
- engine/*.md = routing rules (owned by plugin, human-editable)
- npx skills = content delivery (owned by Vercel skills team)
- ~/.vercel-plugin/ = runtime cache (populated on first session)
- generated/skill-rules.json = compiled rules (build artifact)
Skills not yet published to the registry will match via the rules
engine but inject only their summary text and docs/sitemap URL
until the Vercel team publishes them.
Keep user projects clean by moving orchestrator state and skill bodies into the shared ~/.vercel-plugin cache instead of relying on per-project bundled artifacts.
Make hook runtime and explain behavior consistent with the zero-bundle distribution model so the plugin can ship only metadata, resolve cached bodies when available, and degrade predictably to summary-only guidance when they are not.
Ploop-Iter: 6
Align install orchestration with hashed home-state roots so surfaced commands and first-session status point at the cache location that now owns project skill state.
Make manifest generation require an explicit skills source so build outputs stay tied to registry-derived metadata instead of implicit bundled inputs as the plugin moves toward zero-bundle distribution.
Ploop-Iter: 5
Move orchestration state and skill resolution out of user projects so the plugin can run in true zero-bundle mode without relying on bundled skill bodies or per-project artifacts.
Refresh cache state from the shared loaders after install attempts and make build-from-skills resolve source directories lazily so first-session installs, lockfile-only installs, and source-only builds all remain accurate when skills are cached outside the repo.
Ploop-Iter: 4
Move orchestrator state and skill resolution out of user projects so the plugin can run cache-first without leaving bundled skill artifacts behind.
This keeps local repositories clean, makes first-session installation and fallback behavior consistent across hooks, and lets the shipped rules manifest drive summary-only guidance when full skill bodies are not cached yet.
The follow-up review fix removes a tracked project-local .skills artifact and updates smoke coverage to assert against the hashed home-state cache, which prevents the repository itself from masking path regressions during zero-bundle migration.
Ploop-Iter: 2
Reuse a single cache-first skill store per hook execution so validation and\nchain injection see the same installed skill set without repeated root scans.\n\nThreading the profiled project root into subagent bootstrap keeps spawned\nagents aligned with the parent workspace's installed skills instead of falling\nback to the process cwd, which is required for the orchestrator model to stay\ncorrect as skills move out of the bundled repo and into per-project caches.\n\nAllowing manifest generation from an alternate source directory supports the\ntransition away from bundled skills while preserving the existing manifest and\nhook contracts during migration.\n\nPloop-Iter: 4
Instead of injecting the full SKILL.md body as additionalContext, inject
"You must run the Skill(<name>) tool." — a more conventional way of
telling the agent to use the Skill tool for context loading.
- Add stemmer and shared contractions modules for lexical prompt matching
- Enhance lexical index and prompt patterns with stemming support
- Add promptSignals metadata to all 43 skill frontmatter files
- Add comprehensive documentation site (docs/)
- Add .claude-plugin marketplace and plugin metadata
- Add benchmark scenarios script
- Update skill manifest with prompt signal data
- Add lexical-index and stemmer tests, expand prompt-patterns tests
Switch benchmark runner project definitions to the 12 benchmark-agent scenario slugs and refresh expected skill targets.
Analyzer now discovers benchmark-agent projects from ~/.claude/projects when results subdirectories are absent, and falls back to hook_progress parsing from session JSONL when skill-injections.jsonl is missing.
Report skill hint mappings were expanded for the new scenario skill set so recommendations stay specific.
Verified: bun test tests/benchmark-analyze.test.ts tests/benchmark-pipeline.test.ts (43 pass)
Verified: bun run scripts/benchmark-analyze.ts (discovers 12 benchmark-agent projects)
Swarm-Agent: codex-p0-analyzer-slugs
- Add greenfield project detection to session-start profiler
- Add profiler boost (+5 priority) for likely skills in PreToolUse
- Remove zzz-test-redos-pattern test skill
- Update golden fixtures and snapshots
- Add agent-browser to ecosystem graph
- Add new golden fixture tests
Update build-manifest.ts to include bodyPath in each skill manifest entry pointing to the SKILL.md file. Update all SKILL.md frontmatter across all skills to ensure consistent formatting. Add vercel-config.mjs improvements for key-aware skill routing.
Add tests/build-skill-map.test.ts for skill map construction. Add golden fixture JSON files (golden-bash-cap-collision, golden-bash-next-dev, golden-edit-middleware, golden-read-env-local, golden-read-vercel-json, golden-vercel-json-crons, golden-vercel-json-rewrites) for deterministic match engine validation. Add tests/fuzz-glob.test.ts and tests/fuzz-yaml.test.ts for property-based testing of the glob-to-regex and YAML parsers.
Update snapshot files for injection output. Update validate.ts and validate.test.ts with command convention checks. Update HOOKS.md documentation. Update pretooluse-skill-inject.mjs, skill-map-frontmatter.mjs, and vercel-config.mjs hook modules. Bump plugin.json version from 0.2.0 to 0.3.0.
Create hooks/vercel-config.mjs that reads vercel.json and maps top-level keys (rewrites, redirects, headers, crons, functions) to skill slugs, so skills are injected when the project uses those Vercel features.
Create hooks/logger.mjs with structured logging at four levels (off, summary, debug, trace) controlled by VERCEL_PLUGIN_LOG_LEVEL env var. Support legacy VERCEL_PLUGIN_DEBUG=1 mapping to debug level.
Create src/cli/explain.ts that takes a tool name and input JSON, runs the match engine, and prints which skills would fire and why. Create src/cli/index.ts as the CLI entry point. Create src/commands/doctor.ts for diagnosing plugin setup issues.
Create src/shared/logger.ts and src/shared/match-engine.ts as TypeScript versions of the shared utilities.
Create scripts/build-manifest.ts that reads all SKILL.md files, parses frontmatter, and generates generated/skill-manifest.json.
Add CLAUDE.md documenting the architecture, dedup contract, YAML parser quirks, test conventions, and log levels.
Add tests: tests/cli-explain.test.ts, tests/logger.test.ts, tests/vercel-config.test.ts, tests/snapshot-runner.test.ts with snapshot files in tests/snapshots/. Add test fixtures in tests/fixtures/. Update existing tests to copy new hook modules (logger.mjs, vercel-config.mjs) into temp dirs.
Update package.json with new bin entry and dependencies.
Extract glob-to-regex and seen-skills file utilities into hooks/patterns.mjs
for reuse across the PreToolUse hook and validation script. Add
validateSkillMap to skill-map-frontmatter.mjs. Expand plugin tags for
chat-sdk/bot variants. Comprehensive tests for all new modules.
Replace centralized skill-map.json with frontmatter-based triggers in
each SKILL.md. Add hooks/skill-map-frontmatter.mjs to parse triggers
at runtime. Update validation, tests, and hook logic accordingly.
Create skills/ai-elements/SKILL.md covering the AI Elements component library — 40+ React components for AI chat UIs (Message, Conversation, Tool, Reasoning, CodeBlock, PromptInput) built as a custom shadcn/ui registry. Document installation via `npx ai-elements`, integration with AI SDK v6 useChat/UIMessage parts, server-side patterns (convertToModelMessages async + toUIMessageStreamResponse), and the DefaultChatTransport client pattern.
Create skills/shadcn/SKILL.md covering shadcn/ui — CLI commands (init, add, build, search, migrate), components.json configuration, namespaced custom registries (@v0, @acme), CSS variable theming with oklch, dark mode setup, the cn() utility, TooltipProvider requirement, RTL support, and framework compatibility (Next.js, Vite, Remix, Astro, Laravel).
Create skills/json-render/SKILL.md covering AI chat response rendering — the UIMessage parts format (text, tool-*, reasoning, step-start), manual rendering patterns for custom chat UIs without AI Elements, ToolResultCard patterns for structured tool output display instead of raw JSON, and the 5 most common v6 rendering mistakes (raw JSON from message.content, tool JSON blobs, convertToModelMessages not awaited, toDataStreamResponse vs toUIMessageStreamResponse, v5 useChat API pattern).
In skills/ai-gateway/SKILL.md, add a full "Authentication (OIDC — Default)" section documenting: VERCEL_OIDC_TOKEN provisioned by `vercel env pull`, @vercel/oidc reading the token automatically, ~24h expiry with re-pull for local dev, auto-refresh on Vercel deployments, AI_GATEWAY_API_KEY as manual alternative, and the auth priority order (API key first, then OIDC fallback).
In skills/ai-sdk/SKILL.md, update the setup section to document OIDC as default auth flow (vercel link → enable gateway → vercel env pull → OIDC token auto-provisioned), rewrite the UI Hooks section with both AI Elements (recommended) and manual rendering patterns showing v6 API changes (DefaultChatTransport, sendMessage, status, message.parts), update Key Patterns to include OIDC, AI Elements, and server-side v6 patterns, and expand the migration section with useChat transport, sendMessage, toUIMessageStreamResponse, and message.parts entries.
In vercel.md ecosystem graph: add AI Elements product entry under AI SDK UI Layer with component list and shadcn dependency, add shadcn/ui product entry under Frameworks with CLI commands and registry system, add OIDC Authentication subsection under AI Gateway with token flow, add AI Elements and custom rendering rows to AI Features decision matrix, update "Build an AI Chatbot" workflow with OIDC steps and AI Elements, add 6 new migration table entries (useChat transport, sendMessage, toUIMessageStreamResponse, message.parts, manual API keys → OIDC), and update AI SDK v6 conventions with OIDC-first auth, AI Elements recommendation, and server/client v6 patterns.
In hooks/skill-map.json, add trigger entries for all 3 new skills: ai-elements (components/ai-elements/**, npx ai-elements, shadcn registry URL patterns), shadcn (components.json, components/ui/**, npx shadcn patterns), json-render (components/chat**, components/message*, chat sidebar patterns).
Run the validator (bun run scripts/validate.ts --coverage skip) to confirm all 8 checks pass with 24 skills, 0 orphans, and all skill-map entries valid.
The ecosystem graph now lives at vercel.md (root). Remove the redundant
assets/ directory and update all references in the validator, tests, and
README.
generateObject and streamObject are deprecated in AI SDK v6. Replace all
usage and documentation with generateText/streamText + Output.object().
Also:
- Expand migration tables with CoreMessage, Experimental_Agent deprecations
- Simplify validator to check metadata only (components discovered from dirs)
- Add date to vercel.md header
Rules (.mdc files) aren't supported by Claude Code's plugin system — they
were silently ignored. Move the ecosystem knowledge graph and all three
convention sets (Next.js 16, AI SDK v6, Vercel platform) into CLAUDE.md
so they're always loaded into context.
Also updates repo references from anthropics/open-plugin to
vercel-labs/vercel-plugin.
Add bun test suite with validate.test.ts, coverage-baseline.ts for
llms.txt gap analysis, orphan-skill detection in validate.ts, structured
JSON output with --format json, and per-check timing metrics.
John Lindquist