claude-cowork-lint

claude-cowork-lint

Lint your Claude skill, plugin, and agent files against the Cowork runtime contract before they hit production.

Why

Cowork (the VM-backed sandbox runtime inside Claude.app) silently strips tools, env vars, and hook events that don't survive its filters. The classic incident: an agent declares tools: [Bash, ...], works fine in Claude Code, then fails silently in Cowork because the desktop excludes Bash from registered built-ins and substitutes an MCP replacement.

claude-cowork-lint ships a versioned, machine-readable copy of that contract (extracted from the Claude.app bundle) plus a checker that catches the classes of mistake that have actually hit skill authors:

• declaring tools that the host-loop or async-dispatch filter strips
• agents with no remaining persistence path (no Write or Edit)
• bare $CLAUDE_PLUGIN_ROOT instead of ${CLAUDE_PLUGIN_ROOT}
• disable-model-invocation: true (the v0.4.0 founder-skills incident)
• plugin-scoped hooks that won't fire in Cowork (issues #16288 / #27398)
• userConfig option names that violate Cowork's secret-name validation
• and more — see docs/RULES.md

Install

npm i -g claude-cowork-lint

The package ships two CLI binaries with the same behaviour:

• claude-cowork-lint — the descriptive name, suited for CI yaml
• cwlint — short alias for daily use

Node.js 20+ required. The bundled runtime contract is shipped inside the npm tarball under contracts/ and loaded at runtime — no post-install step.

Quick start

# Lint a skill repo (descriptive form).
claude-cowork-lint check skill/

# Same thing, short alias.
cwlint check skill/

# CI-style strict mode.
cwlint check . --strict

# JSON output for tooling integration.
cwlint check . --format json

# SARIF for GitHub code-scanning.
cwlint check . --format sarif > findings.sarif

# What rules ship?
cwlint list-rules

# Which Cowork build is the bundled spec from?
cwlint spec-info

Sample output

$ cwlint check skills/

skills/dispatch/SKILL.md
  ! 4    CW003  bare '$CLAUDE_PLUGIN_ROOT' found
          → Use '${CLAUDE_PLUGIN_ROOT}' instead.

agents/bad.md
  ✗ 2    CW001  tool 'Bash' will not be available to a Cowork sub-agent
          name is excluded from registered built-ins in Cowork mode (HOST_LOOP_EXCLUDED_BUILTIN_TOOLS); use 'mcp__workspace__bash' instead.
          → Replace 'Bash' with 'mcp__workspace__bash' in this agent's tools.

Summary: 1 error, 1 warn, 0 info  (spec: claude-app 1.6259.1)

Library API

The package is also usable programmatically from any TypeScript / Node app:

import {
  checkRepo,
  loadDefaultSpec,
  loadSpec,
  type Spec,
  type Report,
  type Finding,
  type Severity,
} from "claude-cowork-lint";

const spec = loadDefaultSpec();
const report = checkRepo("./my-skill", spec, { ignore: [] });
console.log(report.findings);

See docs/CLI.md for the full library + JSON contract.

How the contract is built

contracts/cowork-v<X>.json is a JSON-Schema-validated description of the Cowork runtime gates, extracted from the Claude.app bundle (Electron app + in-VM CLI). The shipped contract cowork-v2.1.121.json corresponds to Claude.app 1.6259.1 / Operon-Core 2.1.121 / in-VM CLI 2.1.138. Each checker rule cites the specific contract field it reads.

The cwlint extract <bundle> subcommand can re-derive the contract from a fresh app.asar using AST-based behavioural anchors (@babel/parser); the scripts/check-for-new-release.ts watcher runs it daily on a cron and produces a candidate diff for human review. See docs/SPEC-EXTRACTION.md and docs/SPEC.md for the full design.

Suppressions

Suppress a single finding inline:

<!-- cwlint: ignore CW003 reason="hand-rolled shell escape needed here" -->
$CLAUDE_PLUGIN_ROOT/foo

Or hash-comment form:

- TaskOutput  # cwlint: ignore CW001 reason="legacy agent — slated for removal"

The marker may sit on the same line as the offending token, or on the line immediately above. The reason="..." field is required; without it the marker is silently ignored.

CI integration