commit-message-linter

Validate git commit messages against Conventional Commits spec and configurable rules. Use when linting commit messages, enforcing commit conventions, checki...

Security Scan

The skill is internally consistent: a pure-Python commit message linter that reads git history or commit message files and optionally creates a local config file; it does not request credentials, external network access, or elevated system privileges.

Purpose & Capability

Name/description match the code and instructions: the script lints commit messages, reads commits via 'git log' or .git/COMMIT_MSG, and can generate a .commitlintrc.json. No unrelated capabilities or credentials are requested.

Instruction Scope

SKILL.md and the script stay within scope: running the linter on commits/branches/messages, installing a commit-msg hook, and initializing a local config. The script reads repository files and config files it auto-discovers; it does not instruct reading unrelated system files or sending data externally.

Install Mechanism

No install spec (instruction-only) and the included script is pure Python with no external dependencies. This is low-risk and proportionate for the stated purpose.

Credentials

The skill requires no environment variables, no external credentials, and does not access network endpoints. It uses subprocess to call 'git', which is expected for a git-centric tool.

Persistence & Privilege

always is false and the skill is user-invocable. The only persistence behavior is creating a local .commitlintrc.json when the user runs the init command, which is appropriate for a linter.

Assessment

This skill appears to do exactly what it says: lint commit messages and optionally write a local config file. Before installing or adding it as a commit hook: (1) inspect the included scripts (already provided) to confirm they meet your policies; (2) run it in a test repository first to see what it writes (init will create .commitlintrc.json); (3) avoid running hooks on repositories that contain secrets you don't want processed by third-party tools; and (4) ensure python3 is the interpreter you expect. If you want extra assurance, run the script in a sandboxed repo to observe behavior. Confidence is high based on the provided SKILL.md and script (no network/credential use detected).

Validate commit messages against Conventional Commits and custom rules. Pure Python, no dependencies.

Quick Start

# Lint last commit
python3 scripts/lint_commits.py

# Lint last 5 commits
python3 scripts/lint_commits.py --range HEAD~5..HEAD

# Lint a branch
python3 scripts/lint_commits.py --range main..feature-branch

# Lint a single message
python3 scripts/lint_commits.py --message "feat: add login"

# Read from stdin (git commit-msg hook)
python3 scripts/lint_commits.py --stdin < .git/COMMIT_MSG

# Read from file
python3 scripts/lint_commits.py --file .git/COMMIT_MSG

Output Formats

python3 scripts/lint_commits.py --format text      # human-readable (default)
python3 scripts/lint_commits.py --format json       # CI/tooling
python3 scripts/lint_commits.py --format markdown   # reports

Configuration

Generate default config:

python3 scripts/lint_commits.py init

Creates .commitlintrc.json. Also auto-discovers .commitlintrc or commitlint.config.json.

Key config options:

• header_max_length (72) — max header chars
• require_conventional (true) — enforce <type>[scope]: <desc> format
• types — allowed types (feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert)
• scopes — allowed scopes (empty = any)
• require_scope (false) — mandate scope
• require_body (false) — mandate body
• header_case — description start case: lower/upper/sentence/any
• no_trailing_period (true) — reject trailing period on header
• forbidden_patterns — regex patterns that reject commits
• required_patterns — regex patterns that must match
• --strict flag treats warnings as errors

Rules Reference

Rule	Level	Description
header-empty	error	Empty header
header-max-length	error	Header exceeds max length
header-min-length	warning	Header below min length
conventional-format	error	Not Conventional Commits format
type-enum	error	Type not in allowed list
scope-required	error	Missing required scope
scope-enum	error	Scope not in allowed list
description-empty	error	Empty description
description-case	warning	Wrong description case
header-no-period	warning	Trailing period
header-leading-whitespace	error	Leading whitespace
header-trailing-whitespace	warning	Trailing whitespace
body-separator	error	No blank line before body
body-required	warning	Missing required body
body-line-length	warning	Body line too long
body-max-lines	warning	Too many body lines
breaking-change-description	warning	Breaking ! without BREAKING CHANGE: in body
forbidden-pattern	error	Matches forbidden regex
required-pattern	warning	Doesn't match required regex

Exit Codes

• 0 — all commits pass (warnings OK unless --strict)
• 1 — errors found (or warnings with --strict)
• 2 — git/system error

CI Integration (Git Hook)

As commit-msg hook (.git/hooks/commit-msg):

#!/bin/sh
python3 path/to/lint_commits.py --file "$1" --strict

Auto-ignored: merge commits, reverts, version tags, "Initial commit".