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 (
PATHlookup +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] # optional: ["macos", "linux", "windows"]
---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 # Full portability scan
python3 check.py --check --skill my-skill # Single skill
python3 check.py --fix-hints my-skill # Print fix suggestions
python3 check.py --format jsonProcedure
Step 1 — Run the scan
python3 check.py --checkStep 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 ImportErrorwith a graceful degradation path (likeHAS_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