@lavelle/lint-agent

A CLI linter for Claude Code configuration files. Validates .claude/skills/ directories for correct structure, filenames, and YAML frontmatter.

Install

npm install -g @lavelle/lint-agent

Or run directly:

npx @lavelle/lint-agent

Usage

# Lint the current directory
lint-agent

# Lint a specific directory
lint-agent /path/to/project

# List all checks
lint-agent --list-checks

Exits with code 1 if any errors are found, making it suitable for CI pipelines.

What it checks

Skill structure:

• Stray files in .claude/skills/ that should be in subdirectories
• Missing SKILL.md files
• Wrong filename casing (skill.md instead of SKILL.md)

Frontmatter validation:

• Missing or unparseable YAML frontmatter
• Missing required fields (name, description)
• Name format (lowercase, hyphens, max 64 chars, no whitespace)
• Field type validation for all optional fields (argument-hint, disable-model-invocation, user-invocable, allowed-tools, model, context, agent, hooks)
• Unknown fields that have no effect

Command migration:

• Warns about .claude/commands/ files that could be migrated to skills

Monorepo support:

• Recursively discovers .claude/skills/ in nested subdirectories
• Skips node_modules
• Reports errors with relative path prefixes

Run lint-agent --list-checks to see all checks with their severity levels.

Why this over alternatives?

VS Code's built-in validator validates SKILL.md frontmatter against the Agent Skills open standard schema, not Claude Code's extended schema. It incorrectly rejects valid fields like allowed-tools and user-invocable (open bug). It also can't run from CLI or CI.

cclint covers agents/commands/settings but not skills or rules. Low adoption (11 stars) and not actively maintained.

rulesync solves a different problem -- syncing rules across AI tools (Claude, Cursor, Gemini), not validating them.

lint-agent validates against the correct, current Claude Code schema with zod, runs anywhere Node runs, and is actively maintained.

Library usage

The core validation functions are exported for programmatic use:

import {
  lintSkills,
  lintCommands,
  findAllSkillRoots,
  validateFrontmatter,
} from '@lavelle/lint-agent';

const roots = await findAllSkillRoots('/path/to/project');
for (const root of roots) {
  const { errors, skillCount } = await lintSkills(root);
  const warnings = await lintCommands(root);
}

License

MIT