shelf lint

shelf lint [<name>...]

Also takes the global options --json and --actor (CLI overview).

What it does

Lints the named skills, or every skill in the library. For each it prints the estimated tokens (characters / 4) of the description, which loads in every session, and of the body, which loads on use, then any issues.

Errors make a skill invalid for some harnesses; warnings make it costly or hard for an agent to pick. Only errors change the exit code.

lint goes by the library's directories, so it also checks skills that don't load. A library directory without frontmatter, without a description, with a description over 1024 characters, or whose name doesn't match its directory isn't loaded by other commands (shelf doctor reports it under library); lint reports why, as errors. The dashboard's lint strip runs the same checks on the unsaved draft as you type.

Examples

$ shelf lint
api-design  ~31 description + ~18 body tokens  ok
git-hygiene  ~17 description + ~18 body tokens
  warning: description doesn't say when to use the skill: add "Use when …"
pdf-tools  ~32 description + ~17 body tokens  ok

$ shelf lint
Bad_Name  ~7 description + ~1 body tokens
  error: directory "Bad_Name" is not a valid skill name: rename it (and name:) to lowercase letters, digits and single hyphens
  error: name must be lowercase letters, digits and single hyphens, e.g. pdf-tools
ok-skill  ~7 description + ~0 body tokens
  warning: The body is empty: add the instructions an agent follows
$ echo $?
1

JSON output

{"schemaVersion":1,"ok":true,"data":{"skills":[{"skill":"git-hygiene","issues":[{"level":"warning","message":"description doesn't say when to use the skill: add \"Use when …\""}],"descriptionTokens":17,"bodyTokens":18}],"errors":0}}

When errors is above 0, the envelope still says "ok": true (the command ran) and the exit code is 1.

Errors

Related

• Writing skills
• shelf doctor, shelf audit