skillsaw: Skill for Claude Code

skillsaw Create Plugin

Create a skillsaw rule plugin: a Python package that adds lint rules to skillsaw. Once you build and publish to PyPI, anyone can pip install it and skillsaw picks up the rules automatically — no config required. Prefer this to per-repo custom-rules: files when sharing rules across repos.

Keep the terminology straight: a skillsaw plugin adds rules to the skillsaw linter itself. Never confuse it with the Claude Code plugins that skillsaw lints.

Review this reference material while you work:

• Read the plugin guide: https://skillsaw.org/plugins/
• Follow the rule-writing guide (lint tree, block types): https://skillsaw.org/custom-rules/ and https://skillsaw.org/lint-tree/
• Read the complete working example: examples/plugins/skillsaw-example-plugin/ in the skillsaw repo

Follow each step in order, and keep the user updated on progress at each stage.

Step 1: Gather requirements

Review the following with the user:

1. What should each rule check? Get concrete examples of content that should pass and content that should fail.
2. Rule IDs — use kebab-case, descriptive (e.g. no-todo-instructions). Run skillsaw list-rules and confirm no ID collides with a builtin rule or another installed plugin; skillsaw never loads colliding plugin rules.
3. Severity — set each rule to error (must fix), warning (should fix), or info (advisory).
4. Package name — follow the convention skillsaw-<name> on PyPI with module skillsaw_<name> (e.g. skillsaw-acme-rules / skillsaw_acme_rules).
5. Tunable settings — set anything a user could reasonably want to adjust (patterns, thresholds, allowlists) in config_schema; never hardcode it.

Step 2: Create the package layout

Create this layout:

skillsaw-<name>/
├── pyproject.toml
├── README.md
├── src/
│   └── skillsaw_<name>/
│       ├── __init__.py
│       └── rules.py
└── tests/
    ├── fixture/
    │   └── CLAUDE.md          # realistic fixture the rules run against
    └── test_rules.py