Terminal
Terminal/Skill
Helps you design, adopt and review structured TypeScript errors with the @vercel/error package, with stable codes and recovery hints.
By Vercel
Works with
npx skills add vercel-labs/error --skill vercel-errorUse structured fields to identify what failed, explain why, and suggest what to do next. Software should branch on stable fields; people and agents should read the prose. Preserve the fields until output is rendered, and never parse terminal formatting.
Read the target project's package.json, lockfile, existing errors, output paths, logging, and tests before choosing an API.
@vercel/error version's public exports as the contract. Do not deep-import unexported source paths.engines. Add it as a production dependency only for requested implementation work.engines, and report an incompatibility instead of silently changing the runtime. The package itself is isomorphic (browsers, workers, edge runtimes), so treat engines as the Node support matrix, not a runtime allowlist.Before continuing, record the selected version and runtime compatibility, verify the public imports, and identify where the error is created, handled, sent, logged, or shown.
Keep native Error for a simple local failure that no caller classifies, transports, reports, or presents with recovery guidance. Use @vercel/error when at least one of these is needed:
Use a structured error only when you can name the caller, transport, logger, or UI that needs it. "It is more consistent" is not enough.
| Need | Public API | Read |
|---|---|---|
| Decide error codes, details, public text, and reporting | VercelErrorOptions | Contract design |
| Construct one error, define a subclass, preserve a cause, or inspect a caught value | VercelError, core guards and extractors | Core errors |
| Create a typed family with shared fields, documentation, reporting, or a custom class | createErrors | createErrors factories |
| Produce or consume HTTP error responses | errorResponse, fromHttpResponse, parseErrorResponseData, fromErrorResponseData | HTTP errors |
| Format errors for terminal output | formatError, frame, hint, fix, link | Terminal output |
Use VercelError#toString() for a VercelError; it already uses the package formatter. Use frame() for errors or CLI output that should remain another type.
Read each reference whose row matches the work. Continue when every required operation maps to a public import verified in the selected package version.
Apply Contract design to every field in scope, including its pushback rules.
Before implementation, verify that every populated field has a known use and every client-visible field is safe.
When set, scope and code must be nonblank. Keep their original text. Omit blank optional public fields and preserve other text.
For review work, report correctness, disclosure, and recovery gaps; edit only when asked.
For implementation, change only the error path that needs structured fields. Preserve surrounding behavior, code conventions, and third-party error types. Treat project-wide code or scope renames as a separate migration. Code examples must typecheck in the shown context or be labeled as partial replacements.
This step is complete when the reviewed or changed scope is limited to the identified use and every example is complete or explicitly partial.
Test the behavior that consumes the error, not private formatting helpers:
Content-Type, conditional Vary, and HTTP statusRun the target project's closest test and typecheck first, then its required checks. Verification is complete when they pass or every failure and untested runtime or integration path is reported.