How to Publish AI Rules as an npm Package

npm: The Developer's Package Manager for Everything

Developers already use npm for: ESLint configs (@org/eslint-config), TypeScript configs (@org/tsconfig), Prettier configs (@org/prettier-config), and component libraries (@org/ui). Why not AI rules? Publishing rules as an npm package: uses the same distribution mechanism developers already know. Install: pnpm add -D @org/ai-rules. The rules: delivered to node_modules and copied to the project root via a postinstall script. Version management: semantic versioning via npm. Updates: pnpm update @org/ai-rules.

The npm model for rules: the package contains the canonical rule files (CLAUDE.md, .cursorrules). A postinstall script: copies these files to the project root where AI tools expect them. The developer: installs the package and the rules appear in the right locations automatically. Updates: the developer updates the package version and the postinstall copies the updated rules. The workflow: identical to updating any other npm dependency.

When to use npm distribution: organizations that already use scoped npm packages for shared configs (the team is familiar with the @org/ pattern), projects where rule files should be treated as dependencies (versioned, locked, updatable), and scenarios where RuleSync CLI is not available (the npm package is self-contained — no external service needed). AI rule: 'npm distribution: for organizations already in the npm ecosystem. RuleSync: for organizations that want a dashboard, sync automation, and team management. Both work. Choose based on existing tooling.'

Step 1: Package Structure and Content

Create the npm package: mkdir @org/ai-rules && cd @org/ai-rules && npm init --scope=@org. The package structure: package.json (name, version, description, postinstall script), rules/ directory (source rule files — base.md, typescript.md, react.md), scripts/ directory (postinstall script that generates output files), and generated/ directory (the output files — CLAUDE.md, .cursorrules — generated from the source rules by the build script).

The build script: composes the source rule files into the output files. scripts/build.js: reads base.md + the applicable technology rules, concatenates them with section headers, and writes CLAUDE.md and .cursorrules to the generated/ directory. The build: runs as a prepublish step (before npm publish). The package: published with the pre-built output files. AI rule: 'Build before publish. The package contains pre-built output files. The postinstall: copies the built files. It does not build from source (which would require the build dependencies in the consuming project).'

The postinstall script: scripts/postinstall.js. Copies: generated/CLAUDE.md to the project root (../../CLAUDE.md — two levels up from node_modules/@org/ai-rules/). Copies: generated/.cursorrules to the project root. The postinstall: runs automatically after pnpm install. The developer: sees CLAUDE.md and .cursorrules appear in their project root. No manual steps. AI rule: 'The postinstall copies to the project root. The path: relative to node_modules/@org/ai-rules/. Test the path calculation on different operating systems (macOS, Linux, Windows).'

Step 2: Versioning and Publishing

Semantic versioning: patch (1.0.1): typo fixes, wording clarifications — no AI behavior change. Minor (1.1.0): new rules added, existing rules updated — AI behavior changes. Major (2.0.0): rules removed, fundamental pattern changes — breaking changes. The version: communicates the significance to the consuming developer. They: read the changelog for minor/major versions and skip the changelog for patches.

Publishing: npm publish (public) or npm publish --registry https://npm.pkg.github.com (GitHub Packages for private/organization packages). For organizations: use a private npm registry (GitHub Packages, Verdaccio, Artifactory) to keep rules internal. The scope (@org/): signals that this is an organization package, not a public community package. AI rule: 'Private registry for organization rules. Public npm: only if you intentionally want to share with the community (see the sharing tutorial).'

Lockfile integration: when the developer installs the package, the version is locked in pnpm-lock.yaml (or package-lock.json). The lockfile: ensures every developer and CI run uses the exact same rule version. No drift. No 'it works on my machine with different rules.' The lockfile: the same version control mechanism used for all other dependencies. AI rule: 'Lockfile integration: the key advantage of npm distribution. Every developer and CI: uses the exact same rule version. No drift. No surprises.'

Step 3: Consuming and Updating the Package

Installing: pnpm add -D @org/ai-rules. The postinstall: copies CLAUDE.md and .cursorrules to the project root. The developer: verifies with a quick AI prompt ('What conventions does this project follow?'). Done. First-time setup: 30 seconds.

Updating: pnpm update @org/ai-rules. The postinstall: overwrites the existing CLAUDE.md and .cursorrules with the updated versions. The developer: checks git diff to see what changed in the rules. Commits the updated files. For major version updates (breaking changes): read the changelog first, then update. AI rule: 'pnpm update for rules: identical to updating any other package. The developer already knows this workflow. No new tool to learn.'

Gitignore consideration: do NOT gitignore the generated files (CLAUDE.md, .cursorrules). They must be committed so that: developers who do not have the npm package installed still get the rules (the files are in the repo), AI tools read the files from the repo (not from node_modules), and the CI pipeline can validate the rules (the files exist at the expected paths). The package: delivers the files. Git: distributes them to the team. Both: needed for complete coverage. AI rule: 'The generated files are committed to git. The npm package is the delivery mechanism. Git is the distribution mechanism to the team.'

npm Package Summary

Summary of publishing AI rules as an npm package.

• Concept: distribute rules like any npm package. Install, postinstall copies files, done
• Structure: rules/ source files, scripts/ postinstall, generated/ output files (CLAUDE.md, .cursorrules)
• Build: prepublish composes source rules into output files. Package ships pre-built
• Postinstall: copies generated files to project root. Runs automatically on pnpm install
• Versioning: semver (patch = text fix, minor = behavior change, major = breaking change)
• Registry: private (@org/ scope, GitHub Packages) for organization rules. Public for community sharing
• Lockfile: version locked in pnpm-lock.yaml. Every developer: same rules. No drift
• Do not gitignore: commit generated files. The package delivers. Git distributes to the team