Filtering Reference

Complete specification of the three filtering layers that control which skills reach which targets.

Looking for quick guidance?

See Filtering Skills for a scenario-driven guide.

Overview

Layer	Scope	Where to set	Syntax	Evaluated at
.skillignore	Hides from all targets	Source dir or tracked repo root	gitignore	Discovery
SKILL.md metadata.targets	Restricts skills to listed targets	Per skill frontmatter	YAML list	Sync (parsed at discovery)
Target include/exclude	Per target, per resource	config.yaml or CLI flags	Go filepath.Match glob	Sync

Sync mode caveat

All three layers only apply to merge and copy sync modes. In symlink mode the entire source directory is linked as one unit — per-skill filtering has no effect.

Evaluation order and precedence

A skill must pass all layers to reach a target:

1. .skillignore — evaluated at discovery. Matching skills never enter the sync pipeline.
2. Target include/exclude — evaluated at sync (FilterSkills). Skills are discovered but skipped for non-matching targets.
3. SKILL.md metadata.targets — evaluated at sync (FilterSkillsByTarget). Skills are restricted to their declared targets.

.skillignore

Locations:

• Source root: ~/.config/skillshare/skills/.skillignore — applies to all skills
• Tracked repo root: _team-repo/.skillignore — applies only within that repo

Syntax: Full gitignore — * (single segment), ** (any depth), ?, [abc], !pattern (negation), /pattern (anchored), pattern/ (directory-only).

.skillignore.local: Place alongside .skillignore. Patterns are appended after the base file — last matching rule wins. Use !pattern to un-ignore. Don't commit this file.

CLI visibility:

Command	Output
skillshare sync	Count + skill names
skillshare status --json	source.skillignore object with patterns and ignored list
skillshare doctor	Pattern count and ignored count

📖 File structure reference

SKILL.md targets field

Format: Top-level or nested under metadata:

# Preferred
metadata:
  targets: [claude, cursor]

# Legacy fallback
targets: [claude, cursor]

Behavior: Whitelist — the skill only syncs to the listed targets. Omitting the field means sync to all targets. If both metadata.targets and top-level targets are present, metadata.targets wins.

Aliases: Target names support aliases. claude matches a target configured as claude-code. See Supported Targets.

📖 Skill format — targets field

Target include/exclude filters

Set via CLI:

# Skills
skillshare target claude --add-include "team-*"
skillshare target cursor --add-exclude "legacy-*"
skillshare target claude --remove-include "team-*"

# Agents
skillshare target claude --add-agent-include "team-*"
skillshare target claude --add-agent-exclude "draft-*"
skillshare target claude --remove-agent-include "team-*"

Stored in: config.yaml under targets.<name>.include / targets.<name>.exclude for skills, and targets.<name>.agents.include / targets.<name>.agents.exclude for agents.

Syntax: Go filepath.Match glob patterns matched against the flat resource name. Skills use flat skill names (e.g., _team__frontend__ui); agents use flat .md filenames.

Supported	Not supported
* (any chars)	** (recursive)
? (single char)	{a,b} (brace expansion)
[abc] (char class)

Precedence: When both include and exclude are set, include is applied first, then exclude. A matching resource that hits both is excluded.

Visual editor: skillshare ui → Targets page → "Customize filters" button.

📖 Target command · Filter behavior examples · Configuration

See also

• Filtering Skills — scenario-driven how-to guide