@cuewright/skills

CLI installer for the Cuewright skills framework.

Install the framework into any project in one command — no manual submodule wiring, no shell loops, no symlink errors on Windows.

Pre-public note: While the framework repo is private, cuewright init requires GitHub credentials (SSH key or GitHub token). Anyone with read access to scriswell/cuewright can use the CLI today.

What is Cuewright?

Cuewright is a skills framework for Claude Code. Skills are markdown instruction files that Claude Code discovers and follows automatically — they encode code quality standards, audit checklists, scaffold templates, and governance rules as reusable, version-controlled prompts.

The framework ships as a git submodule with ~25 skills covering CSS, accessibility, security, performance, scaffolding, documentation, and more. It uses a governance model (Discovery → Remediation → Enforcement) so teams can adopt standards incrementally.

This CLI handles the mechanical work: cloning the submodule, wiring the symlinks Claude Code needs to discover skills, scaffolding config files, and keeping everything in sync as the framework evolves.

Quick start

npx @cuewright/skills init

Then follow with /cw-align-project-skills in Claude Code to complete setup.

Commands

cuewright init

Installs the Cuewright framework into the current project.

npx @cuewright/skills init [options]

What it does:

1. Clones the framework as a git submodule at .claude/skills/_framework/
2. Creates skill symlinks at .claude/skills/<name>/ for each skill in the manifest
3. Scaffolds _cuewright/project-config.md from the framework template
4. Creates _cuewright/fragments/project/, _cuewright/references/, and _cuewright/templates/ subdirectories
5. Scaffolds required reference file stubs from the manifest's references field (never overwrites populated files)

Flags:

| Flag | Description | |------|-------------| | --tag <version> | Pin to a specific framework version (default: latest) | | --no-submodule | Clone the framework as a plain directory instead of a git submodule (skills are still symlinked) | | --copy | Use file copies for skills instead of symlinks, and clone the framework as a plain directory (auto-enabled on Windows) | | --symlink | Force symlink mode — exits with an error on Windows if symlinks are unavailable |

--no-submodule vs --copy: These control different things. --no-submodule only changes how the _framework/ directory is created (plain clone vs git submodule) — skill SKILL.md files are still wired as symlinks. --copy goes further: it also replaces those symlinks with file copies, which is required on Windows without Developer Mode.

Existing project adoption: If .claude/skills/_framework/manifest.json already exists (manual install), init adopts the installation without re-cloning. It syncs any missing symlinks, scaffolds the config if absent, and creates any missing required reference stubs.

What init creates:

.claude/skills/
  _framework/                  Git submodule (versioned framework source)
  _cuewright/                  Project-local config and customization
    project-config.md          Set your target, scan paths, and governance stages here
    fragments/project/         Shared context files read by multiple skills
    references/                Per-skill reference files (config, opinions, context)
    templates/                 Scaffold templates (populated by scaffold skills)
  cw-audit-css/
    SKILL.md -> ../_framework/skills/cw-audit-css/SKILL.md   (symlink)
  cw-scaffold-page/
    SKILL.md -> ../_framework/skills/cw-scaffold-page/SKILL.md
  ...

_framework/ is read-only (owned by the submodule). All project customization lives in _cuewright/. The cw-* directories are real directories — only the SKILL.md inside each is a symlink. They are never overridden locally.

cuewright update

Updates the framework to the latest version (or a specified version).

npx @cuewright/skills update [options]

What it does:

• Bumps the submodule pointer (or replaces the directory in copy mode)
• Detects added/removed skills and syncs wiring accordingly
• Scaffolds any missing required reference stubs declared in the new manifest version
• Creates any new template directories declared in the new manifest version
• Warns if a removed skill has a local override directory
• Prints the changelog for the updated version range

Flags:

| Flag | Description | |------|-------------| | --to <version> | Target version (default: latest) | | --dry-run | Show what would change without making changes |

Works on projects installed manually — detects existing installations and adopts them.

cuewright doctor

Verifies the installation is healthy.

npx @cuewright/skills doctor

What it checks:

| Check | Pass | Fail / Warn | |-------|------|-------------| | Framework directory | Present | Missing — run cuewright init | | manifest.json | Valid | Missing or invalid JSON | | Skills wired | All present | Broken or missing symlinks — run cuewright update | | Symlink integrity | File-level, relative | Directory-level or absolute — run cuewright update | | Legacy directories | None found | Unprefixed dirs from old installs — run cuewright update | | project-config.md | Present | Missing — run cuewright init | | Target valid | Matches a framework target | Unknown target — edit project-config.md | | _cuewright/references/ | Present | Missing — run cuewright update | | Required reference files | Present and populated | Missing (FAIL) or unpopulated stub (WARN) — run cuewright init, then edit the file | | Scaffold template dirs | Present and non-empty | Missing (WARN) — run cuewright init; empty (WARN) — run the scaffold skill in Claude Code |

Example output:

✓ Framework installed at v0.21.0
✓ 25/25 skills wired (cw- prefix)
✓ _cuewright/project-config.md found
✓ Target lit-browser found
✓ _cuewright/references/ found
? Reference stub not yet populated: cw-audit-security/security-config.md
  Edit _cuewright/references/cw-audit-security/security-config.md — see _framework/skills/cw-audit-security/SKILL.md for required content.
? Template directory empty: _cuewright/templates/page/
  Run `/cw-scaffold-page` in Claude Code to generate templates from your project.

Exits 0 if all checks pass or only warnings, 1 if any check fails. Every failure and warning includes a fix instruction.

cuewright status

Shows a snapshot of the current installation.

npx @cuewright/skills status [--json]

Example output:

Cuewright v0.14.33
Target:     lit-browser
Skills:     25 total · 2 overridden · 0 from baseline

Governance:
  CSS             Enforcement
  Accessibility   Remediation
  Security        Discovery

--json outputs machine-readable JSON for scripting.

CI/CD usage

doctor exits 1 on any failing check and 0 if all checks pass (warnings are non-blocking). This makes it safe to run in CI:

# GitHub Actions example
- name: Verify Cuewright installation
  run: npx @cuewright/skills doctor

Useful for ensuring the framework stays healthy after dependency updates, submodule pointer bumps, or new developer onboarding.

Migrating from manual installation

If you installed the framework manually before this CLI existed, run cuewright init in the same project. It detects the existing _framework/ directory and adopts the installation: syncs any missing skill symlinks, migrates directory-level symlinks to file-level, scaffolds project-config.md if absent, and creates any missing reference stubs. No re-cloning.

After adoption, cuewright update and cuewright doctor work normally.

CLI vs skills boundary

The CLI and the cw-align-project-skills skill have distinct responsibilities:

| Concern | Owner | Rationale | |---------|-------|-----------| | Directory creation | CLI | Deterministic, testable, no AI required | | Symlink management | CLI | Already owns this | | Reference stub scaffolding | CLI | Reads manifest references field mechanically | | Template directory creation | CLI | Creates the directories; content is AI-generated | | Structural health checks | CLI (doctor) | Single green check means structure is correct | | Stack detection | Skill | Requires AI analysis of code | | Interactive configuration | Skill | Conversational, requires judgment | | Audit baseline | Skill | Runs AI-powered audit skills | | Governance evaluation | Skill | Requires AI judgment | | Template content generation | Scaffold skills | AI-powered, project-specific |

When the CLI is not installed, cw-align-project-skills will stop and prompt you to install it rather than attempting manual file operations.

Windows support

On Windows, directory symlinks require Developer Mode or admin privileges. The CLI detects this automatically and uses copy mode instead. Copied SKILL.md files include a header marking them as auto-generated so update knows which files to refresh.

To force copy mode on any platform: --copy.

Manual installation

Teams that cannot use Node.js can still install the framework manually. See the Cuewright adoption guide for the shell commands.

Troubleshooting

| Symptom | Likely cause | Fix | |---------|-------------|-----| | init fails with repository not found or permission denied | No GitHub credentials for scriswell/cuewright (private repo) | Ensure SSH key or token with read access is configured | | init fails on Windows with symlink error | Symlinks require Developer Mode or admin privileges | Run with --copy, or enable Developer Mode in Settings → Privacy & Security | | doctor reports directory-level symlinks | Manual install used old symlink pattern | Run cuewright update to migrate | | doctor reports legacy directories | Upgraded from pre-v0.15.0 install | Run cuewright update to clean up | | update reports "Could not determine latest version" | Network issue, or tags missing from remote | Use --to <version> to pin explicitly | | add-baseline throws an error | Command is not yet implemented | Coming in a future release |

Framework documentation

For deeper context on how the framework works:

• Adoption guide — full installation and customization reference
• Architecture — governance model, target slot pattern, delivery mechanism; defines key terms (targets, baselines, governance stages, reference files)
• Team baselines — how to set up shared team opinion overrides

License

MIT