skill-tools

0.4.1 verified Fri May 01 auth: no javascript

Validate, lint, and score Agent Skills (SKILL.md) files with 20 spec checks, 10 lint rules, and a 0-100 quality score across 5 dimensions. Current stable version is 0.4.1, released as minor/patch updates with active development. Differentiators include BM25 routing, watch mode, SARIF support, and audit contracts (BAP, DBAR, UseID). Ships TypeScript types, requires Node >=18, and is ESM-only (no CJS support).

Common errors

error Error [ERR_REQUIRE_ESM]: require() of ES Module /path/to/@skill-tools/contracts/index.js not supported. ↓

cause Trying to require() an ESM-only package.

fix

Change require() to import(), or set type: 'module' in package.json.

error error: unknown command 'validate'. Did you mean 'check'? ↓

cause The 'validate' command was removed or renamed in v0.4.0.

fix

Use 'skill-tools check <path>' instead of 'skill-tools validate <path>'.

error Error: Cannot find module '@skill-tools/contracts' ↓

cause The package is not installed. It is a separate package from 'skill-tools'.

fix

Run 'npm install @skill-tools/contracts' (available since v0.1.1).

error Error: You are running Node.js <18. Please upgrade to Node.js >=18. ↓

cause Package requires Node.js version 18 or higher.

fix

Upgrade Node.js to at least version 18.

Warnings

breaking Node.js <18 is not supported. The package relies on modern JavaScript features. ↓

fix Upgrade Node.js to version 18 or higher.

deprecated Pre-0.4.0 'validate', 'lint', 'score' commands are deprecated. Use 'check' which combines all three. ↓

fix Replace 'skill-tools validate; skill-tools lint; skill-tools score' with 'skill-tools check'.

gotcha The package is ESM-only. Attempting to require() the contracts or gen subpackages will fail. ↓

fix Use import statements or dynamic import(). For CDD, set type: 'module' in package.json.

gotcha When using --fail-on warning, exit code 1 is returned if any warning occurs. This may break CI pipelines that expect exit code 0. ↓

fix Use '--fail-on error' (default) for strict CI, or omit the flag.

gotcha The contracts package @skill-tools/contracts was added in v0.4.0 and is still 0.x, so API may change without major semver bump. ↓

fix Pin exact version in package.json, e.g., '@skill-tools/contracts': '0.1.1'.

Install

npm install skill-tools

yarn add skill-tools

pnpm add skill-tools

Imports

skill-tools (CLI)
```
npx skill-tools check ./my-skill/
```
skill-tools is primarily a CLI tool; direct programmatic API is not publicly documented yet.

@skill-tools/contracts

wrong

const { validate } = require('@skill-tools/contracts')

correct

import { validate } from '@skill-tools/contracts'

ESM-only; CJS require() will fail. Available since 0.1.1.

@skill-tools/gen
```
import { generate } from '@skill-tools/gen'
```
Gen package for generating SKILL.md from MCP servers. ESM-only.

Quickstart

Demonstrates CLI usage via npx and programmatic API using the contracts package.

// Validate and score a skill using the CLI
const { execSync } = require('child_process');
const result = execSync('npx skill-tools@0.4.1 check ./path/to/skill/', { encoding: 'utf-8' });
console.log(result);

// For programmatic use with contracts package:
const { validate } = await import('@skill-tools/contracts');
const skill = { name: 'test', description: 'Does something', body: '## Usage\n' };
const report = validate(skill);
console.log(report);