Bootstrap was present as a skill directory but missing from graph references, causing orphan-skill and stale catalog validation failures.
Removed the stale fake-orphan test skill directory from the workspace and regenerated generated artifacts so catalog/manifest reflect current skills.
Verified: bun run scripts/build-manifest.ts
Verified: bun test tests/validate.test.ts
Verified: bun run scripts/validate.ts
Swarm-Agent: codex-fix-tests
PreToolUse now checks VERCEL_PLUGIN_SETUP_MODE and synthesizes a\nbootstrap match when setup mode is active, then boosts bootstrap\npriority so it injects before other matched skills on the first\nrelevant call.\n\nThe routing is dedup-safe: it skips synthetic bootstrap when the skill\nhas already been injected in seen-skills state.\n\nVerified: bun test tests/pretooluse-skill-inject.test.ts -t "setup mode bootstrap routing"\nVerified: node --check hooks/pretooluse-skill-inject.mjs\nSwarm-Agent: codex-profiler-hooks
Session start now scans for bootstrap/setup markers and exports\nVERCEL_PLUGIN_BOOTSTRAP_HINTS, VERCEL_PLUGIN_RESOURCE_HINTS, and\nVERCEL_PLUGIN_SETUP_MODE=1 when signals cross the setup threshold.\n\nThis gives pre-tool hooks deterministic bootstrap context before the\nfirst tool call and helps route setup-focused skills earlier.\n\nVerified: bun test tests/session-start-profiler.test.ts\nVerified: node --check hooks/session-start-profiler.mjs\nSwarm-Agent: codex-profiler-hooks
Add a new bootstrap skill with priority 8 and trigger patterns for env templates,
Vercel linking/integrations, db/dev scripts, and common auth/data imports.
Add /bootstrap slash command with required conventions sections and explicit
preflight -> provisioning -> env verification -> app startup flow.
Verified: bun -e "import { readFileSync } from 'node:fs'; import { extractFrontmatter, parseSkillFrontmatter } from './hooks/skill-map-frontmatter.mjs'; import { globToRegex, importPatternToRegex } from './hooks/patterns.mjs'; const content = readFileSync('skills/bootstrap/SKILL.md','utf8'); const { yaml } = extractFrontmatter(content); if (!yaml) throw new Error('missing frontmatter'); const fm = parseSkillFrontmatter(yaml); if (fm.name !== 'bootstrap') throw new Error('unexpected skill name'); if (!fm.description) throw new Error('missing description'); if (fm.metadata?.priority !== 8) throw new Error('priority must be 8'); for (const pat of fm.metadata?.pathPatterns ?? []) globToRegex(pat); for (const pat of fm.metadata?.bashPatterns ?? []) new RegExp(pat); for (const pat of fm.metadata?.importPatterns ?? []) importPatternToRegex(pat); console.log('bootstrap skill frontmatter/pattern compilation: ok');" (pass)
Verified: bun /tmp/check-bootstrap-command.mjs (pass)
Swarm-Agent: codex-bootstrap-skill
- 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
WHY this change was made:
The dedup documentation referenced an env-file/temp-file model that no longer matches implementation. This updates HOOKS.md to reflect env-var dedup semantics, subagent process behavior, logger field names, and current issue/env variable tables.
WHAT was verified:
A scoped assertions script confirmed every required addition/replacement/removal in hooks/HOOKS.md.
HOW to test:
Run the assertions command used below to verify required strings and absence of obsolete terms.
Verified: set -euo pipefail; rg -n 'SessionStart appends `export VERCEL_PLUGIN_SEEN_SKILLS=""` to `CLAUDE_ENV_FILE`' hooks/HOOKS.md >/dev/null; rg -n '^## Subagents and dedup state$' hooks/HOOKS.md >/dev/null; rg -n 'VERCEL_PLUGIN_SEEN_SKILLS` is a comma-delimited environment variable, not a temp file\.' hooks/HOOKS.md >/dev/null; rg -n '`strategy` \(`env-var`\|`memory-only`\|`disabled`\)' hooks/HOOKS.md >/dev/null; rg -n '`rankedSkills\[\]`, `previouslyInjected\[\]`' hooks/HOOKS.md >/dev/null; rg -n '`PATH_GLOB_INVALID`' hooks/HOOKS.md >/dev/null; ! rg -n 'DEDUP_READ_FAIL|DEDUP_RESET_FAIL|DEDUP_WRITE_FAIL|RESET_DEDUP=1|env-file|newSkills\[\]' hooks/HOOKS.md >/dev/null
Swarm-Agent: hooks-doc-subagent-dedup-behavior
Add a standalone integration test file that validates session-start env export\nand lead/subagent timeline behavior for VERCEL_PLUGIN_SEEN_SKILLS dedup.\n\nVerified: bun test tests/session-timeline-subagent.test.ts (2 pass)\nSwarm-Agent: session-timeline-subagent-integration-test
Add a standalone slack-clone pattern test suite with deterministic skill-order assertions for key route and component paths.\n\nVerified: bun test tests/slack-clone-patterns.test.ts (5 pass)\nSwarm-Agent: slack-clone-pattern-integration-tests
Add a standalone integration test file that validates deterministic skill injection ordering for realistic notion-clone Next.js file paths.
The tests keep local helpers and only assert hookSpecificOutput.skillInjection.injectedSkills to stay focused on path routing behavior.
Verified: bun test tests/notion-clone-patterns.test.ts (5 pass)
Swarm-Agent: notion-clone-pattern-integration-tests
Add a standalone integration test file for subagent fresh-environment dedup behavior around VERCEL_PLUGIN_SEEN_SKILLS and debug strategy events.
Includes three scenarios: no inherited env (memory-only), explicit empty env (env-var), and inherited seen list (dedup to {}).
Verified: bun test tests/subagent-fresh-env.test.ts (3 pass)
Verified: assertions validate hookSpecificOutput.skillInjection.injectedSkills and dedup-strategy debug event
Swarm-Agent: subagent-fresh-env-integration-tests
Clarifies all AI Gateway dashboard setup and monitoring references in the skill
documentation by pointing to exact Vercel URLs and navigation paths.
Verified: rg-based scoped content check for the five required replacements (pass)
Verified: git diff --check -- skills/ai-gateway/SKILL.md (pass)
Swarm-Agent: dashboard-urls-ai-gateway
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.
The seen-skills dedup was using a temp file written via SessionStart,
but PreToolUse hooks can't update CLAUDE_ENV_FILE. This caused errors
when the temp file became stale or inaccessible across session clears.
Now VERCEL_PLUGIN_SEEN_SKILLS is a comma-delimited string stored
directly in the session environment. SessionStart initializes it as
empty, and the PreToolUse hook reads/updates process.env in-place.
Remove the external js-yaml dependency from skill frontmatter parsing and
implement an inline YAML subset parser in hooks/skill-map-frontmatter.mjs.
The new parser handles key/value pairs, nested objects by indentation,
block lists, inline arrays, number scalars, quoted strings, and strict
yaml-structure errors with readable Invalid YAML frontmatter messages.
Verified: bun test tests/skill-map-frontmatter.test.ts --test-name-pattern '^extractFrontmatter' (7 passed)
Verified: bun test tests/skill-map-frontmatter.test.ts --test-name-pattern '^parseSkillFrontmatter' (6 passed)
Verified: bun test tests/skill-map-frontmatter.test.ts --test-name-pattern 'scans actual skills directory and finds all skills' (1 passed)
Verified: bun test tests/skill-map-frontmatter.test.ts --test-name-pattern 'no warnings emitted for well-formed skills directory' (1 passed)
Verified: bun -e "import { buildSkillMap } from './hooks/skill-map-frontmatter.mjs'; const map = buildSkillMap('./skills'); console.log(JSON.stringify({skillCount:Object.keys(map.skills).length, diagnostics:map.diagnostics.length, warnings:map.warnings.length}, null, 2));" (skillCount=28 diagnostics=0 warnings=0)
Verified: bun -e "import { parseSkillFrontmatter } from './hooks/skill-map-frontmatter.mjs'; const yaml = 'name: demo\ndescription: one:two\nmetadata:\n priority: 7\n filePattern: [\'app/**\', \'src/**\']\n bashPattern:\n - \'\\bnpm\\s+run\\b\'\n -\n nested: value\n'; const parsed = parseSkillFrontmatter(yaml); if (parsed.name !== 'demo') throw new Error('name mismatch'); if (parsed.description !== 'one:two') throw new Error('description mismatch'); if (parsed.metadata.priority !== 7) throw new Error('priority mismatch'); if (!Array.isArray(parsed.metadata.filePattern) || parsed.metadata.filePattern.length !== 2) throw new Error('filePattern mismatch'); if (parsed.metadata.bashPattern[0] !== '\\bnpm\\s+run\\b') throw new Error('bashPattern mismatch'); if (parsed.metadata.bashPattern[1]?.nested !== 'value') throw new Error('nested list object mismatch');" (pass)
Swarm-Agent: inline-yaml-frontmatter-parser
Add targeted Bun tests for BOM extraction, YAML parsing stability, scalar coercion warnings, and scan diagnostics behavior.
These cases lock behavior while parser internals are being refactored.
Verified: bun test hooks/skill-map-frontmatter.test.ts (5 pass)
How to test: bun test hooks/skill-map-frontmatter.test.ts
Swarm-Agent: skill-frontmatter-regression-tests
The plugin should not require a bundled node_modules runtime dependency for YAML parsing.
Removing the only dependency entry avoids shipping a dead dependency declaration.
Verified: node -e "const fs=require('fs'); JSON.parse(fs.readFileSync('package.json','utf8')); console.log('package.json parse ok')"
How to test: node -e "JSON.parse(require('fs').readFileSync('package.json','utf8'))"
Swarm-Agent: remove-js-yaml-package-dependency
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 session-id/tmpdir JSON dedup assumptions with the new VERCEL_PLUGIN_SEEN_SKILLS newline-file flow in hook integration tests.
Covers memory-only behavior without env file, env-file persistence, pre-seeded file behavior, dedup-off and reset controls, strategy debug values, newline-delimited file format assertions, and all_deduped reason handling via shared seen file.
Verified: bun test tests/pretooluse-skill-inject.test.ts (215 pass)
Swarm-Agent: pretooluse-env-file-tests
SessionStart now creates a per-session seen-skills text file and exports
VERCEL_PLUGIN_SEEN_SKILLS through CLAUDE_ENV_FILE before PreToolUse runs.
This enables env-file dedup bootstrap without altering existing PreToolUse hook wiring.
Verified: bun test tests/session-start-seen-skills.test.ts
Verified: bun test tests/pretooluse-skill-inject.test.ts -t "hooks.json PreToolUse config"
Swarm-Agent: session-start-hook-bootstrap
Rewrite the chat-sdk skill frontmatter and body to satisfy the audit's
required routing patterns, API corrections, adapter config fixes, and
section ordering.
This update adds Telegram coverage, corrects SentMessage reaction usage,
documents new Chat/Postable/Thread/Message APIs, expands handlers/cards/
modals, and restructures the guide to the requested reference flow.
Verified: bunx prettier --check skills/chat-sdk/SKILL.md
Verified: bun run - (targeted assertion script validating required patterns, sections, and snippets)
Swarm-Agent: codex-chatskill
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.
In hooks/skill-map.json: add tailwind.config.*, postcss.config.*, tsconfig.json, and tsconfig.*.json to the nextjs pathPatterns. Add bun/yarn install patterns for @ai-sdk/gateway to ai-gateway bashPatterns. Add bun/yarn install patterns for @vercel/functions to runtime-cache bashPatterns. Add bun/yarn install patterns for @vercel/speed-insights to observability bashPatterns.
In hooks/pretooluse-skill-inject.mjs: refactor the hook script for clarity and robustness.
In tests/pretooluse-skill-inject.test.ts: expand test coverage for the new trigger patterns and refactored hook logic.
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.
Addresses a gap where the plugin allowed agents to use direct provider
SDKs (@ai-sdk/anthropic, @ai-sdk/openai) with manual API keys instead
of routing through Vercel AI Gateway, which provides auto-provisioned
credentials, failover, cost tracking, and observability.
Changes:
- PreToolUse hook: add 3 new checks (10-12) for AI Gateway preference,
deprecated generateObject/streamObject, and provider API key env vars
- vercel.md: update AI Features decision matrix to make AI Gateway the
default row, add AI project bootstrap workflow, update Conventions to
lead with gateway-first and vercel-link-first guidance
- ai-sdk SKILL.md: rewrite Installation, add Setup for AI Projects
section, update all code examples to use gateway() instead of direct
provider imports, update Key Patterns to prioritize gateway
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
These fields are for path overrides per the open-plugin spec, not
inventory lists. Components are discovered from the filesystem
automatically. Removing them fixes Claude Code validation errors.
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.
John Lindquist