Prompterium

Central library for Cursor project context: agent skills, rules, hooks, and templates. Prompterium holds the canonical copies; you sync them into any app repo’s .cursor/ folder and commit there so your team gets the same prompts without cloning this repo.

What goes where

In Prompterium	After sync (in your app)	Loaded by Cursor?
catalog/skills/<name>/SKILL.md	.cursor/skills/<name>/	Yes — agent skills
catalog/rules/*.mdc	.cursor/rules/	Yes — rules
catalog/commands/*.md	.cursor/commands/	Yes — slash commands (legacy)
catalog/hooks/hooks.json, catalog/hooks/*	.cursor/hooks.json, .cursor/hooks/	Yes — hooks
catalog/templates/**	.cursor/templates/	Only if referenced by a skill or rule

Do not copy anything into ~/.cursor/skills-cursor/ — that directory is managed by Cursor.

Docs: Skills, Rules, Hooks.

Repository layout

catalog/          # source of truth (shared library)
src/              # TypeScript sync implementation
dist/             # build output (generated; not committed)
scripts/sync.sh   # optional bash sync (same catalog layout)
package.json      # npm package
AGENTS.md         # conventions for agents working in this repo

Development

npm install
npm run check      # typecheck + eslint + prettier
npm run build      # compile src/ -> dist/
npm run sync       # dry-run sync into this repo (requires build)

See catalog/README.md for contribution conventions.

Working in this repository

Prompterium has no .cursor/ folder in the repo—only catalog/ plus sync tooling. Edit the catalog here; run ./scripts/sync.sh on app repos to install context. See AGENTS.md for agent conventions.

Requirements

From git: macOS or Linux with bash and rsync (optional; Node sync below works cross-platform).

From npm: Node.js 18+ only.

Install as an npm package (recommended for apps)

In your application repository:

npm install -D prompterium
npx prompterium sync .

Add a script for repeat use:

{
  "devDependencies": {
    "prompterium": "^0.1.0"
  },
  "scripts": {
    "cursor:sync": "prompterium sync ."
  }
}

Then:

npm run cursor:sync
git add .cursor && git commit -m "Sync Cursor context from Prompterium"

Bump the prompterium version in package.json when you want new skills or templates from the library.

Publish to npm (maintainers)

Automated (recommended): pushing a tag v* runs .github/workflows/release.yml, which creates a GitHub Release and publishes to npm with provenance (so the package can appear under the repo Packages section).

1. In the GitHub repo: Settings → Secrets and variables → Actions → add NPM_TOKEN (npm granular token with publish), or on npmjs.com configure Trusted publishing for this GitHub repo (then OIDC can replace the token).
2. Bump and tag: npm version patch (creates commit + v* tag), then git push origin main --tags.

Manual: npm login, bump version, npm publish --access public (use --access public for scoped names).

The published tarball includes catalog/, compiled dist/, and the prompterium CLI only—no postinstall hooks.

Quick start (git clone)

1. Clone Prompterium (once, anywhere on your machine).

2. From Prompterium:

   chmod +x scripts/sync.sh
   ./scripts/sync.sh /path/to/your-app-repo

3. In the app repo, commit the updated .cursor/:

   cd /path/to/your-app-repo
   git add .cursor
   git commit -m "Sync Cursor context from Prompterium"

Teammates who clone the app get .cursor/ automatically; they do not need Prompterium unless they want to run sync themselves.

Day-to-day workflow

1. Add or edit content under catalog/ in Prompterium; commit, push, and npm version patch + npm publish when sharing via npm.
2. In each app: update the prompterium devDependency (or re-run install at latest), then npx prompterium sync . (or ./scripts/sync.sh if using a git checkout).
3. Commit .cursor/ in each app repo.

Adding a skill

1. Create catalog/skills/my-skill/SKILL.md.

2. Frontmatter (required):

   ---
   name: my-skill
   description: One line — when the agent should use this skill.
   ---

3. Run sync, then commit in the target app.

Optional: disable-model-invocation: true for user-only slash-style workflows.

Adding a rule

Add catalog/rules/my-rule.mdc with description, and either alwaysApply: true or globs: **/*.ts. Sync copies it to .cursor/rules/.

Hooks

Put hooks.json and scripts under catalog/hooks/. Sync copies hooks.json to .cursor/hooks.json and scripts to .cursor/hooks/. v1 overwrites .cursor/hooks.json in the target app — keep shared hooks here; app-only hooks belong in the app repo outside Prompterium or wait for v2 merge support.

Sync behavior (v1)

• Additive / update: files in the app’s .cursor/ that are not in the catalog are left alone.
• No prune: deleting a skill from Prompterium does not remove it from an app until you delete it manually in the app (v2 may add --delete or a lockfile).
• --dry-run: shows what would copy without writing.

Roadmap

• Manifest / profiles (prompterium.yaml) for per-app subsets
• Safe removal sync and hooks.json merge
• Validation script for SKILL frontmatter

License

MIT