@lousy-agents/lint

@lousy-agents/lint

Programmatic lint API for AI agent skill, agent, hook, and instruction files. Use this package to integrate lousy-agents lint checks into your own tools, web apps, or CI pipelines without the CLI.

For CLI-based linting, see the lint command docs.

Installation

npm install @lousy-agents/lint

Quick Start

import { runLint } from '@lousy-agents/lint';

const result = await runLint({ directory: '/path/to/project' });

if (result.hasErrors) {
  console.error('Lint failed');
  for (const output of result.outputs) {
    for (const diagnostic of output.diagnostics) {
      console.error(`${diagnostic.filePath}:${diagnostic.line} [${diagnostic.severity}] ${diagnostic.message}`);
    }
  }
}

API

runLint(options): Promise<LintResult>

Runs all lint checks on a project directory and returns structured results.

import { runLint, LintValidationError } from '@lousy-agents/lint';

try {
  const result = await runLint({
    directory: '/path/to/project',
    targets: {
      skills: true,
      agents: true,
      hooks: false,       // skip hook linting
      instructions: false, // skip instruction linting
    },
  });

  console.log('Has errors:', result.hasErrors);
  console.log('Outputs:', result.outputs.length);
} catch (error) {
  if (error instanceof LintValidationError) {
    console.error('Invalid input:', error.message);
  } else {
    throw error;
  }
}

Options:

Property	Type	Required	Description
directory	string		Absolute or relative path to the project directory to lint
targets.skills	boolean	—	Lint skill files (.github/skills/)
targets.agents	boolean	—	Lint agent files (.github/agents/)
targets.hooks	boolean	—	Lint hook configuration: .github/hooks/agent-shell/hooks.json (Copilot), .claude/settings.json and .claude/settings.local.json (Claude)
targets.instructions	boolean	—	Lint instruction files (.github/instructions/, .github/copilot-instructions.md)
logger	LintLogger	—	Custom logger for gateway diagnostics (must have a .warn method); defaults to consola

When targets is omitted or all flags are false, all targets are linted.

Throws LintValidationError when directory is empty, contains control characters, path traversal sequences, does not exist, or is not a directory.

---

createFormatter(format): LintFormatter

Creates an output formatter for rendering LintOutput[] to a string.

import { runLint, createFormatter } from '@lousy-agents/lint';

const result = await runLint({ directory: '/path/to/project' });
const formatter = createFormatter('human');
console.log(formatter.format(result.outputs));

Format	Description
'human'	Human-readable text, one diagnostic per line
'json'	JSON array of all diagnostics
'rdjsonl'	Reviewdog Diagnostic Format JSONL (one JSON object per line) — for CI integrations

---

DEFAULT_LINT_RULES

The default rule configuration used when no lousy-agents.config.ts is present. Use this to inspect or extend the default rule set.

import { DEFAULT_LINT_RULES } from '@lousy-agents/lint';

console.log(DEFAULT_LINT_RULES.skills);
// { 'skill/missing-name': 'error', 'skill/missing-description': 'error', ... }

---

LintValidationError

Thrown when user-supplied input fails validation. Catch this to distinguish user-input errors from system errors.

import { runLint, LintValidationError } from '@lousy-agents/lint';

try {
  await runLint({ directory: '' });
} catch (error) {
  if (error instanceof LintValidationError) {
    // directory was empty, missing, or not a directory
    console.error(error.message);
  }
}

---

Types

import type {
  LintResult,
  LintOutput,
  LintDiagnostic,
  LintSeverity,
  LintTarget,
  LintOptions,
  LintLogger,
  LintRulesConfig,
  LintFormatType,
  LintFormatter,
  InstructionQualityResult,
} from '@lousy-agents/lint';

Key types:

Type	Description
LintResult	Top-level result: outputs array + hasErrors boolean
LintOutput	Per-target result: diagnostics, filesAnalyzed, summary, optional qualityResult
LintDiagnostic	Single diagnostic: filePath, line, severity, message, ruleId, target
LintSeverity	"error" | "warning" | "info"
LintTarget	"skill" | "agent" | "instruction" | "hook"
InstructionQualityResult	Instruction quality scores and suggestions (populated when instructions target runs)

---

Custom Logger

Pass any object with a .warn method to suppress or redirect gateway diagnostics:

import { runLint } from '@lousy-agents/lint';
import { createLogger } from 'your-logger';

const logger = createLogger('lint');
await runLint({
  directory: '/path/to/project',
  logger: { warn: (msg, ...args) => logger.warn(msg, ...args) },
});

---

CI Integration (rdjsonl)

Output in Reviewdog Diagnostic Format for annotation-based CI feedback:

node -e "
const { runLint, createFormatter } = require('@lousy-agents/lint');
runLint({ directory: '.' }).then(r => {
  process.stdout.write(createFormatter('rdjsonl').format(r.outputs));
  process.exit(r.hasErrors ? 1 : 0);
});
"

---

Related docs

• lint CLI command — CLI-based linting with npx @lousy-agents/cli lint
• GitHub Action — run linting in GitHub Actions without installing Node.js