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	Replace packaging-type detection (repeatable). Tool types are always detected from the checkout, and plugin-contributed types too. Values: single-plugin, marketplace, agentskills, dot-claude, coderabbit, apm, promptfoo, codex-plugin, codex-marketplace, codex-project, agent-plugin, mcp-registry, cursor, copilot, cline, devin, opencode, muse, grok-project, grok-plugin, grok-marketplace, kiro, gemini, qwen, agents-md, claude-md, skills-lock, antigravity-plugin, antigravity.
--rule	Only run these rules and their validation dependencies (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.

Path arguments

lint and fix accept files as well as directories. A file resolves to the directory that owns it — never further out, so lint reads and fix writes only under the path you named. Manifest rules discover from a plugin's root, so to run them name the plugin's root directory rather than a manifest file inside it. Duplicate paths and paths nested inside another named path are dropped.

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 and their validation dependencies (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 feedback

Create a local diagnostic bundle for a bug report

Flag	Description	Default
-c, --config	Path to .skillsaw.yaml config file to copy into the bundle verbatim (default: auto-discover only; review it for secrets yourself)
-o, --output	Bundle ZIP path (default: .skillsaw-feedback/ under the repository)
--message	Short description of the problem to include in the bundle
--include	Copy a repository-relative UTF-8 text file into the bundle verbatim (repeatable; review it for secrets yourself)
--max-file-bytes	Maximum raw bytes per --include/--config file (positive integer; default: 4194304 / 4 MiB)	4194304
--max-total-bytes	Maximum retained --include/--config bytes across distinct ZIP members (positive integer; default: 16777216 / 16 MiB)	16777216
--with-extensions	Run custom and installed plugin rules in the diagnostic lint run
--json	Print the bundle result as JSON for agents and automation

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.
--pager, --no-pager	Use a pager (e.g. less) to display documentation (default: auto when tty present)

skillsaw docs

Deprecated: generate repository documentation

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 port

Port Claude Code and Codex plugins to Agent Plugins v1 packages

Flag	Description	Default
--to	Target format (default and currently only: agent-plugin)	agent-plugin
-c, --config	Path to .skillsaw.yaml config file (default: auto-discover from the path)
--marketplaces	Comma-separated marketplace catalogs to generate for the ported plugins so catalog-driven clients can discover them (default: codex; use 'none' to skip)	codex
--dry-run	Show the files that would be written without writing them
--no-progress	Disable the interactive conversion 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 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
--include-info	Include INFO findings (automatic with fail-on: info in config)
--no-custom-rules	Skip custom rules defined in .skillsaw.yaml (recommended for untrusted repositories)
--no-plugins	Skip rules from installed plugin packages (skillsaw.plugins entry points)

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
--no-custom-rules	Skip custom rules defined in .skillsaw.yaml (recommended for untrusted repositories)
--no-plugins	Skip rules from installed plugin packages (skillsaw.plugins entry points)
--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

Deprecated: scaffold marketplaces, plugins, and components

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.