skill-portability-auditlisted

# Auditing a skill for cross-agent portability A skill that works in one agent frequently breaks silently in another. The failure modes are specific and checkable — run this audit before publishing, and whenever a user reports "it loads in X but not in Y". ## The five silent failure modes 1. **Name collision + tier shadowing.** dsh and Codex read *both* `<project>/.agents/skills` (tier 200) and `~/.agents/skills` (tier 500). The same skill name at both levels: the project copy wins **silently** — no warning, ever. If a user's project has an unrelated skill with your name, yours never loads. 2. **Nested SKILL.md.** Every harness scans only the *direct children* of a skill root. `skills/a/SKILL.md` loads; `skills/a/b/SKILL.md` is invisible in all of them. Monorepos that nest skills under product directories hit this constantly. 3. **Name mangling.** Frontmatter `name: My Skill!` gets normalized differently by different tools — some mangle, some reject. The safe form is kebab-case matching the directory name exactly. 4. **Trigger starvation or flooding.** The `description` is the only thing agents match requests against. "A collection of helpers" never triggers; a description listing every keyword triggers on everything and dilutes routing. 5. **Format assumptions.** Flat `my-skill.md` files are a dsh convenience — Claude Code only reads `<dir>/SKILL.md`. And relative links to files outside the skill folder break the moment the skill