TESLint

The ESLint for AI process definitions.

CLI that analyzes your Claude Code configuration — CLAUDE.md, skills, commands, agents, hooks, rules — and tells you what's broken, redundant, contradictory, or missing.

Zero LLM calls. Purely deterministic. Fast. Free.

Install

pip install pyyaml
cd TESLint
python -m teslint /path/to/your/project

Usage

# Lint current directory
python -m teslint .

# Lint specific project
python -m teslint /path/to/project

# Run specific rules only
python -m teslint . --rule S001 --rule R001

# JSON output (for CI/programmatic use)
python -m teslint . --format json

Example Output

  CLAUDE.md
    15:1  error  R001  Referenced file does not exist: src/schema.ts
    22:1  warn   C001  Contradicts .claude/rules/style.md: "use semicolons" vs "never use semicolons"
     1:1  warn   T001  Estimated 2,213 tokens (limit: 2000)

  .claude/skills/deploy/SKILL.md
     1:1  error  S001  Missing required frontmatter field: 'name'
     1:1  warn   B003  Has procedure steps but no success criteria section

  .claude/settings.json
     1:1  error  R005  Hook script does not exist: .claude/hooks/notify.sh

  Token Budget:
    CLAUDE.md .......................... 2,213 tokens (100%)
    TOTAL .............................. 2,213 tokens

  Coverage: covered: testing, style, git — MISSING: security, error-handling, architecture
  6 problems (3 errors, 3 warnings)

What Gets Linted

Target	Path	Checks
CLAUDE.md	**/CLAUDE.md	Structure, contradictions, token cost, completeness, dead refs
Rules	.claude/rules/*.md	Glob validity, overlap, contradictions with CLAUDE.md
Skills	skills/*/SKILL.md	YAML frontmatter, structure, tool declarations, size
Commands	.claude/commands/*.md	YAML frontmatter, argument usage, skill references
Agents	.claude/agents/*.md	Structure, tool scope, injection protection
Hooks	.claude/settings.json	Event validity, command existence, filter presence
Plugin	.claude-plugin/*.json	Schema, path validity

Rules (35 total)

Structure (S)

Rule	Severity	What it checks
S001	error	SKILL.md missing required YAML frontmatter (name, description)
S002	warn	Command .md missing YAML frontmatter
S003	warn	CLAUDE.md has no section structure (no headings)
S004	warn	SKILL.md exceeds 500 lines (progressive disclosure)
S005	info	Agent has no tool scope declaration
S006	error	settings.json is invalid JSON
S007	warn	Unknown fields in YAML frontmatter
S008	warn	Skill directory missing SKILL.md entry point

References (R)

Rule	Severity	What it checks
R001	error	CLAUDE.md references file that doesn't exist
R002	error	Command references skill that doesn't exist
R003	warn	Unknown tool name (not in Claude Code's tool set)
R004	warn	Rule glob pattern matches zero files
R005	error	Hook script/command doesn't exist
R006	info	Possibly outdated model name
R007	warn	Skill allowed-tools lists unrecognized tool
R008	error	Plugin manifest source path doesn't exist

Consistency (C)

Rule	Severity	What it checks
C001	warn	Contradictory directives across CLAUDE.md and rules
C002	warn	Same instruction duplicated across files
C003	warn	Skill YAML name doesn't match directory name

Tokens (T)

Rule	Severity	What it checks
T001	warn	CLAUDE.md exceeds token threshold (default: 2000)
T002	info	Total always-loaded config exceeds threshold (default: 6000)
T003	warn	>30% content duplicated elsewhere (wasted tokens)

Completeness (X)

Rule	Severity	What it checks
X001	info	No testing instructions found
X002	info	No security guidelines found
X003	info	No code style/formatting instructions found
X004	info	No error handling guidance found
X005	info	No git/commit conventions found
X006	info	No architecture/structure guidance found

Best Practices (B)

Rule	Severity	What it checks
B001	warn	Excessive ALL CAPS emphasis (>5 instances)
B002	info	Skill has no allowed-tools restriction
B003	warn	Skill has procedure steps but no success criteria
B004	info	Command has no description in YAML
B005	warn	Hook runs on every tool call without filter
B006	info	No CLAUDE.md or .claude/ directory found
B007	warn	Skill references many URLs with no fallback

Security (P)

Rule	Severity	What it checks
P001	error	Possible secret/API key in config file
P002	warn	Skill uses Bash without safety guidance
P003	warn	Uses --dangerously-skip-permissions
P004	info	Agent has no prompt injection protection mentioned

Configuration

Create .teslintrc.json in your project root:

{
  "disabled_rules": ["S002", "B002"],
  "severity_overrides": {
    "X001": "error"
  },
  "claude_md_token_limit": 3000,
  "total_token_limit": 8000,
  "skill_line_limit": 500,
  "caps_threshold": 5
}

Exit Codes

• 0 — no errors (warnings and info are OK)
• 1 — at least one error found

How It Works

1. Scanner discovers all Claude Code config files in your project
2. Parser extracts YAML frontmatter, markdown sections, and references
3. Rules run against the parsed project — each rule yields issues
4. Reporter formats output (text or JSON)

No LLM calls. No API keys. No network. Pure static analysis.

License

MIT