README.md

July 7, 2026 · View on GitHub

skillsaw

Keep your skills sharp. 40+ rules catch weak language, contradictions, attention dead zones, and structural issues — then auto-fix them.

▶️ Easy onboarding with AI! — watch an AI agent grade, fix, and configure a repo from scratch.

_{skillsaw's own report card, generated by skillsaw badge --large}

Full documentation at skillsaw.org — supports Claude Code plugins, agentskills.io, CLAUDE.md, AGENTS.md, Cursor, Copilot, Gemini, Kiro, CodeRabbit, and more.

Quick Start

No install required — run with uvx skillsaw (or install it for repeated use).

# 1. See what skillsaw detects in your repo
skillsaw tree

# 2. Lint it (current directory by default — also accepts multiple
#    directories and/or SKILL.md files: skillsaw lint dir1/ dir2/SKILL.md)
skillsaw

# 3. Fix what you can automatically
skillsaw fix

# 4. Accept remaining violations as the baseline
skillsaw baseline

# Done — only new violations will fail from here on
skillsaw   # exit 0

# Curious why a rule fired (or didn't)?
skillsaw explain content-weak-language

For all commands and flags, see the CLI Reference.

Tip

:sparkles: Onboard with AI — let your coding agent handle the entire setup in one shot.

Claude Code:

claude plugin marketplace add stbenjam/skillsaw
claude plugin install skillsaw@skillsaw-marketplace

Then type /skillsaw-onboard — it installs skillsaw, lints your repo, autofixes what it can, walks you through manual fixes, sets up CI, and creates a baseline.

Other agents — see the Getting Started guide.

Installation

Via uvx (easiest, no install required)

uvx skillsaw
uvx skillsaw /path/to/skills

Via pip

pip install skillsaw

From source

git clone https://github.com/stbenjam/skillsaw.git
cd skillsaw
pip install -e .

Using Docker

docker pull ghcr.io/stbenjam/skillsaw:latest
docker run -v $(pwd):/workspace ghcr.io/stbenjam/skillsaw

See the Getting Started guide for GitHub Actions and other installation options.

What skillsaw checks

skillsaw automatically detects your repository structure. A repository can match multiple types simultaneously.

Supported repository types include:

The built-in rules cover structural validation, content intelligence, context budgets, supply-chain checks, settings, MCP configuration, hooks, commands, skills, agents, and marketplace registration.

Browse the Repository Types and Builtin Rules references for the full details.

Configuration

Generate a default .skillsaw.yaml in your repository root:

skillsaw init

This creates a config file with all builtin rules, their defaults, and descriptions. Edit it to enable, disable, or customize rules for your project. See .skillsaw.yaml.example for a complete example.

Common configuration topics:

Baseline

When adopting skillsaw on an existing project, you may have many pre-existing violations. The baseline feature lets you snapshot current violations so that skillsaw lint only reports new ones — existing violations are accepted and won't cause failures.

# Generate .skillsaw-baseline.json from current violations
skillsaw baseline

# Run lint without baseline filtering
skillsaw lint --no-baseline

The baseline matches violations by fingerprint, so it survives ordinary line drift and reports stale entries when old violations are fixed. See the Baseline guide for matching behavior, ratchet behavior, and refresh workflow.

CI Integration

# GitHub Actions
- uses: stbenjam/skillsaw@v0
  with:
    strict: true

# GitLab CI — outputs Code Quality JSON for MR widgets
skillsaw:
  script:
    - pip install skillsaw==0.16.0
    - skillsaw lint --output gitlab:gl-code-quality-report.json .
  artifacts:
    reports:
      codequality: gl-code-quality-report.json

Output formats for --format / --output: text, json, sarif, html, code-climate, and gitlab.

For PR review comments, the secure two-workflow pattern, plugins, custom rules, and full configuration options, see the CI Integration guide.

Pre-commit

skillsaw ships a Pre-commit hook. Add this to your repository's .pre-commit-config.yaml:

repos:
  - repo: https://github.com/stbenjam/skillsaw
    rev: v0.16.0  # or pin a full commit SHA
    hooks:
      - id: skillsaw

See the Pre-commit guide for details.

Quality Grade & Badge

Every lint run computes a letter grade (A+ through F) summarizing repository quality, shown in the text summary and in the JSON report under summary.grade.

Add the badge to your README:

[![skillsaw grade](https://img.shields.io/endpoint?url=https%3A%2F%2Fraw.githubusercontent.com%2FOWNER%2FREPO%2Fmain%2F.skillsaw-badge.json)](https://skillsaw.org/)

Generate the badge data with:

skillsaw badge .

See skillsaw badge for badge generation options.

README report card

skillsaw badge --large additionally renders .skillsaw-card.svg, a self-contained SVG report card (no external fonts, images, or network requests) showing the giant letter grade, weighted violation density, content-token count, plugin/skill counts, and the top three offending rules:

skillsaw badge --large .               # dark theme (default)
skillsaw badge --large --theme light .

Commit the SVG next to the badge JSON and embed it:

[![skillsaw report card](https://raw.githubusercontent.com/OWNER/REPO/main/.skillsaw-card.svg)](https://skillsaw.org/)

The grading scale is fixed (deliberately not configurable), so cards are comparable across repositories. Note that GitHub proxies README images through its camo cache, so a freshly regenerated card can appear stale for a while after pushing.

Supply Chain Protection

skillsaw is designed for repositories that execute AI-agent instructions, plugins, hooks, and custom rules. For untrusted pull requests:

Pin skillsaw to a specific version.
Keep custom rules disabled unless you trust the source.
Use the secure CI workflow when posting PR comments.
Review hooks, MCP servers, and settings changes carefully.

See Supply Chain Protection for the threat model and hardened CI patterns.

Autofixing

skillsaw applies deterministic fixes for structural issues. Content-quality violations that need judgment are fixed by coding agents (Claude Code, Cursor, etc.) — the lint interface is familiar, and every violation points to skillsaw explain which includes how-to-fix guidance.

skillsaw fix                     # Apply safe structural fixes
skillsaw fix --suggest           # Also apply suggested fixes
skillsaw fix --dry-run           # Preview safe fixes as colored diffs
skillsaw fix --suggest --dry-run # Preview safe + suggested fixes

See Autofixing for deterministic fix confidence levels, agent workflows, and idempotency guarantees.

Custom Rules and Plugins

Create custom validation rules by extending the Rule base class and referencing them from .skillsaw.yaml:

custom-rules:
  - ./my_custom_rules.py

To share rules across repositories, package them as a rule plugin — a pip-installable package that registers rules through the skillsaw.plugins entry point group.

Start with Custom Rules for local checks and Rule Plugins for reusable distribution.

Scaffolding

skillsaw add scaffolds marketplaces, plugins, and components with best-practice structure, CI, and branding out of the box.

skillsaw add marketplace
skillsaw add plugin my-plugin
skillsaw add skill my-skill
skillsaw add command greet
skillsaw add agent helper
skillsaw add hook PreToolUse

See Scaffolding for context detection, marketplace layouts, and generated files.

Documentation Generation

skillsaw can generate documentation for your plugins, skills, and marketplaces:

skillsaw docs
skillsaw docs --format markdown
skillsaw docs -o my-docs/

See the CLI Reference for all documentation generation options.

Example Output

Linting: /path/to/skills-repo

Errors:
  ✗ ERROR (agentskill-name) [*] [skills/my-skill/SKILL.md:2]: Name 'My Skill' must contain only lowercase letters, numbers, and hyphens
  ✗ ERROR (plugin-json-required) [plugins/git/.claude-plugin/plugin.json]: Missing plugin.json

Warnings:
  ⚠ WARNING (agentskill-description) [skills/helper/SKILL.md:3]: Description exceeds 1024 characters (1087)
  ⚠ WARNING (plugin-readme) [plugins/utils]: Missing README.md (recommended)

Summary:
  Errors:   2
  Warnings: 2
  [*] 1 violation(s) fixable with `skillsaw fix`

Violations that skillsaw fix can resolve automatically are marked with [*] (safe fixes) or [?] (suggested fixes, applied with skillsaw fix --suggest), and the summary counts each kind.

Color and hyperlinks

Terminal output is colored only when stdout is a terminal — piped or redirected output stays plain. Force it with --color or --no-color, which outrank the FORCE_COLOR environment variable (non-empty forces color on even through a pipe, useful in CI; 0 forces it off), which outranks NO_COLOR (present disables color). When color is enabled on a real terminal (TERM other than dumb), rule ids link to their documentation pages and file paths become clickable file:// links, replacing the "Rule docs" URL footer with a one-line hint. Hyperlinks are never emitted through a pipe, even when color is forced.

Migrating from claudelint

This project was renamed from claudelint to skillsaw. To migrate:

Update your package: pip install skillsaw (instead of pip install claudelint)
Rename .claudelint.yaml to .skillsaw.yaml (the old name is still discovered as a fallback)
Update CLI usage: skillsaw (instead of claudelint)
Update imports in custom rules: from skillsaw import ... (the old from claudelint import ... still works)

The claudelint command still works as a shim but prints a deprecation warning.

Development

# Run tests
pytest tests/ -v

# Format code
black src/ tests/

# Build Docker image
docker build -t skillsaw .

See DEVELOPMENT.md for setup instructions.

Issues: https://github.com/stbenjam/skillsaw/issues
Discussions: https://github.com/stbenjam/skillsaw/discussions