 |
skillsawKeep 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 finds the structural errors and content problems that make agents less reliable: vague language, contradictions, buried priorities, repeated directives, hidden content, broken references, unsafe configuration, and more.
It understands Agent Skills, Agent Plugins v1, Claude Code plugins, OpenAI Codex plugins and marketplaces, CLAUDE.md, AGENTS.md, GEMINI.md, QWEN.md, Cursor, Copilot, Cline, Kiro, hooks, agent configuration, and evals. 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 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
What it catches
- Instruction quality: weak language, contradictions, tautologies, attention dead zones, missing stop conditions, repetitive tool-call examples, and bloated context.
- Structure and compatibility: invalid frontmatter, manifests, commands, skills, agents, hooks, marketplaces, and tool-specific configuration.
- Security risks: embedded secrets, invisible Unicode, encoded payloads, hidden instructions, unallowlisted dynamic context, dangerous hooks, and prohibited MCP servers.
- Repository drift: broken references, unreferenced files, inconsistent terminology, stale baselines, and context-budget regressions.
The description-routing rule checks when-to-use phrasing and descriptions that
only repeat a skill, agent, or command name. Both checks can be configured
independently; see the rule reference.
skillsaw detects the repository type automatically and can lint multiple types in the same project. See supported repository types and the complete rule reference for details.
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 |
Convert plugins to Agent Plugins v1 with skillsaw port |
Porting to Agent Plugins |
| Add checks to pull requests | CI Integration |
| Understand and apply fixes | Autofixing |
| Create project-specific checks | Custom Rules |
| Publish reusable rule packages | Rule Plugins |
| Review the security model | Supply Chain Protection |
| Look up commands and flags | CLI Reference |
| Feed the docs to an AI agent | llms.txt index, llms-full.txt full docs |
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. skillsaw is licensed under the Apache License 2.0.
1 maintainer
Release files for skillsaw 0.19.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| skillsaw-0.19.0.tar.gz | 812.5 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| skillsaw-0.19.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 1.4 MB
Release files / skillsaw-0.19.0.tar.gz
| Download URL | skillsaw-0.19.0.tar.gz |
|---|---|
| Size | 812.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
c5e940dfa03573dfb6fa2ad215a2cbc765397142be9c24cb6acf34305629e551
|
|
BLAKE2b-256 checksum How to use checksums |
26aea99e7010990b3317ac72ffcfe1cc2ef47f6c43ec733505596103607681d4
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 27, 2026.
Transparency logRelease files / skillsaw-0.19.0-py3-none-any.whl
| Download URL | skillsaw-0.19.0-py3-none-any.whl |
|---|---|
| Size | 612.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
77c78298b0f959dd21c1eaf97d0ed5afa380c72ae23db082087268d82b453ace
|
|
BLAKE2b-256 checksum How to use checksums |
a9c44222867a464604b94ffbff938ca451261a484bec7cab01cd22981577e008
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 27, 2026.
Transparency log
