voice-sweep

Operator Skills

Cross-runtime agent skills for shipping things, not preparing to ship things.

Each skill in this monorepo is a single capability — a specific quality gate, audit, or sweep — packaged as a plain Node 18+ CLI first, with Claude Code (Agent Skills spec) and MCP as additional install paths. No LLM calls, no paid APIs, no remote dependencies by default.

What's in here

Skill	What it does	Status
design-audit	Reads every page.tsx and checks it against a design-system ruleset — CTA colors, heading hierarchy, container patterns, semantic-color hygiene.	Wave 1
visual-qa	Crawls a sitemap and runs Playwright across 3 viewports (375 / 768 / 1440) to detect horizontal overflow, clipping, and layout breakage.	Wave 1
voice-sweep	Scans a repo for tone violations against a configurable brand-profile — flags banned phrases, stale stat-claims, and missed reframes.	Wave 1

All three are pure static / browser analysis. They do not call OpenAI, Anthropic, or any external paid API. The Voice Sweep brand-profile is a plain JSON file you own. Bring your own rules.

Install

As an npm CLI (recommended — works in any Node 18+ project)

# Per-skill
npm i -D @operator-skills/design-audit
npm i -D @operator-skills/visual-qa
npm i -D @operator-skills/voice-sweep

Then in package.json:

{
  "scripts": {
    "audit:design": "operator-design-audit",
    "audit:visual": "operator-visual-qa",
    "audit:voice":  "operator-voice-sweep"
  }
}

Each CLI is zero-config out of the box (works on Next.js App Router by default) and accepts a config file (<skill>.config.json) at the repo root for project-specific overrides.

As a Claude Code plugin (for Claude Code / Agent Skills users)

/plugin marketplace add cmj-hub/operator-skills
/plugin install design-audit
/plugin install visual-qa
/plugin install voice-sweep

This installs all three skills via the marketplace manifest in .claude-plugin/marketplace.json. Claude Code reads each skill's SKILL.md and surfaces them based on their trigger phrases. The skill body shells out to the same CLI under the hood.

As MCP servers (Cursor, Gemini, Codex, any MCP-aware agent)

Each skill ships an MCP server entrypoint via fastmcp. Wire into your runtime's MCP config:

{
  "mcpServers": {
    "design-audit": { "command": "npx", "args": ["-y", "@operator-skills/design-audit", "mcp"] },
    "visual-qa":    { "command": "npx", "args": ["-y", "@operator-skills/visual-qa",    "mcp"] },
    "voice-sweep":  { "command": "npx", "args": ["-y", "@operator-skills/voice-sweep",  "mcp"] }
  }
}

Optional: server-connected rule-sets

Each CLI accepts a --remote-config <url> flag (and a matching <skill>RemoteConfig field in the config file) that fetches a JSON ruleset from a URL on demand. Use cases:

• Shared team rules: host a single design-rules.json at your org URL; every project pulls the latest at audit time.
• Versioned brand profiles: voice-sweep can fetch the current brand profile from a CDN so PRs catch the latest banned phrases without a package bump.
• Cached baselines: visual-qa can submit anonymized overflow counts to a self-hosted endpoint to track regressions over time.

These connections are opt-in, no-LLM, and the JSON schema is documented in each skill's references/remote-config.md. Default behavior is fully offline.

Cross-runtime status

Runtime	Status
Plain Node 18+ CLI	Verified Wave 1
Claude Code (Agent Skills spec)	Verified Wave 1
MCP (fastmcp)	Verified Wave 1
Cursor	Planned Wave 2
Gemini CLI	Planned Wave 2
Codex	Planned Wave 2

Cross-runtime ports for Cursor / Gemini / Codex are gated on each runtime's plugin model stabilizing. The Claude Code and MCP variants work in those runtimes today via MCP bridges.

Repo layout

operator-skills/
├── .claude-plugin/marketplace.json   # Claude Code plugin marketplace manifest
├── .github/workflows/ci.yml          # build + validate + publish dry-run
├── packages/                          # shared internal packages (validators, registry)
├── skills/
│   ├── design-audit/
│   │   ├── SKILL.md                  # Agent Skills spec entrypoint
│   │   ├── package.json              # npm publishable
│   │   ├── src/                      # TypeScript source — CLI + MCP shim
│   │   ├── bin/                      # CLI shim (operator-design-audit)
│   │   └── references/               # rule docs (loaded into context as needed)
│   ├── visual-qa/
│   └── voice-sweep/
├── pnpm-workspace.yaml
└── tsconfig.base.json

Develop