nori-lint

An opinionated linter for SKILL.md files — follow best practices, don't configure slop.

npx nori-lint lint /path/to/SKILL.md

Opinionated how?

SKILL.md files are prompt-engineered instructions consumed by LLMs. Most LLMs will write verbose slop skills that do not work. Every wasted word burns context window space in every agent session, degrading agent ability and costing you money.

nori-lint enforces two principles:

• Token efficiency: Don't waste tokens on things the LLM already knows (redundant explanations, obvious instructions, markdown formatting it doesn't render).
• Structural discipline: Skills should be concise processes with required checklists, not sprawling reference manuals.

You can disable any rule you disagree with via configuration.

Ecosystem

nori-lint is part of a broader set of tools for building and managing AI agent configurations:

• Nori Skillsets — Registry and CLI for downloading, publishing, and switching between packaged sets of AI agent skills. Teams can get private registries, which also support automatic skill generation from coding session transcripts.
• Nori Sessions — Managed agent runtime platform for running AI coding agents in cloud environments with security, persistence, and integrations. Like Stripe or Ramp, but off the shelf and personalized to your org.
• Nori — Homepage.

If you are struggling to adopt AI or are feeling AI FOMO, get in touch!

Installation

Requires Node.js 20+.

npm install -g nori-lint

Usage

Running nori-lint with no arguments shows help. Use --version to print the version.

Lint

nori-lint lint [path] [options]

Finds all SKILL.md files recursively under [path] (defaults to .) and reports violations. You can also pass a path to a single file.

Option	Default	Description
--format <format>	text	Output format: text or json
--config <path>	—	Path to config file

Exit code 0 means no violations. Exit code 1 means violations were found.

Fix

nori-lint fix [path] [options]

Auto-fixes violations in place. Deterministic rules are fixed directly. LLM rule violations are batched into a single API call per file.

Note: When LLM rules are active, the fix command is non-deterministic — running it twice on the same file may produce different results. Static rule fixes are always deterministic.

Option	Default	Description
--config <path>	—	Path to config file
--dry-run	false	Show what would change without writing

List

nori-lint list [options]

Lists all available lint rules with their descriptions and fixability.

Option	Default	Description
--format <format>	text	Output format: text or json

Rules

nori-lint has a two-tier rule system.

Static rules

These run without any API key. They are fast, deterministic, and pattern-based.

Rule	Fixable	Description
bold_italics	Yes	Bold/italic markdown formatting wastes tokens for an LLM reader.
consecutive_blank_lines	Yes	Multiple consecutive blank lines waste tokens.
description_action	No	Description must indicate when to use the skill, not what it does.
frontmatter	No	Valid YAML frontmatter with required fields per the agentskills.io spec.
frontmatter_name_format	No	Name must be lowercase alphanumeric with hyphens.
line_count	No	Files must not exceed 150 lines.
markdown_links	Yes	Use bare URLs instead of [text](url) markdown link syntax.
redundant_title	Yes	Title headings are redundant — the filename and frontmatter already identify the skill.
required_tags	No	Every skill must contain at least one <required> block.
trailing_whitespace	Yes	Trailing whitespace on lines wastes tokens.
unclosed_tags	No	All opened XML-style tags must have matching closing tags.
when_to_use	Yes	"When to Use" sections are redundant — this belongs in the description frontmatter field.

LLM rules

These call the Anthropic API for semantic analysis. They only run when a config file with a valid anthropic_api_key is present.

Rule	Description
cli_command_index	Flags CLI command reference lists — an LLM already knows these from training data.
duplicate_section	Flags sections that cover substantially the same ground.
first_person	The skill author should refer to themselves as "I/me/my", not "the user".
negative_without_positive	"Don't do X" instructions must pair with a concrete "do Y instead".
obvious_instructions	Flags generic instructions any LLM already follows ("write clean code", "handle errors").
process_not_integration	Skills should be step-by-step workflows, not reference manuals.
redundant_explanation	Flags explanations of concepts an LLM already knows.
skill_example_xml_tags	Behavioral examples must use <good_example>/<bad_example> tags.
linkable_content	Checks that skill files link to external documentation instead of restating it inline. Uses web search to find canonical URLs.
unexplained_url	URLs must have surrounding context explaining what they link to and why.

Configuration

Create a .nori-lint.json file in your project root, or pass --config <path>.

{
  "anthropic_api_key": "sk-ant-your-api-key-here",
  "rules": {
    "disabled": ["obvious_instructions", "redundant_explanation"]
  }
}

• anthropic_api_key — Required for LLM rules. Without it, only static rules run.
• rules.enabled — Allowlist: only these rules run.
• rules.disabled — Denylist: all rules except these run.
• enabled and disabled are mutually exclusive.

The .nori-lint.json file is gitignored by default to avoid committing API keys. See .nori-lint.example.json for a template.