Metadata-Version: 2.4
Name: claude-skill-check
Version: 0.1.0
Summary: Linter for Claude Code SKILL.md files. Validates YAML frontmatter, required fields, description length, and common secret patterns.
Project-URL: Homepage, https://github.com/MukundaKatta/claude-skill-check
Project-URL: Issues, https://github.com/MukundaKatta/claude-skill-check/issues
Project-URL: Source, https://github.com/MukundaKatta/claude-skill-check
Author-email: Mukunda Katta <mukundkst@gmail.com>
License: MIT
License-File: LICENSE
Keywords: anthropic,claude,claude-code,cli,linter,skill,validator
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.9
Requires-Dist: pyyaml>=6.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == 'dev'
Description-Content-Type: text/markdown

# claude-skill-check

[![CI](https://github.com/MukundaKatta/claude-skill-check/actions/workflows/ci.yml/badge.svg)](https://github.com/MukundaKatta/claude-skill-check/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/claude-skill-check.svg)](https://pypi.org/project/claude-skill-check/)
[![Python](https://img.shields.io/pypi/pyversions/claude-skill-check.svg)](https://pypi.org/project/claude-skill-check/)
[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)

A small Python linter for [Claude Code](https://claude.ai/code) `SKILL.md` files. It checks:

- YAML frontmatter is present and parses cleanly
- `name` and `description` are present
- `name` is lowercase kebab-case, 1-64 chars, starts with a letter
- `description` length is reasonable (20-1024 chars after trimming)
- `allowed-tools` is either a string or a list of strings
- Common secret patterns (Anthropic/OpenAI keys, AWS access keys, GitHub tokens, PEM blocks) are not leaked in the file
- Unknown frontmatter fields get a warning
- Empty body gets a warning

## Install

```bash
pip install claude-skill-check
```

## Usage

Lint a single file:

```bash
claude-skill-check path/to/SKILL.md
```

Lint every `SKILL.md` under a directory:

```bash
claude-skill-check path/to/skills-dir/
```

Exit status: `0` on no errors, `1` on any errors, `2` when no skill files were found.

### Only show errors

```bash
claude-skill-check --quiet path/to/skills-dir/
```

## Use as a library

```python
from claude_skill_check import validate_skill_file

result = validate_skill_file("path/to/SKILL.md")
if not result.ok:
    for issue in result.errors:
        print(issue.code, issue.message)
```

## Issue codes

| Code  | Severity | Meaning                                                           |
|-------|----------|-------------------------------------------------------------------|
| E000  | error    | file not found or not a regular file                              |
| E001  | error    | file is empty or not valid UTF-8                                  |
| E002  | error    | missing YAML frontmatter                                          |
| E003  | error    | frontmatter is not valid YAML                                     |
| E004  | error    | frontmatter is empty                                              |
| E005  | error    | frontmatter is not a mapping                                      |
| E100  | error    | missing required field (`name` or `description`)                  |
| E101  | error    | `name` is not a string                                            |
| E102  | error    | `name` is not a valid kebab-case identifier                       |
| E110  | error    | `description` is not a string                                     |
| E112  | error    | `description` exceeds 1024 chars                                  |
| E120  | error    | `allowed-tools` is not a string or list                           |
| E121  | error    | `allowed-tools` list contains a non-string item                   |
| E200  | error    | possible secret detected in the skill file                        |
| W111  | warning  | `description` is shorter than 20 chars                            |
| W300  | warning  | skill body is empty after frontmatter                             |
| W900  | warning  | unknown frontmatter field                                         |

## Development

```bash
pip install -e '.[dev]'
pytest
```

## License

MIT
