skill-tools CLI

CLI tool and library for validating, linting, and quality-scoring Agent Skills per the Agent Skills specification. The ESLint/Lighthouse equivalent for agent skills.

npm install -g skill-tools

Commands

`skill-tools validate <path>`

Checks SKILL.md files against the specification. Reports errors and warnings.

skill-tools validate ./my-skill/
skill-tools validate ./skills/ --format json

`skill-tools lint <path>`

Runs quality lint rules beyond basic spec compliance.

skill-tools lint ./my-skill/
skill-tools lint ./my-skill/ --fail-on warning

`skill-tools score <path>`

Computes a quality score (0-100) with dimension breakdowns and improvement suggestions.

skill-tools score ./my-skill/
skill-tools score ./my-skill/ --min-score 60

`skill-tools check <path>`

Runs validate + lint + score in one pass. Ideal for CI/CD.

Lint Rules

Rule	Default	Description
`description-specificity`	warn	No generic verbs ("manage", "handle")
`description-trigger-keywords`	warn	Has action verbs or "Use when..."
`progressive-disclosure`	warn	Large files use `references/`
`no-hardcoded-paths`	error	No `/Users/...` or `C:\` paths
`no-secrets`	error	No API keys, tokens, private keys
`instructions-has-examples`	info	Has code blocks or numbered steps
`instructions-has-error-handling`	info	Mentions error handling
`consistent-headings`	info	No skipping heading levels

Score Dimensions

Dimension	Points	Key Factors
Description Quality	30	Length, specificity, trigger context, uniqueness
Instruction Clarity	25	Code blocks, steps, error handling, substance
Spec Compliance	20	Name, description, tokens, lines
Progressive Disclosure	15	File size, use of references/scripts
Security	10	No secrets, no hardcoded paths

Library API

import { validate, lint, score } from 'skill-tools';

const results = await validate('./my-skill/');
const lintResult = lint(parsedSkill);
const qualityScore = score(parsedSkill);

GitHub Action

Use the skill-tools GitHub Action to validate skills in CI:

- uses: skill-tools/skill-tools/action@main
  with:
    path: ./skills/
    min-score: 60