skillint-py
MukundaKatta/skillint-py
Lint Claude Code SKILL.md files. Python port of @mukundakatta/skillint.
Instalação
npx convez-ai MukundaKatta/skillint-py1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
README
A tradução para o português deste README ainda está na fila.
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-checkpackage on PyPI by a different author. This package is the user's own port and uses the-pysuffix 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
| Rule id | Severity | Checks |
|---|---|---|
missing-frontmatter | error | File doesn't start with --- YAML fence. |
yaml-parse-error | error | Frontmatter fails to parse as a mapping. |
missing-required | error | name or description is missing. |
empty-required | error | name or description is empty / whitespace. |
kebab-case-name | error | name is not kebab-case (^[a-z][a-z0-9-]*[a-z0-9]$). |
overlong-name | warning | name exceeds 64 characters. |
short-description | warning / error | Description below 80 chars (or below 20 -> error). |
no-trigger-in-description | warning | Description lacks "when / use / trigger / handle / invoke" language. |
no-body-headings | warning | Body has no ## headings. |
hardcoded-secret | error | Provider-shaped key (OpenAI, Anthropic, GitHub, AWS, Slack, Stripe, Google AI). |
unknown-field | info | Frontmatter field outside the known set. |
API differences from the JS sibling
- Stdlib-only YAML parser handles the flat
key: valuemapping that frontmatter actually uses. Block scalars and tagged values are not supported -- if your frontmatter needs them, the linter falls back to ayaml-parse-errorso you'll see it loud and clear. - No
--configplugin loading -- this Python port runs the built-in rules. - Spec entrypoint is
lint(skill_md_path) -> LintResult.lint_sourcecovers the in-memory case.
See the JS sibling's README for the broader rationale.