skill-tools

library0.4.1jsnpmunverified

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).

testing llm-agents devops

npm install skill-tools

github ↗package ↗

INSTALL

IMPORT

SIG · SKILL-TOOLS

skill-tools

testingjavascriptv0.4.1

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

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

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

✗ const { validate } = require('@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.

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);

skill-tools --version

Debug

Known issues

breakingNode.js <18 is not supported. The package relies on modern JavaScript features.

fix

Upgrade Node.js to version 18 or higher.

affects: >=0.0.0

deprecatedPre-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'.

affects: >=0.4.0

gotchaThe 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.

affects: >=0.4.0

gotchaWhen 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.

affects: >=0.3.0

gotchaThe 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'.

affects: >=0.4.0

Errors

Common errors & fixes

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

Trying to require() an ESM-only package.

fix

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

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

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

fix

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

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

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: You are running Node.js <18. Please upgrade to Node.js >=18.

Package requires Node.js version 18 or higher.

fix

Upgrade Node.js to at least version 18.

Upgrade

Version history

0.4.1latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

20 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/skill-tools/skill-tools ↗

packagehttps://www.npmjs.com/package/skill-tools ↗