Skills Lint — Code Quality skill for Claude Code

skills-lint

A linter for agent skills, focused on one question: will this skill ever be picked?

Skills fail without saying anything. You write one, drop it in a directory, and either the model selects it at the right moment or it never does. Nothing logs, nothing warns, there is no error to search for. Weeks later you notice the agent has been doing that task by hand the whole time.

The usual cause is the description field. The runtime matches a user request against it, so a description that only lists what the skill contains gives the matcher nothing to work with. This tool reads a skill the way the runtime does and points at the missing signal.

Standard library only. Python 3.8+. Works on any directory of `SKILL.md` files, including Claude Code, Codex, and anything else following the same convention.

python skills_lint.py ~/.claude/skills

skills-lint 1.0.0
==================================================================
pdf-tools                 99  [####################]
   [INFO] SL017 8 file(s) under scripts/ are never mentioned in SKILL.md
music-search              88  [##################..]
   [FAIL] SL010 description never says when to use the skill
          Add an explicit trigger clause, for example 'Use when the
          user asks to ...'. This is the single highest-impact fix
          for a skill that never fires.
news-digest              100  [####################]
   [ OK ] no findings
------------------------------------------------------------------
8 skill(s), average score 94, 3 failure(s), 2 warning(s)

most impactful fixes first:
  music-search         SL010: description never says when to use the skill

That run was against eight working skills. Three of them never declare when they apply, which means the descriptions were written with care and still had no trigger clause.

The case being caught

Same skill, two descriptions:

# Never selected. This is a catalogue entry.
description: PDF manipulation t