The quality toolkit for Agent Skills.
Validate, lint, score, route, watch, and generate SKILL.md files.

---

Agent Skills (SKILL.md) are a vendor-neutral format for packaging AI agent capabilities — like package.json for what an agent can do. skill-tools is the ESLint + Lighthouse for that format.

Why skill-tools?

• 20 spec checks catch structural issues before deployment
• 10 lint rules enforce quality (no secrets, no hardcoded paths, specific descriptions)
• 0-100 quality score across 5 dimensions gives objective, comparable skill quality
• BM25 routing matches user queries to the right skill at runtime
• Generate from OpenAPI/MCP and quality-gate before writing
• Watch mode, pre-commit hooks, GitHub Action, SARIF — fits into every workflow

Quick Start

npx skill-tools check ./my-skill/

  deploy-vercel  PASS
  ──────────────────────────────────────────────────
  ✓  File is readable
  ✓  Valid YAML frontmatter
  ✓  Has name field
  ✓  Name format is valid
  ✓  Has description field
  ✓  Has markdown body
  ✓  Within token budget
  ...
  20 checks  │  20 passed

  ✓  Description uses specific verbs
  ✓  No hardcoded paths
  ✓  No embedded secrets
  ✓  Instructions include examples
  ...
  10 rules  │  10 passed

  Quality Score  90/100  ★★★★★
  ──────────────────────────────────────────────────
  Description Quality       ████████░░  24/30
  Instruction Clarity       ████████░░  21/25
  Spec Compliance           ██████████  20/20
  Progressive Disclosure    ██████████  15/15
  Security                  ██████████  10/10

Packages

Package	Description	Install
skill-tools	CLI: validate, lint, score, check, route, watch, hook	npm i -g skill-tools
@skill-tools/gen	Generate SKILL.md from OpenAPI, MCP, or text	npm i -g @skill-tools/gen
@skill-tools/router	BM25 skill routing (zero deps)	npm i @skill-tools/router
@skill-tools/core	Parser, types, tokenizer	npm i @skill-tools/core

What's a SKILL.md?

---
name: deploy-vercel
description: >-
  Deploy web applications to Vercel. Use when the user wants to
  deploy, publish, or ship a Next.js or React app.
---

# Deploy to Vercel

## Steps

1. Run `vercel deploy` in the project root
2. Confirm the deployment URL

## Error Handling

- If deploy fails: check `vercel logs` for details

Ecosystem

• GitHub Action — Run skill-tools check in CI
• agentskills.io — The Agent Skills specification
• skills.menu — Documentation and playground

Development

pnpm install && pnpm build && pnpm test

Requires Node.js >= 18 and pnpm >= 9.

License

Apache-2.0