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

Before installing any skill, run the checker first:
```
skill-compatibility-checker ~/clawd/new-skill
```

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

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

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

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
Don't force install BLOCKED skills - the system incompatibility is real and you'll encounter errors.

skill-compatibility-checker