dataproduct-builder-skills (Python)

Agent skills for designing and building Vulcan/DataOS data products — the Python port of the dataproduct-builder-skills npm scaffolder. Run it via uvx/pipx instead of npx.

Scaffolds agent skills for Cursor, Claude Code, Codex, or VS Code (Copilot) — plus the full Vulcan reference docs — into any project.

Usage

Installs the skills and the Vulcan reference docs your project needs:

# Installs examples for all engines by default
uvx dataproduct-builder-skills

# Or pass an engine to install examples for just that one
uvx dataproduct-builder-skills snowflake
uvx dataproduct-builder-skills postgres
uvx dataproduct-builder-skills databricks

Or with pipx:

pipx run dataproduct-builder-skills snowflake

This launches an interactive prompt for which IDE(s) to install into:

dataproduct-builder-skills — scaffolding skills + docs

Which IDE(s) are you using? (comma-separated for multiple, e.g. 1,2)

  1  Cursor
  2  Claude Code
  3  Codex
  4  VS Code (Copilot)
  5  All

Enter number(s) (1–5):

Engine selection is not interactive — it's all by default, or whichever engine you passed as a CLI argument.

What gets installed

.cursor/skills/              ← Cursor (created if you chose Cursor or All)
  design-data-product/
    SKILL.md
  build-data-product/
    SKILL.md
  fix-data-product/
    SKILL.md
.claude/skills/               ← Claude Code (created if you chose Claude Code or All)
  design-data-product/
    SKILL.md
  build-data-product/
    SKILL.md
  fix-data-product/
    SKILL.md
.codex/skills/               ← Codex (created if you chose Codex or All)
  design-data-product/
    SKILL.md
  build-data-product/
    SKILL.md
  fix-data-product/
    SKILL.md
.github/skills/               ← VS Code / GitHub Copilot (created if you chose VS Code or All)
  design-data-product/
    SKILL.md
  build-data-product/
    SKILL.md
  fix-data-product/
    SKILL.md
dpbs-docs/
  dataos-philosophy/  ← DataOS core concepts
  vulcan-docs/        ← Vulcan CLI/framework reference + official engine guide
    engine-guide/     ← per-engine DataOS guidance
  vulcan-examples/
    <engine>/         ← real working data product examples for your chosen engine
  vulcan-*.whl        ← Vulcan CLI wheel — install with: pip install dpbs-docs/vulcan-*.whl

Experimental — Vulcan Review The bundled wheel ships an experimental vulcan review command that audits a built data product and writes an HTML findings report to .vulcan/reviews/. It's an optional extra, independent of the engine extras — install it only if you want it:

pip install "dpbs-docs/vulcan-*.whl[review]"
vulcan review -e <environment>

It also needs a model — review.model in config.yaml, or --llm <provider:model> — plus that provider's API key exported in your shell.

Extras are per-install, not cumulative: if you later reinstall with an engine extra, include review again to keep it. The fix-data-product skill reads the report this produces.

What the skills do

design-data-product

Guides you from a vague idea to a validated data-product-plan.md spec through:

• Structured question batches (business context, data sources, grain, measures, metrics)
• Entity inference and table discovery via the Data Product MCP
• Model-kind classification, join recommendations
• Quality rules, AI context, and semantic behavior drafting

Trigger: ask the agent to "design a data product", "start a Vulcan design session", or "help me with data-product-plan.md".

Requires: Data Product MCP (dataproduct-mcp/api/v1) connected in Cursor Settings → MCP.

build-data-product

Turns the validated design spec into a working, deployed Vulcan data product — scaffolding models, generating SQL/YAML, running vulcan plan/evaluate, enriching metadata, applying quality checks, and deploying to dev and prod. After the build, it tells you what vulcan review needs (a review.model config, a provider API key) without ever running review itself.

Trigger: ask the agent to "build the data product", "scaffold the Vulcan project", or "run vulcan plan".

fix-data-product

Reads an existing vulcan review report (it never generates one — that's your call, from your own shell), summarizes findings by severity, and — only after you agree — updates data-product-plan.md and fixes blocker/high findings plus the compulsory AI-readiness gaps (descriptions/tags/ai_context coverage). Medium/low findings stay tracked, not auto-fixed.

Trigger: ask the agent to "interpret this review report", "check review findings", or "fix what vulcan review flagged".

Requires: an existing vulcan review report in .vulcan/reviews/ — generate one yourself with pip install "dpbs-docs/vulcan-*.whl[review]" then vulcan review -e <environment> (the report lands in .vulcan/reviews by default). The model comes from review.model in config.yaml or the --llm/--llm-model flag, and the matching provider API key must be exported in your shell.

Requirements

• Python ≥ 3.9 — to run this installer
• Python 3.10 or 3.11 — to run Vulcan itself (the bundled wheel requires >=3.10, <3.12). These can be different interpreters; the build skill creates a dedicated .venv for Vulcan.
• Data Product MCP connected in Cursor (for the design skill)
• Vulcan CLI (pip install vulcan-data-tool) for the build skill

Re-running

Running uvx dataproduct-builder-skills again safely updates existing files with the latest skill and docs content.

Vendoring shared content (maintainers)

Before building/testing, vendor the shared skills/ and dpbs-docs/ content from the repo root into the package's data/ directory (mirrors what bin/create.js/npm pack ships for the npm package):

python3 scripts/vendor_data.py

Building the package (maintainers)

python3 scripts/vendor_data.py
uv build   # or: python3 -m build

This produces an sdist and wheel in python/dist/.

Testing locally without publishing (maintainers)

uv build
uvx --from dist/dataproduct_builder_skills-<version>-py3-none-any.whl dataproduct-builder-skills snowflake
# or
pipx run --spec dist/dataproduct_builder_skills-<version>-py3-none-any.whl dataproduct-builder-skills snowflake

Inspect .claude/skills/, .cursor/skills/, and dpbs-docs/ in a scratch project to verify the output.

Publishing a new version (maintainers)

Follow these steps every time you want to ship an update to PyPI.

1. Make your changes

Edit skill files, docs, or the CLI as needed.

2. Bump the version

Update version in python/pyproject.toml to match the npm package's version in package.json (patch/minor/major, same semver rules as npm).

3. Vendor and build

Clear out dist/ first — a stale build from a previous version left there gets uploaded alongside the new one otherwise:

rm -rf dist build
python3 scripts/vendor_data.py
uv build

4. Publish to PyPI

PyPI no longer accepts username/password — authenticate with an API token (username/password auth returns 403 Forbidden):

export UV_PUBLISH_TOKEN=<your-pypi-token>   # or configure ~/.pypirc for twine
uv publish   # or: python3 -m twine upload dist/*

First time only: generate a token at https://pypi.org/manage/account/token/.

One-liner (steps 3–4 combined)

rm -rf dist build && python3 scripts/vendor_data.py && uv build && uv publish

5. Verify

# confirm the new version is live on PyPI
pip index versions dataproduct-builder-skills

# test the published package end-to-end
uvx dataproduct-builder-skills@latest

License

MIT