open-index/open-npm huggingface dataset:
npm package: @lavelle/lint-agent
Description: Lint .claude/skills/ for correct filenames and valid frontmatter
Author: Giles Lavelle
Latest version: 0.0.8

# @lavelle/lint-agent

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

## Install

```sh
npm install -g @lavelle/lint-agent
```

Or run directly:

```sh
npx @lavelle/lint-agent
```

## Usage

```sh
# 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](https://github.com/anthropics/claude-code/issues/25380)). 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:

```ts
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