SKM-P01 · Portability
`paths` is a Cursor-only field
`paths` scopes a skill to files matching glob patterns — it works only in Cursor, and it doesn't just get ignored elsewhere.
What the rule is
`paths` scopes a skill to files matching glob patterns, and it's a Cursor-only frontmatter field — triggering on files touched rather than on phrasing, which is unique to Cursor among the five runtimes this site has verified.
The trap: this doesn't just get ignored in other runtimes the way most runtime-only fields do. Per a verified, open GitHub issue, adding `paths` to a skill running in Claude Code makes it completely undiscoverable — absent from `/` autocomplete, unlisted, and returning 'Unknown skill' on direct invocation. Removing the single line restores it.
Where it comes from
- Agent Skills compatibilityRuntime documentation
- anthropics/claude-code #49835 — `paths` makes a skill undiscoverableVerified issue — open since April 2026
Which runtimes enforce it
| Runtime | Effect | Note |
|---|---|---|
| Claude Code | Breaks the skill | Makes the skill entirely undiscoverable: absent from `/` autocomplete, unlisted, and returns 'Unknown skill' on direct invocation. |
| Codex | Ignored | Not the field's home runtime — the field is ignored. |
| Cursor | Enforced (home runtime) | The field's home runtime — scopes triggering to files matching the given glob patterns. |
| OpenClaw | Ignored | Not the field's home runtime — the field is ignored. |
| Hermes Agent | Ignored | Not the field's home runtime — the field is ignored. |
How to fix it
- If the skill needs to run in Claude Code (or any runtime other than Cursor), remove `paths` entirely.
- If file-scoped triggering is genuinely needed, keep this as a Cursor-specific variant of the skill rather than sharing one file across runtimes.
Elsewhere
- SKILL.md, the formatThe full frontmatter field table this rule is drawn from.
- Agent Skills Not WorkingThe diagnostic reference this rule’s portability and failure evidence comes from.
- All rulesEvery check the validator runs, grouped by class.