Skillsaw

skillsaw

Keep your skills sharp.

A linter for the files that steer AI coding agents.

Agent instructions behave like code, but most teams still review them like prose. skillsaw gives them a linter. It validates structure across every major AI coding ecosystem, guards against many supply-chain attacks, and applies content and context rules backed by research and frontier lab guidance.

It understands Agent Skills, Agent Plugins v1, Claude Code plugins, OpenAI Codex plugins and marketplaces, CLAUDE.md, AGENTS.md, GEMINI.md, QWEN.md, Cursor plugins and marketplaces, Copilot, Cline, Devin, Kiro, OpenCode, Goose recipes, Muse Code, Pi, Grok Build, Google Antigravity, native OpenClaw plugins, hooks, agent configuration, MCP Registry server.json publisher metadata, Vercel skills CLI lockfiles, and eval formats. Safe structural fixes can be applied automatically; everything else comes with precise, agent-friendly guidance.

Get started | Browse the rules | Read the documentation

See it work

Watch an AI agent grade, fix, and configure a repository from scratch.

Try it

Paste this into your coding agent to onboard skillsaw now:

Read and follow the instructions at
https://raw.githubusercontent.com/stbenjam/skillsaw/refs/heads/main/skills/skillsaw-onboard/SKILL.md
to onboard this repo to skillsaw.

Or install the onboarding skill for regular use (recommended). Run this from the repository you want to lint:

npx skills add stbenjam/skillsaw

Select skillsaw-onboard and your coding agent, then ask the agent to use that skill to onboard the repo. See Onboard with AI for plugin installation alternatives.

Or run it yourself. No installation is required with uvx:

uvx skillsaw tree      # See what skillsaw detects
uvx skillsaw           # Lint the current repository
uvx skillsaw fix       # Apply safe, deterministic fixes
uvx skillsaw baseline  # Accept existing findings and fail only on new ones

For lint --fail-on info, use baseline --include-info to accept existing INFO findings too. A configured fail-on: info includes them automatically.

Goose recipes under .goose/recipes/ receive shared content and MCP security checks. Enable the optional recipe checks for standalone recipe directories with:

uvx skillsaw lint my-recipes --type goose --rule goose-recipe-valid --rule goose-subrecipe-references

See Goose recipe support for discovery, path resolution and validation limits.

What it catches

• Multi-ecosystem structure & compatibility: schema, frontmatter, and manifest validation for Agent Skills (SKILL.md), Claude Code, OpenAI Codex (project config, plugins & marketplaces), Cursor plugins & marketplaces, Grok Build (project config, plugins & marketplaces), Google Antigravity (configuration in any customization root — .agents/, .agent/, _agents/, _agent/ — its rules/ and agents/ prose, plugins, hooks, MCP servers and registries), Agent Plugins v1 (plugin.json, mcp.json), GitHub Copilot & VS Code custom agents (.github/agents/), OpenCode configuration, Pi packages and project resources, native OpenClaw plugins (including optional theme and artwork declarations), APM packages, MCP server maps, and MCP Registry metadata.
• Content quality & token economy: research-backed rules detecting instruction drift across duplicate files, excessive instruction budgets, cognitive overload, section length violations, weak language, contradictions, and repetitive inline tool-call examples.
• Discovery & repository integrity: unreferenced bundled files, broken internal file references, inconsistent terminology, missing stop conditions, and stale baselines.
• Security & supply chain:
  • Dangerous lifecycle hooks: blocks arbitrary remote code execution, download-and-execute (curl | sh, wget | bash), and script obfuscation (eval) in hooks.json and settings.
  • Prohibited & unvetted MCP servers: enforces strict MCP allowlists across root, plugin, and custom agent configurations.
  • Prompt injection & stealth payloads: detects invisible Unicode (ASCII smuggling, zero-width tags, bidi overrides), high-entropy encoded payloads (base64/hex), and hidden instructions in comments and code fences.
  • Environment & context security: flags dangerous environment overrides (LD_PRELOAD, NODE_OPTIONS, PYTHONPATH), unallowlisted dynamic context injection, and embedded credentials.
• Deterministic autofixes: safe, instant automated fixes for invalid frontmatter, broken headings, missing manifests, unclosed code fences, and schema keys via skillsaw fix.

skillsaw detects repository types automatically and lints multiple formats in the same project. See supported repository types and the complete rule reference for details.

Pi packages and .pi/ project resources are supported, including native skills, prompt templates, manifest globs, local package references, and first-party .pi/mcp.json servers. Shared MCP credential and policy checks cover these servers; enable pi-mcp-valid for Pi 1.0 field validation, including oauth.authServerMetadataUrl. See Pi configuration checks and Pi MCP checks.

Built for real workflows

skillsaw works locally, in CI, and inside coding-agent workflows. It provides line-level findings, explanations for every rule, deterministic autofixes, baselines for gradual adoption, GitHub and GitLab integration, and text, JSON, SARIF, HTML, and Code Climate output. Rules are configurable, and projects can add local rules or install rule plugins. Typo'd or wrong-typed rule options in .skillsaw.yaml are reported with did-you-mean suggestions instead of being silently ignored.

Goal	Documentation
Install and run skillsaw	Getting Started
Tune rules and exclusions	Configuration
Adopt it without fixing everything at once	Baselines
Review the security model	Supply Chain Protection
Supported ecosystems and tools	Repository Types
Add checks to pull requests & CI	CI Integration
Understand and apply fixes	Autofixing
Convert plugins to Agent Plugins v1	Porting to Agent Plugins
Create project-specific checks	Custom Rules
Publish reusable rule packages	Rule Plugins
Inspect the typed parse tree	Lint Tree
Look up commands and flags	CLI Reference
Feed the docs to an AI agent	llms.txt index, full docs

Updating from 0.20? See the 0.21 upgrade guide for removed commands and rules, new opt-in checks, and Pi skill validation.

Codex portable plugins can place OpenAI metadata and hooks in plugin.json under extensions.com.openai. Skillsaw follows that overlay's precedence over .codex-plugin/plugin.json, validates its declared resources, and checks portable skills/ and mcp.json through the Agent Plugins rules. The optional extensions.com.openai.onboardingSkill must reference a bundled skill's SKILL.md, relative to the plugin root (with or without ./). The manifest rule checks its type, effective skill membership, and containment, including symlink escapes. Project .codex/config.toml files also get a targeted warning when an HTTP MCP server uses the ignored headers field instead of http_headers or env_http_headers.

Measure the result

Every run produces a letter grade based on weighted violation density. The same data can be rendered as a self-contained report card for a README or project dashboard.

skillsaw's own report card, generated with skillsaw badge --large.

Learn how to generate a grade badge and report card for your project.

Contributing

Contributions are welcome. See CONTRIBUTING.md for the project guidelines and DEVELOPMENT.md for the local setup.

Questions and bug reports belong in GitHub Issues. For a shareable diagnostic bundle, run skillsaw feedback in the affected repository and review the ZIP before attaching it to an issue. Files selected with --include or --config are copied verbatim, including BOMs and line endings. Selections default to 4 MiB per file and 16 MiB total across distinct ZIP members; use positive byte values with --max-file-bytes and --max-total-bytes to override these limits. An oversized selection stops before diagnostic lint and creates no bundle. These limits cover selected file bytes only, not diagnostic output or total process memory. skillsaw is licensed under the Apache License 2.0.

Thank you to our contributors

skillsaw is better because people contribute code, bug reports, and ideas. Thank you!