The universal quality standard for AI agent skills.
Evaluate any SKILL.md — from skills.sh, ClawHub, GitHub, or your local machine.

npm install -g skillscore

npm install skillscore
npx skillscore ./my-skill/

git clone https://github.com/joeynyc/skillscore.git
cd skillscore
npm install
npm run build
npm link

# Evaluate a skill
skillscore ./skills/my-skill/

# Evaluate with verbose output (shows all findings)
skillscore ./skills/my-skill/ --verbose

# Full GitHub URL (always recognized)
skillscore https://github.com/vercel-labs/skills/tree/main/skills/find-skills

# GitHub shorthand (requires -g/--github flag)
skillscore -g vercel-labs/skills/find-skills

# Anthropic skills
skillscore -g anthropic/skills/skill-creator

# JSON output
skillscore ./skills/my-skill/ --json

# Markdown report
skillscore ./skills/my-skill/ --markdown

# Save to file
skillscore ./skills/my-skill/ --output report.md
skillscore ./skills/my-skill/ --json --output score.json

# Compare multiple skills (auto-enters batch mode)
skillscore ./skill1 ./skill2 ./skill3

# Explicit batch mode flag
skillscore ./skill1 ./skill2 --batch

# Compare GitHub skills
skillscore -g user/repo1/skill1 user/repo2/skill2 --json

# Show version
skillscore --version

# Get help
skillscore --help

📊 SKILLSCORE EVALUATION REPORT
============================================================

📋 Skill: Weather Information Fetcher
   Fetches current weather data for any city using OpenWeatherMap API
   Path: ./weather-skill

🎯 OVERALL SCORE
   A- - 92.0% (9.2/10.0 points)

📝 CATEGORY BREAKDOWN
------------------------------------------------------------
Structure ████████████████████ 100.0%
   SKILL.md exists, clear name/description, follows conventions
   Score: 10/10 (weight: 15%)
   ✓ SKILL.md file exists (+3)
   ✓ Clear skill name: "Weather Information Fetcher" (+2)
   ✓ Clear description provided (+2)
   ... 2 more findings

Clarity ██████████████████░░ 90.0%
   Specific actionable instructions, no ambiguity, logical order
   Score: 9/10 (weight: 20%)
   ✓ Contains specific step-by-step instructions with commands (+3)
   ✓ No ambiguous language detected (+3)
   ✓ Instructions follow logical order (+2)
   ... 1 more finding (use --verbose to see all)

Safety ██████████████░░░░░░ 70.0%
   No destructive commands, respects permissions
   Score: 7/10 (weight: 20%)
   ✓ No dangerous destructive commands found (+3)
   ✓ No obvious secret exfiltration risks (+3)
   ✗ Some potential security concerns detected

📈 SUMMARY
------------------------------------------------------------
✅ Strengths: Structure, Clarity, Dependencies, Documentation
❌ Areas for improvement: Safety

Generated: 2/11/2026, 3:15:49 PM

📊 BATCH SKILL EVALUATION
Evaluating 3 skill(s)...

[1/3] Processing: ./weather-skill
✅ Completed

[2/3] Processing: ./file-backup
✅ Completed

[3/3] Processing: user/repo/skill
✅ Completed

📋 COMPARISON SUMMARY

Skill                          Grade  Score    Structure Clarity Safety Status    
Weather Information Fetcher    A-     92.0%    100%      90%     70%    OK        
File Backup Tool              B+     87.0%    95%       85%     90%    OK        
Advanced Data Processor       A      94.0%    100%      95%     85%    OK        

📈 BATCH SUMMARY
✅ Successful: 3
📊 Average Score: 91.0%

my-skill/
├── SKILL.md           # Main skill definition (REQUIRED)
├── README.md          # Documentation (recommended)
├── package.json       # Dependencies (if applicable)
├── scripts/           # Executable scripts
│   ├── setup.sh
│   └── main.py
└── examples/          # Usage examples
    └── example.md

# My Awesome Skill

Brief description of what this skill does and when to use it.

## When to Use

Use this skill when you need to [specific task] with [specific tools/inputs].

## When NOT to Use

Don't use this skill when:
- The task is [alternative scenario] — use [other skill] instead
- You need [different capability]

## Dependencies

- Tool 1: Installation instructions
- API Key: How to obtain and configure
- Environment: OS requirements

## Usage

1. Step-by-step instructions
2. Specific commands to run
3. Expected outputs

## Output

Results are written to `./output/` as JSON files.

## Error Handling

- Common issues and solutions
- Fallback strategies
- Validation steps

## Examples

### Example Output

```json
{
  "status": "success",
  "result": "Example of what the skill produces"
}

# Working example
./scripts/main.py --input "test data"

## 🔧 API Usage

Use SkillScore programmatically in your Node.js projects:

```typescript
import { SkillParser, SkillScorer, TerminalReporter } from 'skillscore';
import type { Reporter, SkillScore } from 'skillscore';

const parser = new SkillParser();
const scorer = new SkillScorer();
const reporter: Reporter = new TerminalReporter();

async function evaluateSkill(skillPath: string): Promise<SkillScore> {
  const skill = await parser.parseSkill(skillPath);
  const score = await scorer.scoreSkill(skill);
  const report = reporter.generateReport(score);

  console.log(report);
  return score;
}

Usage: skillscore [options] <path...>

Arguments:
  path                   Path(s) to skill directory, GitHub URL, or shorthand

Options:
  -V, --version         Output the version number
  -j, --json            Output in JSON format
  -m, --markdown        Output in Markdown format
  -o, --output <file>   Write output to file
  -v, --verbose         Show ALL findings (not just truncated)
  -b, --batch           Batch mode for comparing multiple skills
  -g, --github          Treat shorthand paths as GitHub repos (user/repo/path)
  -h, --help           Display help for command

# Run all tests
npm test

# Run tests in watch mode
npm test

# Run tests once
npm run test:run

# Lint code
npm run lint

# Build project
npm run build

git clone https://github.com/joeynyc/skillscore.git
cd skillscore
npm install
npm run build
npm link

# Run in development mode
npm run dev ./test-skill/

# Build for production
npm run build