# https://github.com/tech-leads-club/agent-skills Project Manual Generated at: 2026-06-17 05:24:39 UTC ## Table of Contents - [Introduction to vercel-labs/agent-skills](#page-intro) - [Skill Format, Build Pipeline, and Progressive Disclosure](#page-build-pipeline) - [vercel-optimize Skill Architecture](#page-vercel-optimize) - [Content Skills Catalog and Known Failure Modes](#page-content-skills) ## Introduction to vercel-labs/agent-skills ### Related Pages Related topics: [Skill Format, Build Pipeline, and Progressive Disclosure](#page-build-pipeline), [vercel-optimize Skill Architecture](#page-vercel-optimize), [Content Skills Catalog and Known Failure Modes](#page-content-skills)
Related Source Files The following source files were used to generate this page: - [README.md](https://github.com/vercel-labs/agent-skills/blob/main/README.md) - [skills/vercel-optimize/README.md](https://github.com/vercel-labs/agent-skills/blob/main/skills/vercel-optimize/README.md) - [skills/react-best-practices/README.md](https://github.com/vercel-labs/agent-skills/blob/main/skills/react-best-practices/README.md) - [skills/react-native-skills/README.md](https://github.com/vercel-labs/agent-skills/blob/main/skills/react-native-skills/README.md) - [packages/react-best-practices-build/package.json](https://github.com/vercel-labs/agent-skills/blob/main/packages/react-best-practices-build/package.json) - [packages/vercel-optimize-tests/package.json](https://github.com/vercel-labs/agent-skills/blob/main/packages/vercel-optimize-tests/package.json) - [packages/react-best-practices-build/src/build.ts](https://github.com/vercel-labs/agent-skills/blob/main/packages/react-best-practices-build/src/build.ts) - [packages/react-best-practices-build/src/config.ts](https://github.com/vercel-labs/agent-skills/blob/main/packages/react-best-practices-build/src/config.ts) - [skills/vercel-optimize/references/support-topics/README.md](https://github.com/vercel-labs/agent-skills/blob/main/skills/vercel-optimize/references/support-topics/README.md) - [skills/vercel-optimize/references/playbooks/README.md](https://github.com/vercel-labs/agent-skills/blob/main/skills/vercel-optimize/references/playbooks/README.md)
# Introduction to vercel-labs/agent-skills ## Purpose and Scope `vercel-labs/agent-skills` is a curated collection of skills for AI coding agents. According to the project README, "Skills are packaged instructions and scripts that extend agent capabilities" and "follow the Agent Skills format" (an emerging open specification). Source: [README.md](https://github.com/vercel-labs/agent-skills/blob/main/README.md). A skill bundles three elements into a discoverable package: - `SKILL.md` — instructions the agent consumes - `scripts/` — optional automation helpers - `references/` — optional supporting documentation Source: [README.md](https://github.com/vercel-labs/agent-skills/blob/main/README.md). The repository is multi-disciplinary: it contains Vercel-platform audits, React and React Native engineering guidelines, web-design and writing handbooks, and a deployment skill that publishes to Vercel. ## Available Skills The README advertises the following skills. The table below summarizes the categories and trigger phrases that wire each skill into an agent's intent classifier. | Skill | Domain | Trigger Phrases | Source | |---|---|---|---| | `vercel-optimize` | Vercel cost / performance audit | "optimize this Vercel project" | [README.md](https://github.com/vercel-labs/agent-skills/blob/main/README.md) | | `react-best-practices` | React + Next.js performance | "Review this React component for performance issues" | [README.md](https://github.com/vercel-labs/agent-skills/blob/main/README.md) | | `web-design-guidelines` | UI / accessibility audit | "Review my UI", "Check accessibility" | [README.md](https://github.com/vercel-labs/agent-skills/blob/main/README.md) | | `writing-guidelines` | Vercel voice / handbook audit | "Review my docs", "Audit prose" | [README.md](https://github.com/vercel-labs/agent-skills/blob/main/README.md) | | `react-native-guidelines` | React Native / Expo best practices | "Building React Native or Expo apps" | [skills/react-native-skills/README.md](https://github.com/vercel-labs/agent-skills/blob/main/skills/react-native-skills/README.md) | | `react-view-transitions` | View Transition API | "Add page transitions or route animations" | [README.md](https://github.com/vercel-labs/agent-skills/blob/main/README.md) | | `deploy` | One-shot Vercel deployment | "Deploy my app", "Deploy to production" | [README.md](https://github.com/vercel-labs/agent-skills/blob/main/README.md) | Each skill's own README is the authoritative entry point. For example, `vercel-optimize` documents prerequisites (Node.js 20+, Vercel CLI v53+, Observability Plus, a `vercel link`-ed project) and a metrics-first trust model. Source: [skills/vercel-optimize/README.md](https://github.com/vercel-labs/agent-skills/blob/main/skills/vercel-optimize/README.md). ## Repository Architecture The repository is split into two top-level concerns: a `skills/` directory containing the installable skill packages, and a `packages/` directory containing Node tooling that builds and tests them. ```mermaid graph LR A[skills/] --> B[rules/*.md] A --> C[references/] A --> D[scripts/] B -->|pnpm build| E[packages/react-best-practices-build] E -->|compiled| F[AGENTS.md] E -->|extracted| G[test-cases.json] H[packages/vercel-optimize-tests] -->|fixtures| I[gates / scanners / citations] A --> J[skills.sh / npx skills add] ``` The build pipeline reads individual rule files in `skills/react-best-practices/rules/` and emits a single `AGENTS.md` plus a `test-cases.json` artifact. Source: [packages/react-best-practices-build/src/build.ts](https://github.com/vercel-labs/agent-skills/blob/main/packages/react-best-practices-build/src/build.ts). The build is invoked through the package's `pnpm build` script and supports per-skill subcommands such as `--skill=composition-patterns`. Source: [packages/react-best-practices-build/package.json](https://github.com/vercel-labs/agent-skills/blob/main/packages/react-best-practices-build/package.json). Skill configuration is centralized in `src/config.ts`, which maps each skill (e.g. `composition-patterns`, `react-best-practices`) to its `rulesDir`, `metadataFile`, and `outputFile`, plus a `sectionMap` that assigns numeric prefixes during the build. Source: [packages/react-best-practices-build/src/config.ts](https://github.com/vercel-labs/agent-skills/blob/main/packages/react-best-practices-build/src/config.ts). ### Skill Internals: vercel-optimize The `vercel-optimize` skill is more elaborate than the others. It organizes supporting material under `references/`: - `support-topics/` — "candidate-scoped investigation guardrails injected into sub-agent briefs" — narrow YAML frontmatter-driven files keyed by `id`, `candidateKinds`, `frameworks`, and `citations`. Source: [skills/vercel-optimize/references/support-topics/README.md](https://github.com/vercel-labs/agent-skills/blob/main/skills/vercel-optimize/references/support-topics/README.md). - `playbooks/` — application-profile heuristics (e.g. `ai-application`, `ecommerce`, `saas`) that shape how recommendations are phrased without inventing claims. Source: [skills/vercel-optimize/references/playbooks/README.md](https://github.com/vercel-labs/agent-skills/blob/main/skills/vercel-optimize/references/playbooks/README.md). A separate test package, `@vercel-labs/agent-skill-vercel-optimize-tests`, exercises gates, scanners, and citations and runs `node --test` against fixtures. Source: [packages/vercel-optimize-tests/package.json](https://github.com/vercel-labs/agent-skills/blob/main/packages/vercel-optimize-tests/package.json). ### Skill Internals: react-best-practices and react-native-skills Both guidelines skills use the same authoring convention: files beginning with `_` (e.g. `_sections.md`, `_template.md`) are excluded from the build; rule files are named `area-description.md` (e.g. `async-parallel.md`, `animation-gpu-properties.md`); and the section prefix (`async-`, `bundle-`, `rendering-`, etc.) determines which numbered section the rule lands in during compilation. Source: [skills/react-best-practices/README.md](https://github.com/vercel-labs/agent-skills/blob/main/skills/react-best-practices/README.md) and [skills/react-native-skills/README.md](https://github.com/vercel-labs/agent-skills/blob/main/skills/react-native-skills/README.md). Impact labels (`CRITICAL`, `HIGH`, `MEDIUM-HIGH`, `MEDIUM`, `LOW-MEDIUM`, `LOW`) let agents triage which rules to apply first. ## Installation and Usage The canonical install command is `npx skills add vercel-labs/agent-skills`, optionally scoped to a single skill with `--skill `. Source: [README.md](https://github.com/vercel-labs/agent-skills/blob/main/README.md). Once installed, skills activate when the agent detects matching intent — there is no further wiring required by the user. For the `vercel-optimize` skill, a linked Vercel project directory is required: `vercel link` resolves the project so that `vercel metrics`, `vercel usage`, and `vercel contract` all run against the same account. Without this, the skill pauses before falling back to scanner-only mode. Source: [skills/vercel-optimize/README.md](https://github.com/vercel-labs/agent-skills/blob/main/skills/vercel-optimize/README.md). ## Known Limitations and Community Feedback Several community threads surface recurring pain points worth knowing before adopting the repository: - **Progressive disclosure mismatch.** The current `vercel-react-best-practices` ships a monolithic `AGENTS.md` (~2,975 lines / 83 KB) that duplicates the per-rule files in `rules/`, and `SKILL.md` actively directs agents to read it in full. Issue #169 calls for adopting the Agent Skills spec's progressive-disclosure model by renaming `rules/` to `references/` and letting agents pull only the rules that match intent. Source: [community context — issue #169, #65](https://github.com/vercel-labs/agent-skills/issues/169). - **Frontmatter parser strictness.** `npx skills add` rejects any `SKILL.md` whose frontmatter is preceded by even an HTML comment, breaking consumption of third-party skills like Shopify's `agent-skills` that emit an `` banner above valid frontmatter. Source: [community context — issue #275](https://github.com/vercel-labs/agent-skills/issues/275). - **Content drift between skills.** Cross-skill inconsistencies have been reported (e.g. broken example code in `vercel-composition-patterns/skills/state-lift-state.md` after a fresh install), which suggests the build pipeline does not yet catch broken code blocks. Source: [community context — issue #286](https://github.com/vercel-labs/agent-skills/issues/286). - **Limited agent targets.** The current `add-skill` flow supports Claude Code, Codex, Cursor, and Antigravity; VS Code Copilot support has been requested but is not yet implemented. Source: [community context — issue #27](https://github.com/vercel-labs/agent-skills/issues/27). - **Versioning & marketplace compatibility.** An open RFC proposes versioning for the skills so they can be published to the Claude Code Marketplace, which today requires manual installation. Source: [community context — issue #20](https://github.com/vercel-labs/agent-skills/issues/20). ## See Also - Vercel Agent Skills spec: - Issue tracker: - Skills directory: [skills/](https://github.com/vercel-labs/agent-skills/tree/main/skills) - Build tooling: [packages/react-best-practices-build/](https://github.com/vercel-labs/agent-skills/tree/main/packages/react-best-practices-build) --- ## Skill Format, Build Pipeline, and Progressive Disclosure ### Related Pages Related topics: [Introduction to vercel-labs/agent-skills](#page-intro), [Content Skills Catalog and Known Failure Modes](#page-content-skills), [vercel-optimize Skill Architecture](#page-vercel-optimize)
Related Source Files The following source files were used to generate this page: - [README.md](https://github.com/vercel-labs/agent-skills/blob/main/README.md) - [skills/react-best-practices/README.md](https://github.com/vercel-labs/agent-skills/blob/main/skills/react-best-practices/README.md) - [skills/react-native-skills/README.md](https://github.com/vercel-labs/agent-skills/blob/main/skills/react-native-skills/README.md) - [skills/vercel-optimize/README.md](https://github.com/vercel-labs/agent-skills/blob/main/skills/vercel-optimize/README.md) - [packages/react-best-practices-build/package.json](https://github.com/vercel-labs/agent-skills/blob/main/packages/react-best-practices-build/package.json) - [packages/react-best-practices-build/src/build.ts](https://github.com/vercel-labs/agent-skills/blob/main/packages/react-best-practices-build/src/build.ts) - [packages/react-best-practices-build/src/parser.ts](https://github.com/vercel-labs/agent-skills/blob/main/packages/react-best-practices-build/src/parser.ts) - [packages/react-best-practices-build/src/types.ts](https://github.com/vercel-labs/agent-skills/blob/main/packages/react-best-practices-build/src/types.ts) - [packages/react-best-practices-build/src/config.ts](https://github.com/vercel-labs/agent-skills/blob/main/packages/react-best-practices-build/src/config.ts)
# Skill Format, Build Pipeline, and Progressive Disclosure ## Overview The `vercel-labs/agent-skills` repository packages domain expertise (React, Next.js, React Native, web design, Vercel optimization, writing style) as installable "skills" for AI coding agents. Each skill is a directory containing a `SKILL.md` entry point, a `metadata.json` document, and a `rules/` folder of individual Markdown rule files. Skills follow the public [Agent Skills](https://agentskills.io/) format, which mandates progressive disclosure: agents should load only the entry-point metadata first, then drill into referenced files on demand ([README.md:1-7]()). Two patterns coexist in the repo: 1. **Flat skills** like `vercel-optimize` that ship pre-curated reference Markdown (`references/playbooks/`, `references/support-topics/`) without a build step ([skills/vercel-optimize/README.md:1-30]()). 2. **Compiled skills** like `react-best-practices` and `react-native-skills` whose `rules/` source files are aggregated into a single `AGENTS.md` artifact by the `react-best-practices-build` package ([skills/react-best-practices/README.md:1-15]()). ## Skill Directory Layout A compiled skill has the structure documented in [skills/react-best-practices/README.md:7-15](): | Path | Purpose | Build-time? | |---|---|---| | `SKILL.md` | Entry point the agent loads first | No | | `metadata.json` | Version, organization, abstract | No | | `rules/_sections.md` | Section titles, impacts, descriptions | Source | | `rules/_template.md` | Template for new rules | Source | | `rules/area-description.md` | One file per rule (e.g., `async-parallel.md`) | Source | | `AGENTS.md` | Concatenated output for agents | **Generated** | | `test-cases.json` | LLM evaluation corpus | **Generated** | The `vercel-optimize` skill follows a different layout. Its `references/support-topics/README.md` ([skills/vercel-optimize/references/support-topics/README.md:1-20]()) describes investigation guardrails stored as `id`-named files with strict frontmatter (`status`, `candidateKinds`, `frameworks`, `priority`, `citations`, `maxBriefChars`). Topics are injected into sub-agent briefs rather than concatenated, so no `AGENTS.md` is produced. ## Build Pipeline The pipeline is a Node/TypeScript workspace in `packages/react-best-practices-build`. The package exposes five scripts ([packages/react-best-practices-build/package.json:6-15]()): ```bash pnpm build # build-agents + extract-tests pnpm build-agents pnpm validate pnpm extract-tests pnpm migrate pnpm dev # build + validate ``` `src/config.ts` registers every skill the pipeline knows about, mapping filename prefixes to section numbers. Three skills are currently configured: `react-best-practices` (`async`, `bundle`, `server`, `client`, `rerender`, `rendering`, `js`, `advanced`), `react-native-skills`, and `composition-patterns` ([packages/react-best-practices-build/src/config.ts:1-50]()). ```mermaid flowchart LR R[rules/*.md] --> P[parser.ts] P -->|Rule[]| B[build.ts] M[metadata.json] --> B S[_sections.md] --> B B -->|concat| A[AGENTS.md] R --> V[validate.ts] B --> E[extract-tests.ts] E --> T[test-cases.json] ``` ### Parser `src/parser.ts` reads each rule file, normalizes Windows CRLF to LF, extracts YAML frontmatter between two `---` fences, and slices the body ([packages/react-best-practices-build/src/parser.ts:1-40]()). The parser expects frontmatter to start at byte zero. Community issue [#275](https://github.com/vercel-labs/agent-skills/issues/275) reports that `npx skills add` fails when a `SKILL.md` begins with an HTML comment banner before the opening `---`; the parser silently treats anything before frontmatter as body content. This is a known compatibility friction with skills that emit `` headers. ### Builder `src/build.ts` produces `AGENTS.md` by stamping the metadata header, generating a numbered table of contents, and emitting each section with its rules in alphabetical-by-title order ([packages/react-best-practices-build/src/build.ts:1-60]()). Rule identifiers (`1.1`, `2.3`, …) are assigned during build based on sort position. The output is wrapped in a GitHub-anchor-friendly heading scheme: the H3 anchor `${rule.id} ${rule.title}` is lowercased and stripped of non-word characters so links survive GitHub's renderer. ### Validator and Test Extractor `pnpm validate` runs `validate.ts`, which enforces filename prefixes match the section map in `config.ts` and that every rule declares a recognized `ImpactLevel` (`CRITICAL | HIGH | MEDIUM-HIGH | MEDIUM | LOW-MEDIUM | LOW`) ([packages/react-best-practices-build/src/types.ts:1-10]()). `pnpm extract-tests` parses the `**Incorrect:**` / `**Correct:**` example blocks and emits a paired test corpus to `test-cases.json` for LLM-as-judge evaluation. ## Progressive Disclosure Tension The Agent Skills specification at [agentskills.io/specification#progressive-disclosure](https://agentskills.io/specification#progressive-disclosure) calls for agents to receive a small index file plus lazy-loaded references. The `vercel-react-best-practices` skill currently ships an `AGENTS.md` of **2,975 lines / 83 KB** that inlines every one of the 58 rules — duplicating content that already lives in the `rules/` folder ([issue #169](https://github.com/vercel-labs/agent-skills/issues/169)). Issue [#65](https://github.com/vercel-labs/agent-skills/issues/65) argues for renaming `rules/` to `references/` and replacing the inlined `AGENTS.md` with a thin index so agents only pay context cost for the rules they actually need. Community issue [#286](https://github.com/vercel-labs/agent-skills/issues/286) further documents that the current `vercel-composition-patterns` build sometimes emits broken example code, suggesting that the build pipeline's auto-numeric rule IDs and sort order are not yet resilient to malformed source files. Until progressive disclosure is implemented, contributors who add or reorder rules must regenerate `AGENTS.md` and `test-cases.json` via `pnpm build` and commit both artifacts, or downstream agents will see stale content ([skills/react-best-practices/README.md:47-53]()). ## See Also - [Available Skills Catalog](README.md) — top-level inventory of every skill in the repo - [react-best-practices skill internals](skills/react-best-practices/README.md) — structure, scripts, and section prefixes - [react-native-skills internals](skills/react-native-skills/README.md) — sibling skill with similar layout - [vercel-optimize skill internals](skills/vercel-optimize/README.md) — non-compiled skill using `references/` directly - [Support Topics reference](skills/vercel-optimize/references/support-topics/README.md) — frontmatter schema for candidate-scoped guardrails - Community: [Issue #65 — Progressive Disclosure RFC](https://github.com/vercel-labs/agent-skills/issues/65), [Issue #169 — AGENTS.md context waste](https://github.com/vercel-labs/agent-skills/issues/169), [Issue #275 — SKILL.md frontmatter parser](https://github.com/vercel-labs/agent-skills/issues/275), [Issue #286 — Composition patterns inconsistencies](https://github.com/vercel-labs/agent-skills/issues/286) --- ## vercel-optimize Skill Architecture ### Related Pages Related topics: [Introduction to vercel-labs/agent-skills](#page-intro), [Skill Format, Build Pipeline, and Progressive Disclosure](#page-build-pipeline)
Related Source Files The following source files were used to generate this page: - [skills/vercel-optimize/README.md](https://github.com/vercel-labs/agent-skills/blob/main/skills/vercel-optimize/README.md) - [skills/vercel-optimize/CONTRIBUTING.md](https://github.com/vercel-labs/agent-skills/blob/main/skills/vercel-optimize/CONTRIBUTING.md) - [skills/vercel-optimize/references/playbooks/README.md](https://github.com/vercel-labs/agent-skills/blob/main/skills/vercel-optimize/references/playbooks/README.md) - [skills/vercel-optimize/references/support-topics/README.md](https://github.com/vercel-labs/agent-skills/blob/main/skills/vercel-optimize/references/support-topics/README.md) - [packages/vercel-optimize-tests/package.json](https://github.com/vercel-labs/agent-skills/blob/main/packages/vercel-optimize-tests/package.json) - [skills/vercel-optimize/scripts/check-docs-fresh.mjs](https://github.com/vercel-labs/agent-skills/blob/main/skills/vercel-optimize/scripts/check-docs-fresh.mjs) - [skills/vercel-optimize/scripts/check-citations.mjs](https://github.com/vercel-labs/agent-skills/blob/main/skills/vercel-optimize/scripts/check-citations.mjs)
# vercel-optimize Skill Architecture ## Purpose and Scope The `vercel-optimize` skill is a metric-driven auditing tool that helps AI coding agents find cost and performance optimizations in deployed Vercel projects. It sits inside the `vercel-labs/agent-skills` repository alongside static-style skills such as `react-best-practices` and `writing-guidelines`, but its role is fundamentally different: instead of shipping rules for an agent to follow, it actively queries the Vercel platform through the CLI before touching source code. The skill's mission is stated directly in its README: it "uses Vercel metrics to find high-impact improvements in your app" and guarantees that "every recommendation is backed by observed data, scoped code evidence, and version-aware docs" [Source: [skills/vercel-optimize/README.md:5-7]()]. It enforces a Vercel CLI v53+ compatibility floor, requires an authenticated session, a linked project directory, and Observability Plus for route-level metrics [Source: [skills/vercel-optimize/README.md:25-37]()]. If route-level metrics are unavailable, the skill pauses before entering scanner-only mode, because scanner-only output "can catch traffic-independent code issues, but it cannot rank hot routes or prove cost impact" [Source: [skills/vercel-optimize/README.md:39-41]()]. Framework coverage is asymmetric: strongest for Next.js and SvelteKit, supported for Nuxt via generic checks, and limited or paused for Astro, Hono, Remix, and unknown stacks [Source: [skills/vercel-optimize/README.md:31-37]()]. ## Architecture: Metrics-First Pipeline The skill is organized as a small pipeline of deterministic stages rather than a monolithic prompt. The README identifies the conceptual layers: gates (deterministic thresholds), scanners (code-level checks), playbooks (application-profile shaping), support topics (candidate-scoped investigation briefs), citations (version-aware docs), and sanitizers (claim cleanup) [Source: [skills/vercel-optimize/README.md:75-82]()]. New contributors are pointed at fixture coverage under `packages/vercel-optimize-tests` [Source: [skills/vercel-optimize/README.md:84-85]()]. The runtime flow begins with metric collection through `vercel metrics`, `vercel usage`, and `vercel contract`. Only after signals exist does code investigation start [Source: [skills/vercel-optimize/README.md:73-75](), [skills/vercel-optimize/README.md:78-81]()]. The trust section makes the ordering explicit: "Metrics come first. Code investigation starts only after signals are collected. Gates are deterministic JavaScript thresholds. No LLM decides whether a metric qualifies" [Source: [skills/vercel-optimize/README.md:78-82]()]. ```mermaid flowchart LR A[Metric Collection
vercel metrics / usage / contract] --> B{Gate
deterministic threshold} B -->|qualifies| C[Scanner
code-level checks] B -->|fails| X[Skip candidate] C --> D[Support Topic
candidate-scoped brief] D --> E[Playbook
profile-shaped output] E --> F[Citation allow-list
+ sanitizer] F --> G[Ranked Markdown report] ``` The contract that ties these stages together is the citation allow-list and the verifier, which blocks contradictory actions such as "enable Fluid Compute" when Fluid Compute is already on and uses "magnitude framing, not invented exact savings" [Source: [skills/vercel-optimize/README.md:82-87]()]. Because gates are deterministic JavaScript and citations are stripped against an allow-list, the LLM's role is reduced to summarization rather than judgment [Source: [skills/vercel-optimize/README.md:79-82]()]. This design aligns with the broader community request for progressive disclosure — see discussion #65 ("Follow the Agents skills spec for progressive disclosure") and #169 ("AGENTS.md (2975 lines) wastes context") — by keeping references modular instead of inlining everything into a single document. ## Supporting Subsystems: Playbooks and Support Topics Two reference subsystems in `skills/vercel-optimize/references/` give the skill structured, machine-readable input without bloating `SKILL.md`. **Playbooks** are profile-shaped advice. They "are not recommendations" themselves but tell the recommender "what to emphasize when a project matches a profile" [Source: [skills/vercel-optimize/references/playbooks/README.md:3-7]()]. Detection is best-effort: the table of signals maps dependencies such as `@vercel/sandbox`, `@ai-sdk/*`, `next-auth`, or `pages/api/**` to profiles including `ai-application`, `saas`, `ecommerce`, `api-service`, `content-site`, and `marketing` [Source: [skills/vercel-optimize/references/playbooks/README.md:17-26]()]. `ai-application` is checked first because "AI-shaped customers often share routes with SaaS/ecommerce surfaces, but the billing shape (AI Gateway dominant) and remediation set" differ [Source: [skills/vercel-optimize/references/playbooks/README.md:25-26]()]. **Support topics** are narrower. They are "candidate-scoped investigation guardrails injected into sub-agent briefs" and must cite only URLs already present in `references/docs-library.json` [Source: [skills/vercel-optimize/references/support-topics/README.md:3-5, 35-37]()]. Their frontmatter is a strict YAML subset with `candidateKinds`, optional `metrics`, optional `routePatterns`, and a `maxBriefChars` budget that keeps the brief bounded [Source: [skills/vercel-optimize/references/support-topics/README.md:13-28, 41-44]()]. ## Trust Model, Testing, and Contributing Quality is enforced through dedicated fixtures rather than ad-hoc prompt engineering. The `vercel-optimize-tests` package exposes `npm test` (Node's built-in test runner) plus two doc-quality scripts: `check-docs-fresh.mjs` and `check-citations.mjs` [Source: [packages/vercel-optimize-tests/package.json:7-10]()]. These are wired into the contribution contract, which states that "new gates, scanners, playbooks, citations, and sanitizers need fixture coverage in `packages/vercel-optimize-tests`" [Source: [skills/vercel-optimize/README.md:84-85](), [skills/vercel-optimize/CONTRIBUTING.md:1-20]()]. The trust model is reinforced by three explicit prohibitions: no LLM-decided gate qualification, no unknown or version-mismatched citations, and no project-config contradictions in the verifier [Source: [skills/vercel-optimize/README.md:79-85]()]. The final user-facing artifact is "a concise final message plus a full Markdown report" [Source: [skills/vercel-optimize/README.md:67-70]()], keeping both a quick scan and a deep dive available. ## See Also - `react-best-practices` Skill Architecture — rule-based performance guidance - `web-design-guidelines` Skill Architecture — UI/accessibility audit pipeline - Agent Skills Specification — the format these skills implement - Vercel CLI metrics commands — `vercel metrics`, `vercel usage`, `vercel contract` - Community discussion #65 and #169 — progressive-disclosure rationale for the modular `references/` layout --- ## Content Skills Catalog and Known Failure Modes ### Related Pages Related topics: [Introduction to vercel-labs/agent-skills](#page-intro), [Skill Format, Build Pipeline, and Progressive Disclosure](#page-build-pipeline)
Related Source Files The following source files were used to generate this page: - [README.md](https://github.com/vercel-labs/agent-skills/blob/main/README.md) - [skills/react-best-practices/README.md](https://github.com/vercel-labs/agent-skills/blob/main/skills/react-best-practices/README.md) - [skills/react-native-skills/README.md](https://github.com/vercel-labs/agent-skills/blob/main/skills/react-native-skills/README.md) - [skills/vercel-optimize/README.md](https://github.com/vercel-labs/agent-skills/blob/main/skills/vercel-optimize/README.md) - [skills/vercel-optimize/references/support-topics/README.md](https://github.com/vercel-labs/agent-skills/blob/main/skills/vercel-optimize/references/support-topics/README.md) - [skills/vercel-optimize/references/playbooks/README.md](https://github.com/vercel-labs/agent-skills/blob/main/skills/vercel-optimize/references/playbooks/README.md) - [packages/react-best-practices-build/package.json](https://github.com/vercel-labs/agent-skills/blob/main/packages/react-best-practices-build/package.json) - [packages/react-best-practices-build/src/parser.ts](https://github.com/vercel-labs/agent-skills/blob/main/packages/react-best-practices-build/src/parser.ts) - [packages/react-best-practices-build/src/build.ts](https://github.com/vercel-labs/agent-skills/blob/main/packages/react-best-practices-build/src/build.ts) - [packages/react-best-practices-build/src/config.ts](https://github.com/vercel-labs/agent-skills/blob/main/packages/react-best-practices-build/src/config.ts) - [packages/react-best-practices-build/src/types.ts](https://github.com/vercel-labs/agent-skills/blob/main/packages/react-best-practices-build/src/types.ts)
# Content Skills Catalog and Known Failure Modes This page documents the **content skills** shipped by the `vercel-labs/agent-skills` repository — the rule-driven packages whose source is a directory of Markdown rule files compiled into a single, agent-consumable document — together with the **known failure modes** surfaced by community issues, parser edge cases, and build pipeline quirks. ## 1. The Content Skills Catalog The repository ships two distinct families of skills, each with a different authoring pipeline: ### 1.1 Rules-based skills (compiled from `rules/`) These skills are authored as many small Markdown files inside a `rules/` directory, then compiled into an `AGENTS.md` artifact by the `react-best-practices-build` package. Source: [packages/react-best-practices-build/package.json:8-19](). | Skill | Skill directory | Sections | Rule count | Build output | |---|---|---|---|---| | `react-best-practices` | `skills/react-best-practices/` | 8 (async, bundle, server, client, rerender, rendering, js, advanced) | 40+ rules across 8 categories | `skills/react-best-practices/AGENTS.md` | | `react-native-skills` | `skills/react-native-skills/` | 7 categories (rendering, list-performance, animation, scroll, navigation, state, react-compiler, ui, monorepo) | 16 rules | `skills/react-native-skills/AGENTS.md` | | `composition-patterns` | `skills/composition-patterns/` | 4 (architecture, state, patterns, react19) | rule files in `rules/` | `skills/composition-patterns/AGENTS.md` | The `SKILLS` map in [packages/react-best-practices-build/src/config.ts:18-58]() enumerates all three with their `skillDir`, `rulesDir`, `metadataFile`, `outputFile`, and `sectionMap`. The `composition-patterns` entry uses section prefixes `architecture`, `state`, `patterns`, and `react19`, distinct from the React skill's eight `async`/`bundle`/`server`/`client`/`rerender`/`rendering`/`js`/`advanced` prefixes. ### 1.2 Workflow-driven skills (run by sub-agents) `vercel-optimize` is a different shape. It is not compiled from rule files; it is a runnable skill that invokes the Vercel CLI, reads metrics, and emits a ranked report. Source: [skills/vercel-optimize/README.md](). It composes two reference subsystems: - **Playbooks** — application-profile-specific advice (`ai-application`, `ecommerce`, `saas`, `api-service`, `content-site`, `marketing`) selected from dependency and route heuristics. Source: [skills/vercel-optimize/references/playbooks/README.md](). - **Support topics** — candidate-scoped investigation guardrails injected into sub-agent briefs, scoped by `candidateKinds`, `frameworks`, optional `metrics`, and `routePatterns`. Source: [skills/vercel-optimize/references/support-topics/README.md](). The remaining skills catalogued in the root [README.md]() (`writing-guidelines`, `web-design-guidelines`, `react-view-transitions`) are content-review or API-coverage skills and are not part of the compiled `AGENTS.md` build pipeline. ```mermaid flowchart LR R[rules/*.md] --> P[parser.ts] P --> V[validate.ts] V --> B[build.ts] B --> A[AGENTS.md] A --> AGENT[AI Agent] M[metadata.json] --> B S[_sections.md] --> B ``` ## 2. Build Pipeline and Artifact Shape The `react-best-practices-build` package exposes five entry points. Source: [packages/react-best-practices-build/package.json:8-14](). | Script | Command | Purpose | |---|---|---| | `build` | `pnpm build-agents && pnpm extract-tests` | Compile `AGENTS.md` and emit `test-cases.json` | | `build-react` | `tsx src/build.ts --skill=react-best-practices` | Build one skill | | `build-rn` | `tsx src/build.ts --skill=react-native-skills` | Build React Native skill | | `build-composition` | `tsx src/build.ts --skill=composition-patterns` | Build composition skill | | `validate` | `tsx src/validate.ts` | Check rule files against schema | | `extract-tests` | `tsx src/extract-tests.ts` | Pull bad/good code examples into test fixtures | The build iterates the section map from [packages/react-best-practices-build/src/config.ts]() and produces a hierarchical Markdown document with a numbered TOC and per-rule anchors of the form `-` (e.g., `1-1-eliminating-waterfalls`). Source: [packages/react-best-practices-build/src/build.ts](). Rule files must begin with `---` frontmatter. The parser extracts key/value pairs line-by-line before the closing `---`, then parses the body for `## Title`, `**Incorrect (…):**`/`**Correct (…):**` blocks, and a `Reference:` link. Source: [packages/react-best-practices-build/src/parser.ts:18-38](). ## 3. Known Failure Modes The community has surfaced several reproducible failure modes. Each is documented here with its symptom and a workaround. ### 3.1 Parser rejects SKILL.md with leading HTML comments `skills add` fails with `No valid skills found` when `SKILL.md` contains anything before the opening `---`, even a single HTML comment banner such as `<!-- AUTO-GENERATED ... -->`. Source: [issue #275](https://github.com/vercel-labs/agent-skills/issues/275). Workaround: move the banner **below** the opening `---` frontmatter fence, or strip it during install. ### 3.2 Insufficient `npx skills check` error reporting When installed skills are renamed or removed upstream, `npx skills check` does not clearly report which skills became unresolvable. Source: [issue #152](https://github.com/vercel-labs/agent-skills/issues/152). Until upstream reporting improves, users must diff their `.agents/skills/` directory manually after each `check`. ### 3.3 Cross-skill inconsistency: composition-patterns vs react-best-practices Issue #286 reports that `vercel-composition-patterns` ships broken code in `state-lift-state.md`, and the two skills disagree on terminology and example patterns in adjacent rule families. Source: [issue #286](https://github.com/vercel-labs/agent-skills/issues/286). The `composition-patterns` skill is not built by the same pipeline as `react-best-practices` in the same commit; if you `pnpm build --all`, re-read `state/lift-state.md` before relying on it. ### 3.4 AGENTS.md monolith wastes context (progressive disclosure) `vercel-react-best-practices/AGENTS.md` is **2,975 lines / ~83KB**, duplicating the 57 individual rule files in `rules/`. `SKILL.md` itself directs agents to read the monolith, defeating progressive disclosure. Source: [issue #169](https://github.com/vercel-labs/agent-skills/issues/169) and [issue #65](https://github.com/vercel-labs/agent-skills/issues/65). The recommended fix is to rename `rules/` to `references/` and let `SKILL.md` reference files on demand, per the [Agent Skills specification](https://agentskills.io/specification#progressive-disclosure). ### 3.5 SSR rules not separable from CSR Issue #74 requests splitting the `server-*` rules out of `react-best-practices` so client-only React users can opt out of Next.js-specific guidance. Source: [issue #74](https://github.com/vercel-labs/agent-skills/issues/74). Today there is no opt-out flag — the build always inlines the full `server` section. ### 3.6 Claude Code Marketplace compatibility The `add-skill` flow supports Claude Code, Codex, Cursor, and Antigravity, but the repo does not yet publish a Claude Code Marketplace manifest or per-skill versions. Source: [issue #20](https://github.com/vercel-labs/agent-skills/issues/20) and [issue #27](https://github.com/vercel-labs/agent-skills/issues/27). ## 4. Safe Authoring Checklist When contributing to or installing from this repo: 1. Always place an `---` frontmatter fence as the very first line of `SKILL.md`. Source: [parser.ts:18-23](). 2. Pick the correct filename prefix for the skill you are editing (`async-`, `bundle-`, `server-`, `client-`, `rerender-`, `rendering-`, `js-`, `advanced-` for React; `rendering-`, `list-performance-`, `animation-`, `scroll-`, `navigation-`, `react-state-`, `state-`, `react-compiler-`, `ui-`, `design-system-`, `monorepo-`, `imports-`, `js-`, `fonts-` for React Native). Source: [skills/react-best-practices/README.md](), [skills/react-native-skills/README.md](). 3. Run `pnpm validate` before opening a PR — `validate.ts` enforces the schema in [types.ts](). 4. After install, run `npx skills check` and manually audit for renamed/removed skills until issue #152 is resolved. 5. If you only need a subset of rules, follow issue #65's guidance and copy individual files from `rules/` into your local `references/` rather than consuming the full `AGENTS.md`. ## See Also - [Agent Skills specification — progressive disclosure](https://agentskills.io/specification#progressive-disclosure) - `skills.sh` listing for `vercel-labs/agent-skills` - Related wiki pages: `vercel-optimize Skill`, `react-best-practices Skill`, `react-native-guidelines Skill`, `composition-patterns Skill` --- <!-- evidence_pipeline_checked: true --> <!-- evidence_injected: true --> --- ## Pitfall Log Project: tech-leads-club/agent-skills Summary: Found 14 structured pitfall item(s), including 2 high/blocking item(s). Top priority: Security or permission risk - Security or permission risk requires verification. ## 1. Security or permission risk - Security or permission risk requires verification - Severity: high - Evidence strength: source_linked - Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/tech-leads-club/agent-skills/issues/114 ## 2. Security or permission risk - Security or permission risk requires verification - Severity: high - Evidence strength: source_linked - Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/tech-leads-club/agent-skills/issues/120 ## 3. Installation risk - Installation risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/tech-leads-club/agent-skills/issues/131 ## 4. Configuration risk - Configuration risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: capability.host_targets | https://github.com/tech-leads-club/agent-skills ## 5. Capability evidence risk - Capability evidence risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: README/documentation is current enough for a first validation pass. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: capability.assumptions | https://github.com/tech-leads-club/agent-skills ## 6. Maintenance risk - Maintenance risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: evidence.maintainer_signals | https://github.com/tech-leads-club/agent-skills ## 7. Security or permission risk - Security or permission risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: no_demo - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: downstream_validation.risk_items | https://github.com/tech-leads-club/agent-skills ## 8. Security or permission risk - Security or permission risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: no_demo - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: risks.scoring_risks | https://github.com/tech-leads-club/agent-skills ## 9. Security or permission risk - Security or permission risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/tech-leads-club/agent-skills/issues/123 ## 10. Security or permission risk - Security or permission risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/tech-leads-club/agent-skills/issues/135 ## 11. Security or permission risk - Security or permission risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/tech-leads-club/agent-skills/issues/126 ## 12. Security or permission risk - Security or permission risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/tech-leads-club/agent-skills/issues/129 ## 13. Maintenance risk - Maintenance risk requires verification - Severity: low - Evidence strength: source_linked - Finding: issue_or_pr_quality=unknown。 - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: evidence.maintainer_signals | https://github.com/tech-leads-club/agent-skills ## 14. Maintenance risk - Maintenance risk requires verification - Severity: low - Evidence strength: source_linked - Finding: release_recency=unknown。 - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: evidence.maintainer_signals | https://github.com/tech-leads-club/agent-skills <!-- canonical_name: tech-leads-club/agent-skills; human_manual_source: deepwiki_human_wiki -->