vendure-dev-skill

An agentic skill for working on TypeScript projects built on Vendure — the headless commerce framework (@vendure/core, @vendure/dashboard, @vendure/admin-ui, @vendure/cli, the official @vendure/* plugins, and so on).

The skill is designed to load into any agent runtime that supports Anthropic-style "skills" or equivalent loadable instruction packs (Claude Code, Claude.ai with skills enabled, OpenAI Codex / Operator / Agents SDK, OpenCode, custom MCP-orchestrating agents, etc.). Nothing in the contents is specific to a particular agent product.

Purpose

Vendure is a non-trivial framework with its own conventions (VendurePlugin decorator on top of NestJS modules, RequestContext threading, TransactionalConnection, ErrorResult union mutations, the EventBus, the JobQueue, custom field declaration merging, channel scoping, a freshly-rewritten React Dashboard alongside a deprecated Angular Admin UI, and more). General TypeScript / NestJS / GraphQL knowledge alone gets agents into trouble.

This skill is the field manual that keeps an agent on the rails when it encounters Vendure code: where to look, what to do, what to avoid, and — crucially — when to stop guessing and consult the live docs.

Repo layout

The skill itself lives in the vendure-dev/ directory of this repo. That directory is what you load into your agent runtime — it follows the standard skill folder convention (a SKILL.md at the root with YAML frontmatter and supporting reference files alongside it).

vendure-dev-skill/                 <- this repo
├── README.md                      <- you are here
├── LICENSE
└── vendure-dev/                   <- the skill folder
    ├── SKILL.md
    └── references/
        ├── mcp-usage.md
        ├── project-setup.md
        ├── plugins.md
        ├── graphql.md
        ├── jobs-events.md
        ├── debugging.md
        ├── admin-ui-legacy.md
        ├── dashboard.md
        ├── ui-migration.md
        ├── testing.md
        └── version-info.md

What it covers

A short top-level vendure-dev/SKILL.md with the philosophy, the most important footguns, and a decision table pointing into focused references under vendure-dev/references/:

Reference	Topic
mcp-usage.md	When and how to call each of the two MCP servers (below); query patterns and known quirks
project-setup.md	Bootstrapping a new project (@vendure/create), VendureConfig, environment variables, monorepos, the @vendure/cli
plugins.md	The @VendurePlugin decorator, entities, custom fields with declaration merging, services, TransactionalConnection, lifecycle hooks, channels, strategies
graphql.md	The Shop and Admin APIs, schema extension, resolvers and decorators (@Allow/@Transaction/@Ctx), @ResolveField, the ErrorResult-union idiom, custom scalars including Money, codegen for plugins / Dashboard / storefront, IDE setup
jobs-events.md	EventBus (and blocking event handlers), JobQueueService, BullMQJobQueuePlugin, DefaultSchedulerPlugin and ScheduledTask (v3.3+), and how to choose between the three
debugging.md	Logger, DB query logging, common failure triage, custom field declaration-merging issues, transaction weirdness, channel-scoping bugs
admin-ui-legacy.md	Maintaining Angular-based Admin UI extensions (deprecated; not maintained after July 2026) — AdminUiExtension, compileUiExtensions, addActionBarItem/registerRouteComponent, etc.
dashboard.md	The new React Dashboard: Vite setup, defineDashboardExtension, page structure, useDetailPage, the "import everything from @vendure/dashboard" rule and its four exceptions
ui-migration.md	Concept-by-concept mapping from the legacy Admin UI to the new Dashboard, the CLI codemod, what cannot be ported automatically
testing.md	@vendure/testing + Vitest e2e patterns: DB initializers, createTestEnvironment, fixtures, accessing internal services
version-info.md	Version-gated feature snapshot (current as of @vendure/core 3.6) and how to verify currency at any later date

The skill is opinionated about staying current. It treats its own contents as a snapshot that will drift over time, and routes the agent back to the two MCP servers below for fresh truth.

MCP servers to use with this skill

The skill is much weaker without these servers configured. They are how the agent verifies APIs against the real docs and the real source code.

1. Vendure docs MCP — https://docs.vendure.io/mcp

The official MCP server published by Vendure. Returns search results from, and full markdown of, every page on https://docs.vendure.io/. Updates with each docs deploy, so it always reflects the current minor version.

Tools:

• search_docs(query, [section], [packageId], [limit]) — returns {title, url, snippet, section}[]. The section filter (e.g. "Developer Guide", "Reference", "Extending The Dashboard", "Legacy Apis", "How To", "Core Concepts", "Storefront", "Deployment", "Getting Started") is the single highest-leverage thing to use.
• get_doc_page(url) — returns full markdown for a docs.vendure.io URL. Some pages exceed the response budget — fall back to DeepWiki for those, or use a more targeted search_docs.

2. DeepWiki MCP — https://mcp.deepwiki.com/mcp

A general MCP server from DeepWiki that grounds answers in any public GitHub repo. For Vendure work, point it at vendurehq/vendure. Best for synthesised explanations across many files, version history ("what changed between v3.0 and v3.6"), and pages too long to fetch from the docs MCP directly.

Tools (used with repoName: "vendurehq/vendure"):

• read_wiki_structure({repoName}) — hierarchical TOC of the wiki.
• read_wiki_contents({repoName}) — the wiki content itself.
• ask_question({repoName, question}) — synthesised, citation-grounded answer to a free-form question.

Configuring the MCP servers

How you register MCP servers depends on your runtime — see your agent's documentation. As examples (subject to change):

• Claude Code / Claude.ai: claude mcp add from the CLI, or via .claude/mcp.json / the connector picker in the UI.
• OpenAI Codex / Operator: under the MCP / Connectors settings for your workspace.
• Custom agents (Anthropic SDK / OpenAI Agents SDK / Mastra / etc.): whatever MCP-client API your stack exposes, pointed at the URLs above.

Both servers are HTTP-based MCP servers, no auth required.

Status and currency

Last verified against @vendure/core 3.6.x (released 2026-03-31). The skill includes a version-info.md reference with the version-gating detail it currently knows about, plus instructions for re-verifying via the MCPs at any later date.

If you find a fact in here that's drifted, please open an issue or PR.

License

MIT. See LICENSE.