| name | skill-portability-checker |
| version | 1.0 |
| category | core |
| description | Validates that a skill's companion scripts declare their OS and binary dependencies correctly, and checks whether those dependencies are actually present on the current machine. |
Skill Portability Checker
What it does
Skills with companion scripts (.py, .sh) can silently fail on machines where their dependencies aren't installed. A skill written on macOS may call brew, pbcopy, or use /usr/local/bin paths that don't exist on Linux. A Python script may import pandas on a system without it.
Skill Portability Checker:
- Scans companion scripts for OS-specific patterns and external binary calls
- Checks whether those binaries are present on the current system (
PATH lookup + which)
- Cross-checks against the skill's declared
os_filter: frontmatter field (if any)
- Reports portability issues before the skill fails at runtime
Frontmatter field checked
---
name: my-skill
os_filter: [macos]
---
If os_filter: is absent the skill is treated as cross-platform. The checker then warns if OS-specific calls are detected without a corresponding os_filter:.
Checks performed
| Check | Description |
|---|
| OS_SPECIFIC_CALL | Script calls macOS/Linux/Windows-only binary without os_filter: |
| MISSING_BINARY | Required binary not found on current system PATH |
| BREW_ONLY | Script uses brew (macOS-only) but os_filter: includes non-macOS |
| PYTHON_IMPORT | Script imports a non-stdlib module; checks if importable |
| HARDCODED_PATH | Absolute path that doesn't exist on this machine (/usr/local, C:\) |
How to use
python3 check.py --check
python3 check.py --check --skill my-skill
python3 check.py --fix-hints my-skill
python3 check.py --format json
Procedure
Step 1 — Run the scan
python3 check.py --check
Step 2 — Triage FAILs first
- MISSING_BINARY: The script calls a binary that isn't installed. Either install it or add a graceful fallback in the script.
- OS_SPECIFIC_CALL without os_filter: Add
os_filter: [macos] (or whichever OS applies) to the frontmatter so users on other platforms know the skill won't work.
Step 3 — Review WARNs
- PYTHON_IMPORT: Install the missing module or add a
try/except ImportError with a graceful degradation path (like HAS_MODULE = False).
- HARDCODED_PATH: Replace with
Path.home() or environment-variable-based paths.
Step 4 — Add os_filter when needed
If a skill genuinely only works on one OS, declare it:
os_filter: [macos]
This prevents the skill from being shown as broken on other platforms — it simply won't be loaded there.
Output example
Skill Portability Report — linux (Python 3.11)
────────────────────────────────────────────────
32 skills checked | 1 FAIL | 2 WARN
FAIL obsidian-sync: MISSING_BINARY
sync.py calls `osascript` — not found on this system
Fix: add os_filter: [macos] to frontmatter (osascript is macOS-only)
WARN morning-briefing: PYTHON_IMPORT
run.py imports `pync` — not importable on this system
Fix: wrap in try/except ImportError and degrade gracefully
