skill-compatibility-checker – OpenClaw Skill

---

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

Skill Compatibility Checker

vet skills before you install them

A Clawdbot skill that checks whether a new skill is compatible with your system before installation. Analyzes conflicts, system requirements, dependencies, and security issues—then gives you a clear GO/CAUTION/BLOCKED verdict with actionable fix steps.

Features

• ✅ Conflict Detection — Name, CLI command, and port conflicts with existing skills
• ✅ System Checks — OS, architecture, and Node.js version compatibility
• ✅ Dependency Audit — Missing CLI tools, API keys, Clawdbot versions
• ✅ Security Scan — Automated vulnerability scan via security-scanner-skill
• ✅ Clear Readiness — GO / CAUTION / BLOCKED with detailed next steps
• ✅ Multiple Outputs — Human-readable text and JSON for CI/CD

Installation

cd ~/clawd/skill-compatibility-checker-skill
npm install
chmod +x scripts/checker.js

Make it globally available:

npm link
# or manually: alias skill-compatibility-checker="~/clawd/skill-compatibility-checker-skill/scripts/checker.js"

Quick Start

# Check a skill before installing
skill-compatibility-checker ~/clawd/some-skill

# Get detailed JSON output
skill-compatibility-checker ~/clawd/some-skill --output json

# See help
skill-compatibility-checker --help

Understanding the Verdict

🟢 GO

Safe to install. No blocking issues.

$ skill-compatibility-checker ~/clawd/my-skill
✅ GO - Safe to install

Next step: npm install && clawdbot skill install

🟡 CAUTION

Installable with caveats. Review and fix issues first.

⚠️  CAUTION - Review issues before installation

Missing CLI Tools:
❌ ffmpeg
   Install: brew install ffmpeg

Missing API Keys:
⚠️  groq - configure in TOOLS.md

Fix the issues (install tools, configure keys), then install.

🔴 BLOCKED

Cannot install on this system.

❌ BLOCKED - Do not install

Issues preventing installation:
• System requirements not met (OS/arch/Node version)
• Skill name conflict with existing installation
• Security risk detected (dangerous patterns found)

Either:

• Use a compatible system
• Contact skill author about Windows/Linux/x86_64 support
• Uninstall the conflicting skill

What It Checks

Conflicts

• Skill name already installed
• CLI command collisions (e.g., both try to add foobar command)
• Port usage conflicts
• Config section overlaps

System Requirements

• OS: macOS, Linux, Windows
• Architecture: arm64, x86_64
• Node.js: Minimum version requirement

Dependencies

• CLI tools: ffmpeg, python, java, docker, etc.
• API keys: Groq, ElevenLabs, OpenAI, Stripe, Twilio, etc.
• Clawdbot version: X.Y.Z minimum
• npm packages: Listed but auto-installed

Security

• Code execution vulnerabilities (eval, exec)
• Credential theft patterns
• Suspicious network calls
• Obfuscation/minification

Use Cases

Manual Installation

Before installing a new skill from ClawdHub or GitHub:

git clone https://github.com/user/my-cool-skill ~/clawd/my-cool-skill
skill-compatibility-checker ~/clawd/my-cool-skill

# Review the report, fix any issues, then install
npm install && clawdbot skill install

CI/CD Pipelines

Validate skills before merging:

#!/bin/bash
skill-compatibility-checker ./skill --output json > report.json
if [ $? -eq 2 ]; then
  echo "Skill blocked on reference system (arm64/macOS/Node 25)"
  exit 1
fi
# ... continue with tests, build, deploy

Skill Repositories

Add to your skill's CI/CD to catch compatibility issues:

# GitHub Actions example
- name: Check compatibility
  run: |
    npm install -g clawdbot-skill-compatibility-checker
    skill-compatibility-checker .

Maintenance

Periodically check existing skills for issues:

for skill in ~/clawd/*-skill; do
  echo "Checking $(basename $skill)..."
  skill-compatibility-checker "$skill" || true
done

Output Formats

Text (Human-Readable)

Default output, designed for manual review:

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

Skill: my-skill
Path:  /Users/ericwoodard/clawd/my-skill

┌─ 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.
└────────────────────────────────────────────────────────────────────────────┘

JSON

Machine-readable, for programmatic use:

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

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

Exit Codes

• 0 — GO: Ready to install
• 1 — CAUTION: Fix issues before installing
• 2 — BLOCKED: Cannot install on this system

Use in shell scripts:

skill-compatibility-checker ~/clawd/my-skill
case $? in
  0) echo "Installing..."; npm install && clawdbot skill install ;;
  1) echo "Fix issues first"; exit 1 ;;
  2) echo "Incompatible system"; exit 2 ;;
esac

Configuration

API Keys

The checker looks in two places for API keys:

1. TOOLS.md (~/clawd/TOOLS.md):

   ## API Keys & Services
   - **Groq API:** `gsk_...`
   - **ElevenLabs API:** Configured
   

2. Environment Variables:

   export GROQ_API_KEY="gsk_..."
   export ELEVENLABS_API_KEY="sk_..."
   

If a skill needs groq and you have GROQ_API_KEY or mention it in TOOLS.md, it passes. Otherwise, it's flagged as missing.

Programmatic Usage

Use the checker in your own Node.js code:

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

// Check system requirements
const sysReqs = checkSystemRequirements('./my-skill');
if (sysReqs.issues.length > 0) {
  console.error('Incompatible:', sysReqs.issues);
  process.exit(2);
}

// Check all aspects
const results = {
  conflicts: checkConflicts('./my-skill', []),
  sysReqs,
  deps: checkDependencies('./my-skill'),
  security: runSecurityScan('./my-skill'),
};

const readiness = determineReadiness(results);
console.log(readiness); // 'GO' | 'CAUTION' | 'BLOCKED'

Limitations & Future Work

Current Limitations

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

Planned Features

• ClawdHub integration (skill-compatibility-checker clawdhub:skill-name)
• Actual port binding tests
• Custom required tool detection
• Caching of scan results
• Skill update notifications

Troubleshooting

"skill path not found"

skill-compatibility-checker ~/clawd/my-skill
# Error: Skill path not found: ~/clawd/my-skill

Fix: Use absolute paths or ensure directory exists:

skill-compatibility-checker /Users/ericwoodard/clawd/my-skill

"security-scanner-skill not installed"

UNKNOWN - security-scanner-skill not installed. Cannot perform security scan.

The checker continues without security scanning. Install optional dependency:

cd ~/clawd/security-scanner-skill && npm install

"BLOCKED: Requires Node.js 18.0.0, but you have 16.0.0"

You need to upgrade Node.js:

brew upgrade node
# or use nvm
nvm install 18 && nvm use 18

"Missing API Keys: groq"

Configure the API key in TOOLS.md:

## API Keys & Services
- **Groq API:** `gsk_...`

Or set environment variable:

export GROQ_API_KEY="gsk_..."

Related Skills

• security-scanner-skill — Deep vulnerability scanning (eval, exec, etc.)
• skill-creator-skill — Generate new skills from scratch
• trending-skills-monitor-skill — Track new skills on ClawdHub

Contributing

Found a bug or want to add a feature?

1. Fork the skill
2. Create a branch: git checkout -b feature/your-idea
3. Make changes and test: ./test.sh
4. Commit: git commit -am 'Add feature'
5. Push: git push origin feature/your-idea
6. Open a pull request

License

MIT — Use freely, modify, share.

---

Happy skill hunting! 🚀

Got a cool skill you want to install? Run it through the compatibility checker first!