skillint-py

A linter for Claude Code skill files (SKILL.md). Catches malformed YAML frontmatter, missing required fields, thin descriptions, hardcoded secrets, and missing body headings before they ship.

Stdlib-only Python port of @mukundakatta/skillint. No PyYAML required -- the linter only needs to recognize the simple key: value mapping that frontmatter actually uses.

Note: there's a separate claude-skill-check package on PyPI by a different author. This package is the user's own port and uses the -py suffix to disambiguate.

Install

pip install skillint-py

Usage

from skillint import lint

result = lint("path/to/SKILL.md")

result.fatal           # True if frontmatter could not be parsed at all
for issue in result.issues:
    print(issue.line, issue.severity, issue.rule_id, issue.message)

You can also lint an in-memory source string:

from skillint import lint_source

source = """---
name: git-commit
description: Use when the user asks Claude to commit changes; handles co-author trailers.
---

## Triggers
"""
result = lint_source(source, file="<inline>")

Result shape

@dataclass
class Issue:
    rule_id: str
    severity: str           # "error" | "warning" | "info"
    message: str
    suggestion: str = ""
    line: int = 1

@dataclass
class LintResult:
    file: str
    fatal: bool
    issues: list[Issue]

Rules

API differences from the JS sibling

• Stdlib-only YAML parser handles the flat key: value mapping that frontmatter actually uses. Block scalars and tagged values are not supported -- if your frontmatter needs them, the linter falls back to a yaml-parse-error so you'll see it loud and clear.
• No --config plugin loading -- this Python port runs the built-in rules.
• Spec entrypoint is lint(skill_md_path) -> LintResult. lint_source covers the in-memory case.

See the JS sibling's README for the broader rationale.