# AI Skill Portability Checklist A practical checklist to verify that an [[AI Agent Skills|AI skill]] is portable across machines, tools, models, and people. Run it against every skill before sharing it with a teammate, publishing it, or installing it on a different machine. It targets the most common sources of [[It works on my machine syndrome]] for AI skills. ## The checklist - [ ] **No absolute paths**. Every path is either relative or uses an environment variable - [ ] **No hardcoded folder structures**. Paths are configurable or discovered dynamically - [ ] **No model lock-in**. Instructions work across different AI models, or the dependency is documented - [ ] **No tool lock-in**. Tool-specific syntax is isolated and documented - [ ] **No OS lock-in**. Shell commands work cross-platform, or platform detection is in place - [ ] **No person lock-in**. Personal context is separated from reusable logic - [ ] **Dependencies are documented**. Required tools, CLIs, and permissions are listed at the top - [ ] **Config is externalized**. Anything that varies between users lives in a config block, not inline - [ ] **No secrets in the skill body**. API keys, tokens, credentials, and personal URLs are loaded from environment variables or a secrets manager, never inlined - [ ] **Network and permission assumptions are explicit**. Required internet access, reachable domains, proxy-friendliness, and filesystem/system permissions are documented - [ ] **Idempotent and safe to re-run**. Running the skill twice doesn't duplicate notes, corrupt state, or destroy prior work - [ ] **Fails gracefully**. When a dependency is missing or a precondition isn't met, the skill detects it, explains what's needed, and stops cleanly instead of producing garbage output - [ ] **No assumed session or conversation state**. The skill doesn't rely on a previous skill having run, on a specific note being open, or on context being pre-loaded - [ ] **Inter-skill dependencies are declared**. If the skill depends on another skill (chained, prerequisite, or shared helpers), that dependency is documented and version-aware ## How to use it Treat each item as a hard pass/fail. A skill that fails any one of them is not portable, even if it "works on your machine". Fix the failing items before distributing the skill or relying on it from a second machine. The same logic applies at higher levels too: bundles of skills, agents, and full workflows all need their own portability checks. See [[AI Agent Portability]] and [[AI Skill Resilience]] for the broader design practices that make passing this checklist easier. ## References - [[Why Your AI Skills Break on Other Machines (Article)]] ## Related - [[AI Skill Portability]] - [[AI Agent Portability]] - [[AI Skill Resilience]] - [[AI Agent Skills]] - [[Claude Code Skills]] - [[It works on my machine syndrome]] - [[Context-as-Code]] - [[Convention over Configuration]]