Agent Portability Checker

Audit agent skills for platform lock-in and cross-agent compatibility. Use when checking if a skill is portable, making a skill work across multiple agents (...

Security Scan

The skill is an internal portability-audit and auto-fix tool whose code and instructions match its stated purpose — it reads and (with --fix) edits files in a target skill directory, and it does not request unrelated credentials or installs external packages.

Purpose & Capability

Name/description, SKILL.md, and the included scripts/audit.py are coherent: the repository contains an auditing script that looks for hardcoded paths, XDG fallbacks, SKILL_DATA_DIR usage, User-Agent strings, platform CLI invocations, headless setup flags, and credential env-var support. No unrelated environment variables, binaries, or install steps are requested.

Instruction Scope

SKILL.md tells the agent to run python3 scripts/audit.py <skill_dir> (and optionally --fix). The script will recursively read the provided directory and, when --fix is used, apply auto-fixes to files. This behavior is expected for a portability fixer but means the skill can modify files in any directory the agent is pointed at — review changes before applying --fix and avoid pointing it at sensitive system paths.

Install Mechanism

No install spec is provided (instruction-only with one helper script). This is the lowest-risk model: nothing is downloaded or installed automatically by the skill.

Credentials

The skill declares no required environment variables, no credentials, and no config-path access. The script itself searches target files for credential handling but does not request secrets from the runtime environment.

Persistence & Privilege

always:false and no special privileges are requested. However, the skill can be invoked autonomously (platform default) and — when given a path — can write changes to that path via its auto-fix mode. The combination of autonomous invocation and file-writing capability is not inherently malicious but merits caution (run audits read-only first; limit the directories the skill may inspect/modify).

Assessment

This skill appears to do what it says: audit a skill directory and optionally auto-fix portability issues. Before using --fix, run the audit in read-only or --json mode and inspect the findings. If you allow auto-fix, back up the target directory or review diffs produced by the script. Do not point the tool at system or home-root paths you don't want modified. If you plan to let agents call this skill autonomously, restrict which directories the agent may pass as <skill_dir> so it cannot scan or modify arbitrary filesystem locations.

Audit an agent skill for platform lock-in. Auto-fixes what it can, flags what needs manual attention.

Why

Skills with hardcoded paths only work on one platform. This tool catches those issues and fixes them — making your skills work everywhere agents run.

When to Use

• "Is this skill portable?"
• "Make this skill cross-platform"
• "Check for hardcoded paths"
• "Prepare a skill for other agents"

How to Run

python3 scripts/audit.py <skill_dir>          # audit only
python3 scripts/audit.py <skill_dir> --fix    # auto-fix + audit
python3 scripts/audit.py <skill_dir> --json   # structured output

What It Checks

📍 Hardcoded paths     — platform-specific dirs like ~/.<platform>/ in scripts
🔧 SKILL_DATA_DIR      — env var support for data dir resolution
📦 XDG fallback        — ~/.config/<skill>/ fallback path
🔌 Platform CLI deps    — external binary dependencies (e.g. clawhub, gh)
🏷️  User-Agent strings — platform names in HTTP headers
📄 SKILL.md paths      — platform-specific path references in docs
🖥️  Headless setup     — OAuth scripts without --no-browser flag
🔑 Credential env vars — file-only credentials with no env var alternative

Output Example

❌ github-growth-tracker — 8 errors, 9 warnings (9 auto-fixable)

📍 Hardcoded Paths
  ❌ scripts/github_tracker.py:28: ~/.<platform>/ [auto-fix]
  ❌ scripts/github_tracker.py:31: ~/.<platform>/ [auto-fix]

🔧 SKILL_DATA_DIR: Not supported — scripts use hardcoded paths
🔧 XDG Fallback: Missing ~/.config/ fallback path

Two-Phase Flow

1. Audit — show all findings (auto-fixable + manual)
2. Fix — apply auto-fixes, show brief "what changed" confirmation

The agent reads the script output and formats it for the current channel. See references/formatting.md for Slack/WhatsApp/Discord styling.

Auto-Fixes

• Replaces ~/.<platform>/credentials/ with $SKILL_DATA_DIR
• Replaces ~/.<platform>/workspace/data/<skill>/ with $SKILL_DATA_DIR/<skill>/
• Strips platform names from User-Agent strings
• Replaces hardcoded paths in SKILL.md with <DATA_DIR> placeholder

⚠ Output styling is never modified. Emojis, formatting, and visual elements in script output are preserved exactly as-is.

Manual flags require human review (platform CLI deps, headless setup, env var alternatives).

Formatting

Read references/formatting.md for channel-specific styling (Slack, WhatsApp, Discord, terminal).

The Portability Pattern

Skills that work everywhere follow this:

1. Resolve data dir via $SKILL_DATA_DIR (set by agent platform)
2. Fall back to ~/.config/<skill>/ (XDG-compliant, works everywhere)
3. Accept credentials via env var OR file (env var preferred)
4. Output to stdout — no platform messaging APIs
5. Self-contained scripts — no platform SDK imports