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:

   bash

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

2. •

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

   bash

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

3. •

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

   bash

   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