[Feature]: Add `files` field to SKILL.md frontmatter for include/exclude control
Author: unionalCreated May 24, 2026Updated Oct 1, 2026
Description
Skill authors currently have no way to control which files are copied when a user runs npx skills add. The CLI copies everything in the skill folder except a hardcoded exclusion list (.git, __pycache__, __pypackages__, metadata.json).
This creates two problems:
- No whitelist/allowlist — authors cannot restrict installation to only the files they intend to ship (e.g. exclude dev-only scripts, test fixtures, internal docs).
- Local augmentation files leak — files like
SKILL.local.mdare local overrides meant to stay on the author's machine, but they get copied to every user who installs the skill.
Proposed Solution
Add a files field to the SKILL.md frontmatter, following the same semantics as package.json#files:
---
name: my-skill
description: Does something useful.
files:
- SKILL.md
- scripts/
- "!scripts/dev-only.sh"
---- If
filesis omitted, current behavior is preserved (copy everything minus the default exclusions). - If
filesis present, only matching paths are copied. SKILL.mdis always included regardless.
Default Exclusions
In addition, *.local.* files (e.g. SKILL.local.md) should be excluded by default, since they are a convention for local-only augmentations that should never be distributed. This mirrors how .gitignore handles local overrides.
And should also exclude files like *.test.* too.
Related
- #734 — a related request about dotfiles not being included; the
filesfield would also solve that use case by letting authors explicitly opt those files in.
Source: vercel-labs/skills