CLI Reference

skillsaw [command] [options]

skillsaw lint

Lint agent skills, plugins, and AI coding assistant context

Flag	Description	Default
-c, --config	Path to .skillsaw.yaml config file (default: auto-discover from the first path)
-v, --verbose	Show info-level messages
--strict	Treat warnings as errors (equivalent to --fail-on warning; overrides the config file's strict/fail-on settings)
--fail-on	Fail on violations at this severity or above (default: error; --strict is equivalent to --fail-on warning). Overrides the config file's strict/fail-on settings. (choices: error, warning, info)
--format	Output format for stdout (default: text) (choices: text, json, sarif, html, code-climate, gitlab)	text
--output	Write output to FILE. Format is inferred from extension (.htm, .html, .json, .sarif, .txt) or set explicitly with a FORMAT: prefix (e.g. gitlab:report.json). Use the prefix when an extension is ambiguous (e.g. .json could be json or gitlab/code-climate). Can be specified multiple times.
--type	Override auto-detected repository type (repeatable). Values: single-plugin, marketplace, agentskills, dot-claude, coderabbit, apm, promptfoo.
--rule	Only run these rules (repeatable). Config still comes from .skillsaw.yaml.
--skip-rule	Skip these rules (repeatable). Cannot be combined with --rule.
--no-baseline	Ignore baseline file even if .skillsaw-baseline.json exists
--no-custom-rules	Skip custom rules defined in .skillsaw.yaml (recommended for CI on untrusted PRs)
--no-plugins	Skip rules from installed plugin packages (skillsaw.plugins entry points)
--no-progress	Disable the interactive per-rule progress indicator (auto-disabled when stderr is not a terminal)
--color, --no-color	Force ANSI colors and terminal hyperlinks on (--color) or off (--no-color). Default: color only when stdout is a terminal; FORCE_COLOR and NO_COLOR are also honored.

skillsaw fix

Automatically fix lint violations

Flag	Description	Default
-c, --config	Path to .skillsaw.yaml config file (default: auto-discover from the first path)
--dry-run	Preview fixes without writing changes
--suggest	Also apply suggested fixes (not just safe ones)
--rule	Only run these rules (repeatable). Config still comes from .skillsaw.yaml.
--skip-rule	Skip these rules (repeatable). Cannot be combined with --rule.
--no-custom-rules	Skip custom rules defined in .skillsaw.yaml (recommended for CI on untrusted PRs)
--no-plugins	Skip rules from installed plugin packages (skillsaw.plugins entry points)
--no-progress	Disable the interactive per-rule progress indicator (auto-disabled when stderr is not a terminal)
--color, --no-color	Force ANSI colors and terminal hyperlinks on (--color) or off (--no-color). Default: color only when stdout is a terminal; FORCE_COLOR and NO_COLOR are also honored.

skillsaw init

Generate a default .skillsaw.yaml config file

skillsaw list-rules

List all available builtin and plugin rules

skillsaw plugins

List installed rule plugins and the rules they provide

skillsaw explain

Show documentation and effective configuration for a rule

Flag	Description	Default
-c, --config	Path to .skillsaw.yaml config file (default: auto-discover)
--color, --no-color	Force ANSI colors and terminal hyperlinks on (--color) or off (--no-color). Default: color only when stdout is a terminal; FORCE_COLOR and NO_COLOR are also honored.

skillsaw docs

Generate documentation for a plugin, marketplace, or .claude repository

Flag	Description	Default
-c, --config	Path to .skillsaw.yaml config file (default: auto-discover)
--format	Output format (default: html) (choices: html, markdown)	html
-o, --output	Output file or directory (default: skillsaw-docs/). If it ends with .html/.md, writes a single file directly.
--title	Custom title for the documentation
--theme	Color theme for HTML output. Presets: indigo (default), forest-green, ocean-blue, sunset-orange, royal-purple, crimson-red.

skillsaw tree

Display the repository lint tree

Flag	Description	Default
-c, --config	Path to .skillsaw.yaml config file
--format	Output format (default: text) (choices: text, dot)	text

skillsaw baseline

Generate or update the baseline file from current violations

Flag	Description	Default
-c, --config	Path to .skillsaw.yaml config file

skillsaw badge

Grade the repository and write a shields.io badge JSON file

Flag	Description	Default
-c, --config	Path to .skillsaw.yaml config file (default: auto-discover)
-o, --output	Badge JSON output path (default: .skillsaw-badge.json in the repository root)
--large	Also render a self-contained SVG report card (.skillsaw-card.svg) next to the badge JSON
--theme	Report card color theme, used with --large (default: dark) (choices: light, dark)	dark
--color, --no-color	Force ANSI colors and terminal hyperlinks on (--color) or off (--no-color). Default: color only when stdout is a terminal; FORCE_COLOR and NO_COLOR are also honored.

skillsaw add

Scaffold marketplaces, plugins, skills, commands, agents, and hooks

skillsaw add marketplace

Initialize a new marketplace

Flag	Description	Default
--name	Marketplace name
--owner	Owner name (e.g., GitHub username)
--github-repo	GitHub repository (owner/repo)
--color-scheme	Color scheme preset (choices: forest-green, ocean-blue, sunset-orange, royal-purple, crimson-red)
--type	Marketplace type (default: claude-code) (choices: claude-code)	claude-code
--no-example-plugin	Do not create the example plugin
--interactive	Prompt for missing values interactively

skillsaw add plugin

Add a new plugin

Flag	Description	Default
--path	Marketplace root path

skillsaw add skill

Add a skill to a plugin

Flag	Description	Default
--plugin	Target plugin name (auto-detected if unambiguous)
--path	Marketplace root path

skillsaw add command

Add a command to a plugin

Flag	Description	Default
--plugin	Target plugin name (auto-detected if unambiguous)
--path	Marketplace root path

skillsaw add agent

Add an agent to a plugin

Flag	Description	Default
--plugin	Target plugin name (auto-detected if unambiguous)
--path	Marketplace root path

skillsaw add hook

Add a hook to a plugin

Flag	Description	Default
--plugin	Target plugin name (auto-detected if unambiguous)
--path	Marketplace root path

Color and hyperlinks

Commands that produce terminal output (lint, fix, explain, badge) decide whether to emit ANSI colors with the standard cascade, strongest first:

1. --color / --no-color
2. FORCE_COLOR — a non-empty value forces color on even through a pipe (0 forces it off); useful in CI logs that render ANSI
3. NO_COLOR — present (even empty) disables color
4. Otherwise color is used only when stdout is a terminal

Piped or redirected output is plain text by default. When color is enabled on a real terminal (TERM other than dumb), text output also emits OSC 8 hyperlinks: rule ids link to their documentation pages, file paths become clickable file:// links, and the per-rule "Rule docs" URL footer collapses to a one-line hint. Hyperlinks are never emitted through a pipe, even when color is forced.