🔍 Skill Validator

A powerful CLI tool for validating OpenClaw skill.md files. Automatically checks for security issues, missing documentation, and best practices.

$ skill-validator validate examples/good-skill.md

📋 Skill Validator Report
════════════════════════════════════════════════════

File: examples/good-skill.md
Status: ✓ PASSED

Summary:
  Total Issues:     0
  🔴 Critical:      0
  🟡 Warnings:      0
  🔵 Info:          0

✨ No issues found! Your skill is well documented.

════════════════════════════════════════════════════

Features

✅ Security Checks

• Detects hardcoded passwords, API keys, tokens, and secrets
• Flags dangerous functions (eval, exec)
• Warns about unencrypted HTTP URLs
• Identifies credential exposure patterns

✅ Documentation Validation

• Ensures required sections (Overview, Parameters, Returns, Examples, Error Handling)
• Checks for code examples
• Validates completeness

✅ Best Practices

• Error handling documentation
• Permission/authentication requirements
• Input validation guidance
• Usage warnings and notes
• Properly specified code blocks

✅ Multiple Output Formats

• Colorized terminal reports
• JSON for automation
• File export support

Installation

npm install -g skill-validator

Or use directly:

npx skill-validator@latest validate skill.md

Usage

Validate a Single File

skill-validator validate path/to/skill.md

Options:

• -j, --json - Output as JSON instead of formatted report
• -o, --output <file> - Write report to file

Examples:

# Terminal report
skill-validator validate my-skill.md

# JSON output
skill-validator validate my-skill.md --json

# Save to file
skill-validator validate my-skill.md --output report.txt

Scan a Directory

skill-validator scan path/to/skills/

Recursively scans all skill.md files in a directory.

Options:

• -j, --json - Output as JSON summary
• -o, --output <file> - Write report to file

Examples:

# Scan all skills
skill-validator scan ./skills/

# JSON summary
skill-validator scan ./skills/ --json

# Export scan results
skill-validator scan ./skills/ --output scan-report.json --json

Output Examples

Terminal Report

📋 Skill Validator Report
════════════════════════════════════════════════════

File: my-skill.md
Status: ✗ FAILED

Summary:
  Total Issues:     3
  🔴 Critical:      1
  🟡 Warnings:      2
  🔵 Info:          0

Issues:
════════════════════════════════════════════════════

🔒 Security Issues:
  1. 🔴 CRITICAL Potential hardcoded password detected
     Context: "password = "secret123""

📚 Documentation Issues:
  1. 🟡 WARNING Missing or unclear "Error Handling" section
  2. 🟡 WARNING Missing or unclear "Parameters" section

════════════════════════════════════════════════════

JSON Output

{
  "filepath": "my-skill.md",
  "passed": false,
  "issueCount": 3,
  "criticalCount": 1,
  "warningCount": 2,
  "infoCount": 0,
  "issues": [
    {
      "type": "security",
      "severity": "critical",
      "message": "Potential hardcoded password detected",
      "context": "password = \"secret123\""
    },
    {
      "type": "documentation",
      "severity": "warning",
      "message": "Missing or unclear \"Error Handling\" section"
    },
    {
      "type": "documentation",
      "severity": "warning",
      "message": "Missing or unclear \"Parameters\" section"
    }
  ]
}

Rules & Validation Checks

🔒 Security Rules

| Issue | Severity | Description | |-------|----------|-------------| | Hardcoded Password | 🔴 Critical | password = "..." patterns | | Hardcoded API Key | 🔴 Critical | api_key = "...", apiKey = "..." | | Hardcoded Secret | 🔴 Critical | secret = "..." patterns | | Hardcoded Token | 🔴 Critical | Bearer tokens, auth tokens | | eval() Usage | 🔴 Critical | Dynamic code execution | | exec() Without Validation | 🟡 Warning | Shell command execution | | HTTP URLs | 🟡 Warning | Unencrypted connections |

📚 Documentation Rules

| Issue | Severity | |-------|----------| | Missing Overview section | 🟡 Warning | | Missing Parameters section | 🟡 Warning | | Missing Returns/Output section | 🟡 Warning | | Missing Examples | 🟡 Warning | | Missing Error Handling section | 🟡 Warning | | No code examples (...) | 🟡 Warning | | Very short documentation (<10 lines) | 🔵 Info | | No YAML front matter | 🔵 Info |

💡 Best Practices Rules

| Issue | Severity | |--------|----------| | No error handling documentation | 🟡 Warning | | No permission/auth documentation | 🟡 Warning | | Code blocks without language | 🔵 Info | | No usage warnings/notes | 🔵 Info | | No input validation documentation | 🔵 Info | | No external documentation links | 🔵 Info |

Example Skills

The examples/ directory contains:

• good-skill.md - A well-documented, secure skill (passes validation)
• bad-skill.md - A poorly documented skill with security issues (fails validation)

Try them:

skill-validator validate examples/good-skill.md
skill-validator validate examples/bad-skill.md

Exit Codes

• 0 - Validation passed (no critical issues)
• 1 - Validation failed (critical issues found) or error occurred

Useful for CI/CD pipelines:

skill-validator validate my-skill.md && echo "✅ Ready for production" || echo "❌ Fix issues first"

Integration with CI/CD

GitHub Actions

name: Validate Skills
on: [push, pull_request]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-node@v2
        with:
          node-version: '18'
      - run: npm install -g skill-validator
      - run: skill-validator scan ./skills/ --json --output report.json
      - uses: actions/upload-artifact@v2
        if: always()
        with:
          name: validation-report
          path: report.json

Pre-commit Hook

#!/bin/bash
# .git/hooks/pre-commit

skill-validator scan . || exit 1

API Usage

Use skill-validator programmatically:

const { SkillValidator } = require('skill-validator');
const fs = require('fs');

const validator = new SkillValidator();
const skillContent = fs.readFileSync('my-skill.md', 'utf-8');

const report = validator.validate(skillContent, 'my-skill.md');

console.log(`Issues found: ${report.issueCount}`);
console.log(`Critical: ${report.criticalCount}`);
console.log(`Passed: ${report.passed}`);

// Get detailed issues
report.issues.forEach(issue => {
  console.log(`[${issue.type}] ${issue.message}`);
});

Development

Setup

git clone https://github.com/bagalobsta/skill-validator.git
cd skill-validator
npm install

Run Tests

npm test
npm run test:watch  # Watch mode

Test Coverage

npm test -- --coverage

Contributing

Contributions welcome! Please:

1. Fork the repository
2. Create a feature branch: git checkout -b feature/my-feature
3. Write tests for new features
4. Run npm test to ensure all tests pass
5. Submit a pull request

Project Structure

skill-validator/
├── bin/
│   └── skill-validator.js       # CLI entry point
├── lib/
│   ├── validator.js             # Core validation logic
│   └── formatter.js             # Output formatting
├── tests/
│   └── validator.test.js        # Test suite
├── examples/
│   ├── good-skill.md            # Example: valid skill
│   └── bad-skill.md             # Example: invalid skill
├── README.md                    # This file
├── package.json                 # Project metadata
└── LICENSE                      # MIT License

Roadmap

• [ ] Config file support (.skillvalidatorrc)
• [ ] Custom rule definitions
• [ ] Integration with skill templates
• [ ] VS Code extension
• [ ] Performance benchmarks
• [ ] Extended test coverage
• [ ] Support for YAML/JSON skill formats

License

MIT License © 2024 Bagalobsta

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software.

Support

• 📖 Documentation
• 🐛 Report Issues
• 💬 Discussions
• 🌐 Website

Author

Bagalobsta - GitHub | Email

Built with ❤️ for OpenClaw developers