Skip to content

0.20.0

2026-09-06 · View on GitHub

What's New

  • More supported tools: OpenCode configuration, agents, commands, and skills; Devin rules and skills; GitHub Copilot custom agents; and Muse Code hooks and shared agent memory.
  • Grok Build support: Validate project configuration, agents, hooks, plugins, and marketplaces.
  • Google Antigravity support: Discover customization roots and validate configuration, plugins, hooks, MCP servers, and registries.
  • Expanded Codex validation: Check hooks and MCP servers in .codex/config.toml, with improved compatibility for plugin interface assets.
  • Package metadata checks: Validate MCP Registry server.json files and Vercel skills-lock.json files, including package ownership and source metadata.
  • New instruction checks: Detect missing AGENTS.md imports in CLAUDE.md and optionally flag fully qualified MCP tool names in prose.
  • Better troubleshooting: Generate local diagnostic bundles with skillsaw feedback, view skillsaw explain through an interactive pager, and see which rules account for large finding counts.
  • Smoother upgrades: New skillsaw-update and skillsaw-release-ready skills, plus onboarding guidance for reviewing findings before fixing or baselining them.

Fixes and improvements

  • Reduce false positives for documented secret examples, migration mappings, routing descriptions, and internal references.
  • Consolidate unreferenced directories into fewer findings and recognize files loaded collectively by scripts.
  • Align autofix eligibility with severity settings, report failed writes accurately, and explain skipped symbolic links.
  • Fix case-only command renames on case-insensitive filesystems.
  • Preserve externally installed content during autofix and improve ownership detection in linked worktrees and nested local skill sources.
  • Improve host-specific parsing, hook security checks, directory exclusions, and handling of unreadable discovery paths.
  • Honor explicitly requested package versions in the GitHub Action.
  • Reduce repeated discovery work and Markdown memory use on large repositories.

Upgrading from 0.19.0

  • Keep version: "0.19.0" in .skillsaw.yaml to defer new automatically enabled rules; set it to "0.20.0" when ready.
  • hooks-json-valid is now an alias for claude-hooks-valid only. Configure other hosts' hook rules separately; muse-hooks-valid requires explicit opt-in.
  • skillsaw fix now follows the reported severity scope. Suggested rewrites still require --suggest.
  • Repeated-directive findings now default to INFO, and the function/method terminology group is opt-in.
  • Baselines automatically include INFO findings when configuration sets fail-on: info.
  • skillsaw add and skillsaw docs are deprecated but remain available.

See the upgrade guide for details.

Full changelog: https://github.com/stbenjam/skillsaw/compare/v0.19.0...v0.20.0

Upgrade notes

Skillsaw 0.20.0 expands host-specific validation and improves discovery, autofix consistency and adoption workflows. Review these changes when updating an existing repository from 0.19.0.

Choose when to enable new rules

The version in .skillsaw.yaml gates new rules whose activation is auto. Keeping version: "0.19.0" postpones those rules while you upgrade the executable; changing it to "0.20.0" lets applicable new rules run. An explicit enabled: true bypasses the version gate. Run skillsaw lint -v and use skillsaw explain <rule-id> to review the effective configuration.

See configuration for activation and severity settings. Existing rules can also receive compatibility fixes regardless of the version gate.

Update hook rule overrides

hooks-json-valid is now claude-hooks-valid. The old name remains an alias for Claude validation in configuration, CLI flags, suppressions and baselines. Other hosts have their own shape rules, including codex-hooks-valid, grok-hooks-valid and muse-hooks-valid. Muse hook shape validation is opt-in in 0.20.0 because available real-world coverage is limited; enable muse-hooks-valid explicitly to use it.

An old hooks-json-valid: {enabled: false} entry therefore disables only the Claude rule. Configure each host's rule directly when needed. Some Codex findings have new wording and IDs, so old baseline entries may no longer match; review the findings before accepting them again. Shared hook command checks continue to apply across host formats.

Review findings and baseline policy

Host validators now accept more configurations their released loaders support and report additional malformed fields those loaders discard. Several errors are consolidated by their actual failure scope. Explicit severity settings now also reach primary Grok config and Antigravity MCP findings whose default classification is WARNING; independently classified secondary advisories keep their documented severity.

The function/method group in content-inconsistent-terminology is now opt-in, because these terms commonly describe different things. Other groups retain their defaults.

skillsaw baseline includes INFO findings automatically when the configuration sets fail-on: info. If only the lint command uses --fail-on info, create the baseline with skillsaw baseline --include-info. Review and fix new findings before deliberately accepting existing ones. See the baseline guide.

Keep installed content under its owner's control

Externally sourced skills remain visible to diagnostics by default, but autofix leaves them unchanged. Linked worktrees and nested local lock sources now use the same ownership decisions for discovery and fixing. Plugins under .codex/plugins/ also remain diagnostic-only. See external-content policy.

SAFE fixes remain the default. Suggested rewrites require skillsaw fix --suggest; ambiguous MCP tool names and generated instruction-file banners have additional guards to preserve intended content.

Check CI and deprecated commands

The GitHub Action now honors an explicit with.version package version. Leaving that input empty uses the source at the selected action ref. Keep the action ref and package version intentional; see CI integration.

skillsaw docs and skillsaw add are deprecated but remain available during the transition. Deprecated rules no longer run under auto; explicitly enabling one retains it temporarily and emits a deprecation notice. Existing published rule explanations and the site replace the generated rule-reference workflow described in CI integration.