Use when user asks to "conform package", "check standards", "sync package", "audit project config", "update catalogs", "add github actions", "setup eslint", "configure vitest", "init package", "create npm package", "scaffold project", "init nuxt module", "create nuxt module", "scaffold module", "sync nuxt module", "add playground", "setup test fixtures", "configure @nuxt/test-utils", or needs help with pnpm workspace catalogs, obuild config, standard npm package architecture, Nuxt module architecture, runtime vs build-time code, addImports, addServerHandler, or nuxt-module-builder.
user_invocable
true
Package Conform Skill
Conform a package to standardized architecture, or scaffold a new one.
Usage
/pkg-conform # conform existing project
/pkg-conform my-package # scaffold new package
Behavior
New project: scaffold with all standards below
Existing project: compare and offer to sync each component
Detection
Check for package.json in cwd to determine new vs existing.
Check for packages: in pnpm-workspace.yaml to detect monorepo vs single repo.
Check for @nuxt/module-builder in devDependencies to detect Nuxt module -> apply Nuxt-specific patterns.
Project Type Detection
Determine project type from the absolute path of the working directory:
Path pattern
Type
Description
*/pkg/*
Package
Published library/module -- needs exports, build, release
*/sites/* or */site/*
Site
Nuxt app -- private, no exports, deploy not publish
If path doesn't match either pattern, fall back to heuristics: private: true + nuxt in deps -> Site, otherwise Package.
IMPORTANT: The project type determines which rules apply. Do NOT apply Package-only rules (exports, obuild, test:attw, prepack, release) to Sites, and do NOT apply Site-only rules (nuxi scripts, generate, preview) to Packages.
Gotchas
Catalog version conflicts -- when migrating deps to catalog:, check that the catalog version satisfies all consumers in the monorepo. A single catalog: entry shared across packages with different version requirements will break.
obuild vs tsc -- obuild doesn't do type-checking. If you remove tsc from the build, types won't be validated. Always keep typecheck as a separate script.
module: preserve in tsconfig -- this is correct for packages built with obuild, but breaks Nuxt apps that need module: esnext or defer to .nuxt/tsconfig.json. Don't apply package tsconfig rules to sites.
ESM-only exports trap -- removing CJS exports breaks consumers that haven't migrated to ESM. For public packages, confirm the audience before dropping .cjs.
pnpm install after catalog changes -- lockfile must be regenerated. If you edit pnpm-workspace.yaml catalogs, always run pnpm install before running any other commands.
Nuxt module dev:prepare order -- must run before typecheck or test. Missing this causes confusing "module not found" errors from auto-generated types.
Site vs Package misdetection -- path-based detection (*/pkg/* vs */sites/*) can fail for unusual directory structures. Always verify the detected type before applying rules.
UnJS Conventions
Always prefer UnJS ecosystem packages over Node.js builtins:
Instead of
Use
Import
path
pathe
import { join, resolve } from 'pathe'
console.log/warn/error
consola
import { consola } from 'consola'
fetch
ofetch
import { $fetch } from 'ofetch'
fs.readFile (JSON)
pkg-types
import { readPackageJSON } from 'pkg-types'
Object.assign defaults
defu
import { defu } from 'defu'
require.resolve
mlly
import { resolveImports } from 'mlly'
EventEmitter
hookable
import { createHooks } from 'hookable'
yargs/commander
citty
import { defineCommand } from 'citty'
cosmiconfig
c12
import { loadConfig } from 'c12'
git clone templates
giget
import { downloadTemplate } from 'giget'
Principles: ESM-only, minimal deps, full TypeScript, universal (Node/browser/edge)
Package.json
Package (single repo / monorepo)
See references/pkg-package-json.md for single repo and monorepo root templates.
Site (Nuxt app)
See references/site-package-json.md for template, optional scripts, and rules.
See references/site-structure.md for Nuxt 4 directory layout.
See references/site-configs.md for nuxt.config.ts, tsconfig, eslint, .npmrc, .gitignore templates.
Test Structure
test/
unit/ # unit tests
*.test.ts
e2e/ # e2e/integration tests
*.test.ts
fixtures/ # test data
Nuxt Module (when @nuxt/module-builder detected)
Build-time vs Runtime
Context
Location
Access
Registration
Build-time
src/module.ts
@nuxt/kit, nuxt config
runs during nuxi build
App runtime
src/runtime/app/
Vue, useNuxtApp()
addPlugin(), addImports()
Server runtime
src/runtime/server/
H3, Nitro
addServerHandler(), addServerPlugin()
Shared
src/runtime/shared/
Pure JS only
import via alias
See references/nuxt-module-template.md for full module.ts template with registration examples.
See references/nuxt-module-structure.md for directory layout and runtime rules.
References
See references/ for detailed templates:
references/pkg-package-json.md - single repo and monorepo package.json templates
Determine from cwd path whether this is a Package (*/pkg/*) or Site (*/sites/*, */site/*).
Phase 1: Config Review
Read the config files directly (one batch of parallel Read calls) and compare against the checklist. These are small files and the comparison is cross-cutting (catalog ↔ lockfile ↔ exports ↔ tsconfig interact), so read them inline rather than fanning out to sub-agents — you keep the whole picture in context and avoid losing nuance across separate reports.
Read for all project types:
pnpm-workspace.yaml, package.json — deps, catalogs, packageManager, type
.github/workflows/*.yml — action versions against v6 standards
If Package, also read: build.config.ts, vitest.config.ts, package exports, release scripts.
If Site, also read: nuxt.config.ts, app/ structure (pages/, layouts/, components/), .npmrc.
If Nuxt module (Package + @nuxt/module-builder), also read: src/module.ts (registration methods, resolver, options), src/runtime/app/ (composables/plugins/imports), src/runtime/server/ (handlers/plugins/middleware — verify no Vue deps), playground/ + test/fixtures/ (nuxt.config, prepare scripts, test patterns).
For a large monorepo where a single read pass would be unwieldy, delegate per-package walks to subagent_type=Explore. For a single package or site, read inline.
Phase 2: Apply Changes
Based on the review, apply necessary updates using the appropriate checklist (Package or Site).
