skill-compatibility-checker

name

skill-compatibility-checker

description

Pre-installation skill vetter that checks for conflicts, system requirement mismatches, missing dependencies, and security issues before you install a skill. Analyzes skill manifests, scans for name/CLI/port conflicts with existing skills, verifies OS/architecture/Node version compatibility, checks for missing CLI tools and API keys, and runs automated security scanning. Returns GO/CAUTION/BLOCKED with detailed remediation steps.

Skill Compatibility Checker

Vet skills before installation. Analyzes compatibility, conflicts, dependencies, and security risks.

Quick Start

# Check a local skill directory
skill-compatibility-checker ~/clawd/some-skill

# Get JSON output for programmatic use
skill-compatibility-checker ~/clawd/some-skill --output json

What It Checks

1. Conflict Detection

• Name conflicts - Is a skill with this name already installed?
• CLI command conflicts - Does it try to install a command that already exists?
• Port conflicts - Does it use ports that are already in use?
• Config conflicts - Does it modify the same config sections as existing skills?

2. System Requirements

Verifies your system meets the skill's requirements:

• OS compatibility - macOS, Linux, or Windows?
• Architecture - arm64 or x86_64?
• Node.js version - Does your Node meet the minimum requirement?

Parsed from:

• SKILL.md frontmatter and content
• package.json engines.node field

3. Dependencies

Checks for missing requirements:

• CLI tools - ffmpeg, python, java, docker, etc.

  • Lists which are missing
  • Provides install commands (brew install X)

• API keys - Groq, ElevenLabs, OpenAI, Stripe, Twilio, etc.

  • Checks TOOLS.md and environment variables
  • Lists which are not configured

• Clawdbot version - Does the skill need Clawdbot X.Y.Z or higher?

• npm packages - Dependency summary from package.json

4. Security Scan

Runs the security-scanner skill (if installed):

• Detects code execution vulnerabilities (eval, exec, dynamic require)
• Flags credential theft patterns
• Warns about network calls to unknown domains
• Identifies obfuscated or minified code
• Returns risk level: SAFE / CAUTION / DANGEROUS

Output: Installation Readiness

🟢 GO

Ready to install. No blocking issues detected.

• No system requirement mismatches
• No conflicts detected
• All dependencies available
• Security scan clear (SAFE)
• Missing optional dependencies (with install commands provided)

🟡 CAUTION

Proceed with caution. Review issues before installation.

• All system requirements met, but see warnings
• Conflicts detected but resolvable
• Some dependencies missing (CLI tools, API keys)
• Security scan shows CAUTION level
• Resolution steps provided for each issue

🔴 BLOCKED

Do not install.

• System requirements NOT met (wrong OS, architecture, or Node version)
• Skill name conflicts with existing installation
• Security scan detects DANGEROUS patterns
• Cannot be installed on this system

Usage Examples

Check a skill directory

$ skill-compatibility-checker ~/clawd/my-skill

╔════════════════════════════════════════════════════════════════════════════╗
║                    SKILL COMPATIBILITY CHECKER REPORT                      ║
╚════════════════════════════════════════════════════════════════════════════╝

Skill: my-skill
Path:  /Users/ericwoodard/clawd/my-skill
Date:  2026-01-29T15:30:00.000Z

┌─ INSTALLATION READINESS ─────────────────────────────────────────────────┐
│ ✅ GO - Safe to install
│
└────────────────────────────────────────────────────────────────────────────┘

┌─ SYSTEM REQUIREMENTS ────────────────────────────────────────────────────┐
│ Your System: darwin / arm64 / Node 25.4.0
│
│ System requirements met ✅
└────────────────────────────────────────────────────────────────────────────┘

┌─ RECOMMENDATION ─────────────────────────────────────────────────────────┐
│ ✅ Ready to install. No blocking issues detected.
│
│ Next step: npm install && clawdbot skill install
└────────────────────────────────────────────────────────────────────────────┘

With warnings (CAUTION)

$ skill-compatibility-checker ~/clawd/another-skill

┌─ INSTALLATION READINESS ─────────────────────────────────────────────────┐
│ ⚠️  CAUTION - Review issues before installation
│
└────────────────────────────────────────────────────────────────────────────┘

┌─ DEPENDENCIES ───────────────────────────────────────────────────────────┐
│ Missing CLI Tools:
│ ❌ ffmpeg
│    Install: brew install ffmpeg
│
│ Missing API Keys/Tokens:
│ ⚠️  groq - configure in TOOLS.md or environment
│ ⚠️  elevenlabs - configure in TOOLS.md or environment
└────────────────────────────────────────────────────────────────────────────┘

┌─ RECOMMENDATION ─────────────────────────────────────────────────────────┐
│ ⚠️  Proceed with caution. Review all issues above.
│
│ Actions before installation:
│ 1. Install missing CLI tools (see above)
│ 2. Configure missing API keys in TOOLS.md
│ 3. Review security findings and audit code if needed
└────────────────────────────────────────────────────────────────────────────┘

JSON output for programmatic use

$ skill-compatibility-checker ~/clawd/my-skill --output json

{
  "skill": {
    "name": "my-skill",
    "path": "/Users/ericwoodard/clawd/my-skill",
    "description": "Does something useful"
  },
  "readiness": "GO",
  "timestamp": "2026-01-29T15:30:00.000Z",
  "system": {
    "platform": "darwin",
    "arch": "arm64",
    "nodeVersion": "25.4.0",
    "osVersion": "26.2"
  },
  "conflicts": {
    "conflicts": [],
    "warnings": []
  },
  "systemRequirements": {
    "issues": [],
    "warnings": []
  },
  "dependencies": {
    "missingCLITools": [],
    "missingApiKeys": [],
    "clawdbotVersionRequired": null,
    "warnings": []
  },
  "security": {
    "riskLevel": "SAFE",
    "findings": [],
    "message": ""
  },
  "recommendation": "Ready to install. No blocking issues detected."
}

How It Works

1. Resolve Skill Path

• Local paths: ~/clawd/my-skill or /full/path/to/skill
• ClawdHub lookups: clawdhub:skill-name (future)

2. Parse Skill Metadata

• Read SKILL.md frontmatter (name, description, requirements)
• Read SKILL.md and README.md content
• Parse package.json (bin, engines, dependencies)

3. Check Conflicts

• Compare skill name with all installed skills in ~/clawd/
• Check if bin commands from package.json already exist in PATH
• Scan for port usage declarations

4. Verify System Requirements

• Compare required OS with process.platform (darwin, linux, win32)
• Compare required arch with process.arch (arm64, x64)
• Compare required Node version with running Node version
• Parse from SKILL.md and package.json engines field

5. Check Dependencies

• Search content for mentions of common CLI tools (ffmpeg, python, java, etc.)
• Check if those tools exist in PATH
• Parse SKILL.md/README for API key requirements
• Check TOOLS.md and process.env for configured keys
• Note npm dependencies from package.json

6. Run Security Scan

• Invoke security-scanner-skill if available
• Pass skill path to scanner
• Capture risk level and findings
• Report security assessment

7. Generate Report

• Determine readiness (GO / CAUTION / BLOCKED)
• Format as text (human-readable) or JSON (programmatic)
• Provide actionable remediation steps

Exit Codes

• 0 - GO: Ready to install
• 1 - CAUTION: Review and fix issues before installing
• 2 - BLOCKED: Do not install on this system

This allows scripts to programmatically handle compatibility:

skill-compatibility-checker ~/clawd/my-skill
if [ $? -eq 0 ]; then
  echo "Installing..."
  npm install && clawdbot skill install
elif [ $? -eq 1 ]; then
  echo "Review issues and try again"
  exit 1
else
  echo "Cannot install on this system"
  exit 2
fi

Requirements

• Node.js ≥ 14.0.0
• security-scanner-skill (optional, for security scanning)
• CLI tools (optional, detected if mentioned in skill docs)

How to Use with Other Skills/Sub-Agents

The skill-compatibility-checker is designed to be invoked by other tools:

# From command line
skill-compatibility-checker ~/clawd/some-skill --output json > report.json

# From Node.js
const checker = require('./scripts/checker.js');
const results = checker.checkSystemRequirements('./skill-path');

Configuration

Environment Variables

The checker automatically reads these to determine configured API keys:

• GROQ_API_KEY
• ELEVENLABS_API_KEY
• OPENAI_API_KEY
• STRIPE_API_KEY
• TWILIO_AUTH_TOKEN
• etc.

TOOLS.md Format

The checker looks in ~/clawd/TOOLS.md for API key sections:

## API Keys & Services

- **Groq API:** `gsk_...` (Whisper audio transcription)
- **ElevenLabs API:** Configured (sk_...)

Limitations

• ClawdHub lookups not yet implemented (use local paths)
• Port conflict detection is informational only (doesn't test actual ports)
• API key requirement detection is pattern-based (may miss some)
• CLI tool detection based on common names (ffmpeg, python, etc.)

Advanced: Programmatic API

Use the skill in your own code:

const {
  checkConflicts,
  checkSystemRequirements,
  checkDependencies,
  runSecurityScan,
  determineReadiness,
} = require('./scripts/checker.js');

// Run a single check
const sysReqs = checkSystemRequirements('./my-skill');
console.log(sysReqs);
// { issues: [], warnings: [] }

// Check readiness
const readiness = determineReadiness(results);
// 'GO' | 'CAUTION' | 'BLOCKED'

Tips

1. Before installing any skill, run the checker first:

   skill-compatibility-checker ~/clawd/new-skill
   

2. For CI/CD pipelines, use JSON output and exit codes:

   skill-compatibility-checker ~/clawd/new-skill --output json || exit $?
   

3. Check regularly - run the checker on existing skills if you update TOOLS.md:

   for skill in ~/clawd/*-skill; do
     skill-compatibility-checker "$skill" || true
   done
   

4. Resolve CAUTION warnings - they're fixable:

   • Install missing CLI tools: brew install <tool>
   • Configure API keys in TOOLS.md
   • Review security findings and ask maintainer

5. Don't force install BLOCKED skills - the system incompatibility is real and you'll encounter errors.

See Also

• security-scanner-skill - Static code analysis for malware/vulnerabilities
• TOOLS.md - Your API key configuration file
• SKILL.md - Skill metadata format