#1241·skills

[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:

  1. 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).
  2. Local augmentation files leak — files like SKILL.local.md are 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:

yaml
---
name: my-skill
description: Does something useful.
files:
  - SKILL.md
  - scripts/
  - "!scripts/dev-only.sh"
---
  • If files is omitted, current behavior is preserved (copy everything minus the default exclusions).
  • If files is present, only matching paths are copied.
  • SKILL.md is 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 files field would also solve that use case by letting authors explicitly opt those files in.