---
id: skillsaw
version: "0.18.0"
license: Apache-2.0
license_treatment: permissive
maintenance: active
---

# skillsaw — A configurable linter for agent skills, plugins, and AI coding assistant context

License: permissive · Maintenance: active · Downloads: 574.3K/mo

## What it is and what it does

skillsaw is a linter for the configuration and instruction files that steer AI coding agents—files like CLAUDE.md, AGENTS.md, Agent Skills, and plugin manifests. It treats agent instructions as code rather than prose, catching structural errors (invalid frontmatter, broken references), quality issues (vague language, contradictions, buried priorities), and security problems (embedded secrets, hidden instructions, dangerous configurations) that make agents less reliable. It understands multiple agent frameworks and plugin standards, detects repository type automatically, and can lint multiple types in the same project.

The tool runs locally, in CI pipelines, and inside agent workflows. It produces line-level findings with explanations, applies deterministic autofixes where safe, supports baselines for gradual adoption, and outputs to text, JSON, SARIF, HTML, and Code Climate formats. Rules are configurable, and teams can add local rules or install rule plugins. Every run generates a weighted grade based on violation density.

Use it for:

- Catch structural errors and broken references in agent skill and plugin files before they cause agent failures.
- Enforce consistent terminology and description quality across a repository of agent instructions and configurations.
- Detect embedded secrets, invisible Unicode, and hidden instructions in agent context files as part of a security review.
- Integrate linting into CI/CD to fail pull requests when new instruction quality violations are introduced.
- Gradually adopt linting standards across an existing codebase using baselines, fixing only new violations.
- Generate a grade badge and report card for a project's agent instruction quality to display in README or dashboards.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

A linter for AI agent instruction files that detects structural errors, vague language, contradictions, security risks, and configuration problems in agent skills, plugins, and coding assistant context.

Yes. skillsaw addresses a real gap: agent instructions are now critical infrastructure but lack the tooling that code has. The package is actively maintained, has low install friction, carries no security vulnerabilities, and is licensed permissively. It's in Beta but has been released for months and sees substantial monthly downloads. Install it if you maintain agent skills, plugins, or AI coding assistant context files.

## Install

pip install skillsaw
uv add skillsaw
poetry add skillsaw

## Installing skillsaw

Before you install: Active project released 7 days ago with a recent commit history. Low install friction: pure Python wheel with four common dependencies (PyYAML, ruamel.yaml, markdown-it-py, jsonschema). Supports Python 3.9 through 3.14.

License in practice: Apache License 2.0 (permissive): you can use, modify, and distribute skillsaw freely in commercial and private projects, provided you include the license notice and state significant changes.

Quickstart:

pip install skillsaw

# Run linter on current repository
import subprocess
result = subprocess.run(['skillsaw'], capture_output=True, text=True)
print(result.stdout)

Requires Python 3.9 or later. Designed to run against a repository containing agent instruction files (skills, plugins, agent configs); running it without such files will produce minimal output.

Verify before relying:

- Whether the package can be used as a library (imported and called from Python) or only as a CLI tool.
- Performance characteristics when linting large repositories or many instruction files.
- Whether custom rule plugins require additional dependencies beyond the four listed runtime deps.

## Package facts

- License: Apache-2.0 (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 574.3K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

agent instruction linter, AI skill validation, agent configuration checker, plugin manifest linter, coding agent context quality, skill file linter, agent prompt linter, ai-agents, linting, prompt-engineering

[View on SkillFed](https://skillfed.io/packages/skillsaw) · [View on PyPI](https://pypi.org/project/skillsaw/)