PVDS Agent Skills & Knowledge Base

Skills and reference knowledge for building with the Planview Design System (PVDS).

Installation

The recommended path is the @planview/pvds-skills CLI, which auto-detects your project's skills root, records a .pvds-skills/config.json marker, and installs all four skills in one step:

pnpm dlx @planview/pvds-skills init

For npm / yarn / bun, substitute the equivalent runner (npx --yes, yarn dlx, bunx). The CLI is a zero-dependency ~160 KB tarball — no lockfile changes, no peer deps.

Either path installs the skills into the skills directory of each coding agent you have installed (.claude/skills/ for Claude Code, .agents/skills/ for Codex, Cursor, and Copilot, and so on — or your home directory if you install globally). Use --agent to target specific agents; see --agent (init).

Available Skills

| Skill | Purpose | | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | pvds-knowledge | Shared reference knowledge base — API docs, code recipes, gotchas, architecture guides. Not a standalone skill; other skills load data from it. | | pvds-builder | Generate React code using PVDS packages correctly. Loads knowledge on demand to produce correct, performant, accessible code. | | pvds-peer-review | Expert-level peer review of code consuming PVDS packages. Checks coding style, accessibility, performance, theming, and more. | | pvds-test-builder | Write tests for code consuming PVDS packages: sets up the PVDS test providers, queries by role, label and text, and tests your integration rather than PVDS internals. |

CLI

pnpm dlx @planview/pvds-skills init      # one-time setup + install skill markdown
pnpm dlx @planview/pvds-skills upgrade   # refresh skill markdown; bump config version
pnpm dlx @planview/pvds-skills check     # run all deterministic PVDS audits
pnpm dlx @planview/pvds-skills doctor    # verify config + skills presence
pnpm dlx @planview/pvds-skills versions  # compare bundled PVDS reference data vs. installed pv-* versions
pnpm dlx @planview/pvds-skills props <Component>  # look up components', hooks' or styling namespaces' APIs
pnpm dlx @planview/pvds-skills components         # list the manifest's exports (filter by --package / --grep)
pnpm dlx @planview/pvds-skills tokens             # list color, spacing and size tokens, or find which hold a value
pnpm dlx @planview/pvds-skills --help

For npm / yarn / bun projects, substitute the equivalent runner:

| PM | Run | | ---- | ----------------------------------- | | pnpm | pnpm dlx @planview/pvds-skills … | | npm | npx --yes @planview/pvds-skills … | | yarn | yarn dlx @planview/pvds-skills … | | bun | bunx @planview/pvds-skills … |

Quick start

Audit your code. check is deterministic and offline; it exits 1 on error-level findings (warnings don't block by default) and 2 when it couldn't run:

pnpm dlx @planview/pvds-skills check
pnpm dlx @planview/pvds-skills check --preset=self-review --changed   # only what you've touched
pnpm dlx @planview/pvds-skills check --only=hardcoded-colors,unknown-props
pnpm dlx @planview/pvds-skills check --fail-on=warning                # strict CI
pnpm dlx @planview/pvds-skills check --format=json --output=./pvds-report.json

Look things up before writing code:

pnpm dlx @planview/pvds-skills props Grid Toolbar             # a component's props
pnpm dlx @planview/pvds-skills props ContentLayout.Left       # a composite's sub-component
pnpm dlx @planview/pvds-skills components --grep=button       # what is it actually called?
pnpm dlx @planview/pvds-skills tokens colors --grep=error     # color tokens by name
pnpm dlx @planview/pvds-skills tokens --value '#d41616'       # which tokens hold this value?

Choose which agents get the skills:

pnpm dlx @planview/pvds-skills init                      # auto-detect installed agents
pnpm dlx @planview/pvds-skills init --agent claude-code  # or name them; repeatable, '*' for all

CLI-REFERENCE.md has everything else: every command and flag, exit codes, JSON output shapes, the rule catalogue (each ruleId, its severity, and what it ignores), how props resolves a name, and the manifest schema.

Architecture

Single bundled ESM entry (dist/cli.js). Every dependency (citty and cross-spawn) is inlined at build time via tsdown's deps.alwaysBundle: /.*/. No runtime deps, no peer deps, no post-install hooks. The consumer-facing manifest (deprecations, enum props, style-token reverse-lookups) is generated from the installed @planview/pv-* .d.ts files via pnpm refresh-manifest and bundled inline — no runtime dependency on those packages.

Usage

Building with PVDS

Invoke the builder skill when you need help creating UI with PVDS:

/pvds-builder I need a grid with editable cells and drag-and-drop

Reviewing PVDS code

Invoke the review skill to check your PVDS usage:

You can ask for a review of a specific PR:

/pvds-peer-review can you please review PR #123

Or ask for a general review of your current branch:

/pvds-peer-review can you please review the current changes in my branch? The intent with the changes are....

Or ask for a review of commits not yet pushed to a PR:

/pvds-peer-review can you please review the last three commits in my branch? The intent with the changes are....

You can also do a quick, only mechanical review of your code by asking for a quick review. This will run the deterministic CLI checks and return the results to you.

/pvds-peer-review can you please do a quick review of the changes done in my branch?

Testing PVDS code

Invoke the test builder skill to write tests for code that uses PVDS components. It sets up the PVDS test providers, queries by accessible role, label and text, and covers how your code uses the components rather than what PVDS does internally:

/pvds-test-builder add tests for the filter panel: changing a filter should narrow the grid

Or point it at existing code:

/pvds-test-builder write tests for src/features/tasks/TaskDetails.tsx, including selecting a card and opening the details panel

Knowledge Base Coverage

| Package | Status | | ------------------------ | ------------------------------------------------------------ | | @planview/pv-grid | Available (API reference, 27 recipes, gotchas, architecture) | | @planview/pv-uikit | Available (API reference, 15 recipes, gotchas, architecture) | | @planview/pv-utilities | Available (API reference, 13 recipes, gotchas, architecture) | | @planview/pv-tokens | Available (API reference, gotchas) | | @planview/pv-toolbar | Available (API reference, 15 recipes, gotchas, architecture) | | @planview/pv-icons | Available (API reference, gotchas) | | @planview/pv-details | Available (API reference, 12 recipes, gotchas, architecture) | | @planview/pv-filter | Available (API reference, 14 recipes, gotchas, architecture) | | @planview/pv-gantt | Available (API reference, 17 recipes, gotchas, architecture) | | @planview/pv-form | Available (API reference, 19 recipes, gotchas, architecture) | | @planview/pv-widget | Available (API reference, 17 recipes, gotchas, architecture) |

Cross-cutting guides available: accessibility, coding style, theming & tokens, i18n, testing, performance.

Contributing

See CONTRIBUTING.md for local development, testing, and release instructions.