Skill scoping convention (paths: frontmatter)

Closes Gap #3 from RD-0033 — skills currently load globally, polluting context with irrelevant suggestions and inflating token usage.

The rule

Every skill in .claude/commands/*.md must declare a paths: field in its frontmatter, listing the glob patterns where the skill is relevant. Skills without paths: load globally — only acceptable for cross-cutting infrastructure skills (e.g., session-close, screenshot).

Frontmatter format

---
description: One-line description of what this skill does.
allowed-tools: Read, Write, Edit, Glob, Grep, Bash
model: sonnet
paths:
  - content-in/{domain}/**
  - {output-directory}/{request-pattern}/**
---

How to choose paths

Skill kind	Typical paths
Domain-specific (e.g., legal-review)	content-in/legal/**, requests/**/legal/**
Output-producing (e.g., generate-fiche)	{output-directory}/**, requests/**
Cross-cutting (e.g., session-close, ci)	Omit paths: — global load is intentional
Per-client tooling	The client-specific subtree only

Anti-patterns

• paths: ['**'] — equivalent to global, defeats the purpose. Either declare a real scope or omit the field.
• Listing every directory in the repo — if you can't pick 1–3 scopes, the skill is probably doing too much; split it.
• Adding paths: to a skill that fundamentally crosses domains (/ci, /maint-fix) — these are genuinely global.

Migration checklist (during assembly Phase C)

For each skill in the talent:

• Identify the natural file scope (where would a user be working when invoking this?)
• Add paths: to frontmatter — or document why global load is correct
• Smoke-test: open a file outside scope and verify the skill is unavailable

Example

See example-scoped-skill.md in this directory.

See also

• ../USAGE.md Section A step 5 — where this convention is applied during talent assembly
• ../../assembly-checklist-template.md Phase D.kit — the checklist item that enforces it at QA
• example-scoped-skill.md — a properly-scoped skill, ready to copy