Skip to content

reach lint

Validate skill manifests, frontmatter schemas, naming conventions, and runtime listing budget limits.

Synopsis

reach lint [SKILLS] [OPTIONS]

Key Scenarios

Automatically inspect the project using the configured precedence order:

reach lint

Validate all skills in a specific directory or a standalone skill manifest positionally:

reach lint ./skills
reach lint ./SKILL.md

Fail with exit code 1 if any warnings or errors are discovered:

reach lint ./skills --strict

Filter lint checks to a specific skill:

reach lint ./skills --skill database-migrate

Get detailed background and remediation instructions for a rule:

reach lint --explain listing-overflow

Generate GitHub annotations or JSON diagnostics:

reach lint ./skills --format github
reach lint ./skills --format json

Options

Option Type Default Description
[SKILLS], --skills Path Auto-discovered Path to a skill directory, SKILL.md file, or catalog tree (discovered from precedence if omitted).
--skill String - Filter lint diagnostics to specific skill name(s) (repeatable).
--strict Flag false Fail with exit code 1 if any warnings are detected.
--explain String - Display detailed explanation and remedy for a specific lint rule and exit.
--ignore String - Disable specific lint rule(s) (repeatable).
--error String - Treat specific lint rule(s) as an error (repeatable).
--warn String - Treat specific lint rule(s) as a warning (repeatable).
--agent Choice - Agent runtime to query for installed skill locations (claude-code, antigravity-cli, etc.).
--global, -g Flag false Discover and inspect skills from user global configuration (~/).
--format Choice text Output format: text, concise, github, json, jsonl, csv.
--config Path - Path to custom reach.toml configuration file.

Built-in Lint Rules

Rule ID Default Severity Description
invalid-yaml Error SKILL.md contains missing or unparseable YAML frontmatter.
missing-name Error Frontmatter does not declare a skill name.
missing-description Error Frontmatter has no description or the description is empty.
invalid-name-format Error Skill name does not adhere to lowercase kebab-case convention (max 64 chars).
name-mismatch Error Frontmatter name differs from the parent directory name.
duplicate-name Error Multiple skills in the corpus declare the same name.
duplicate-capability Warning Skill description has high semantic overlap (> 92%) with another resident skill.
description-too-short Warning Description is under 20 characters and lacks actionable routing criteria.
listing-overflow Warning Description exceeds warning threshold (1,024 characters) and risks prompt listing elision.
reserved-name-collision Warning Skill name collides with a built-in agent tool or command primitive.
unresolved-placeholder Warning Description contains unresolved template markers (TODO, FIXME, <FILL_IN>).
unresolved-declared-dependency Warning Declared dependency skill in metadata or allowed-tools is missing from resident catalog.
lockfile-drift Warning Local SKILL.md content digest does not match pinned computedHash in skills-lock.json.
unbounded-attractor Warning Description contains overly broad phrases that aggressively attract out-of-scope queries.
unknown-skill-reference Warning Negative routing handoff (use <other-skill>) references a skill missing from the catalog.
missing-mutual-handoff Warning High-similarity or one-way competing neighbor lacks reciprocal Don't use for... handoff.