claude-commands-check
A small Python linter for Claude Code slash-command files (.claude/commands/*.md).
It checks:
- filename is a valid command name (lowercase kebab-case)
- YAML frontmatter parses cleanly (when present — frontmatter is optional)
descriptionis present, reasonably long, and a stringallowed-tools/disallowed-toolsare a string or list of stringsargument-hintis a stringmodelis a recognized value (opus,sonnet,haiku,inherit,default, or a full model id)disable-model-invocationis a boolean- command body is not empty (otherwise there's no prompt for Claude to run)
- no hardcoded API keys slipped into the body or frontmatter
Install
pip install claude-commands-check
Usage
Lint a single file:
claude-commands-check .claude/commands/my-cmd.md
Lint an entire commands directory:
claude-commands-check .claude/commands/
claude-commands-check ~/.claude/commands/
Exit status: 0 on no errors, 1 on any errors, 2 when no command files were found.
Library API
from claude_commands_check import validate_command_file
result = validate_command_file(".claude/commands/my-cmd.md")
for issue in result.errors:
print(issue.code, issue.message)
Issue codes
| Code | Severity | Meaning |
|---|---|---|
| E000 | error | file-level problem (missing, empty, not UTF-8) |
| E001 | error | filename is not a valid command name |
| E010 | error | frontmatter is not valid YAML |
| E012 | error | frontmatter is not a mapping |
| E100 | error | description is not a string |
| E102 | error | description is too long |
| E110 | error | allowed-tools / disallowed-tools is not a string or list |
| E111 | error | list item in tools field is not a string |
| E120 | error | argument-hint is not a string |
| E130 | error | model is not a string |
| E140 | error | disable-model-invocation is not a boolean |
| E200 | error | command body is empty |
| E300 | error | possible secret detected |
| W001 | warning | file does not end in .md |
| W011 | warning | frontmatter block is empty |
| W100 | warning | missing description |
| W101 | warning | description is too short |
| W131 | warning | unusual model value |
| W900 | warning | unknown frontmatter field |
License
MIT
1 maintainer
Metadata
1 maintainer
Release files for claude-commands-check 0.1.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 | Provenance | |
|---|---|---|---|---|
| claude_commands_check-0.1.0.tar.gz | 7.1 kB | Without provenance | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| claude_commands_check-0.1.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 14.9 kB
Release files / claude_commands_check-0.1.0.tar.gz
| Download URL | claude_commands_check-0.1.0.tar.gz |
|---|---|
| Size | 7.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
2b7b67a73aaf9b1ff5ff9940a1607d6ed79eb585d97852ac0950a7c005d44dae
|
|
BLAKE2b-256 checksum How to use checksums |
4f769cd6c226e325d29c832523b8bb7f770ddc408f28e147cb5985f4f3549b7a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.14.3
|
Release files / claude_commands_check-0.1.0-py3-none-any.whl
| Download URL | claude_commands_check-0.1.0-py3-none-any.whl |
|---|---|
| Size | 7.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
8a9cb7a375f1b47241abccb3ed689d28d3219a679a15f34dce6a3bf07b728d98
|
|
BLAKE2b-256 checksum How to use checksums |
be71a5d15d596115bca7d989fcc58b077c3c77af8ce163ab4ed7f2a9f6a32435
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.14.3
|
Security for claude-commands-check 0.1.0
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.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.
