paramour skills

Agentic coding tools know nothing about paramour — it is too new to be in any model's training data. @paramour-js/next therefore ships an Agent Skills–format skill inside the package itself (SKILL.md plus four reference files), and paramour skills installs it into your project so Claude Code, Cursor, Codex, and any other skills-reading tool can work with paramour correctly — and verify their own work with paramour check. Because the skill ships in the npm package, its content always matches the installed API version. The AI agents guide covers the skill's contents and the surrounding agent story; this page documents the command.

npx paramour skills

paramour skills
  ✔ .claude/skills/paramour — installed (5 files)
  ✔ .cursor/skills/paramour — installed (5 files)

The installer detects agent tooling by presence at the project root — the .agents/, .claude/, .codex/, and .cursor/ directories, plus a root AGENTS.md file, which counts as detecting the .agents/ target (so a repo with only an AGENTS.md gets .agents/skills/paramour) — and writes the skill into each detected tool's skills/ directory. With nothing detected it installs to the portable .agents/skills/ location and says so. Commit the installed files: they diff cleanly and version with your lockfile.

Safe re-syncs

Every install writes a .paramour-skills.json manifest next to the skill recording the package version and a content hash per file. On a re-run (after upgrading @paramour-js/next, say):

• files you never touched are updated in place,
• files you edited locally are left as-is — re-run with --force to overwrite them,
• files the package no longer ships are removed when untouched, kept (and untracked) when edited.

A re-run that changes nothing writes nothing. Deleting the skill directory (or the whole tool directory) is a clean uninstall.

Flags

--check never writes, so combining it with --dry-run or --force is a usage error (exit 2).

--check in CI

skills --check verifies that every detected target has an up-to-date copy — add it to CI next to paramour check if you want skill drift to fail builds after package upgrades. With no agent tooling detected there is nothing to verify, so the check passes — a project that never opted into skills can carry it in CI without a permanently red gate:

npx paramour skills --check

Locally-modified files are reported as warnings but do not fail the check — tailoring the skill to your project is legitimate. Files that are missing or stale (the packaged content changed since the last sync) exit 1.

In a repo where only some detected tools should carry the skill (say .cursor/ exists but only Claude skills are installed), scope the CI invocation with --tool claude so the unused tool does not read as missing.

paramour doctor reports the same staleness as a warn-level check — advisory, never build-failing — and paramour init installs the skill automatically when it detects agent tooling (--no-skills opts out).

Exit codes