Best Version — ai-layer-kit/skills/SCOPING.md

Best Version — ai-layer-kit/skills/SCOPING.md

Score: 12/12 Iteration: #1 Date: 2026-05-26

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