Choosing a Name and Scope

One skill, one job

Aim for one coherent job per skill: "release-notes", "pr-review", "db-migration-check", "browser-automation". A skill that tries to do five unrelated things has a vague description, triggers wrongly and is hard to maintain; five small skills with sharp descriptions work better than one giant one. Names should be lowercase with hyphens, descriptive, and match the folder name; prefer verb-or-noun phrases that you would say out loud ("pr-review"), avoid clever names. Decide the scope boundary explicitly: what the skill does not cover (for example, "does not deploy; only checks readiness"). If two skills could both match a request, either merge them, sharpen their descriptions so they differ, or let one hand off to the other by name.

Name it, describe it, structure it

The description decides whether the skill is used; the body decides whether it works.

Good and poor names and scopes

Names that say what the skill does, and scopes that say what it does not.

POOR                      BETTER                       why
helper                    release-notes                says what it does
my_skill_v2               pr-review                    lowercase, hyphens, no version in the name
devops-everything         deploy-check, rollback-plan  one job each, sharp descriptions
stuff                     db-migration-check           discoverable by name and by description

Scope line in the body:  "Does NOT deploy or modify files; it only reports readiness."

Quick check: Why prefer several small skills to one giant skill?

• Small skills are always faster
• Sharper descriptions trigger correctly and are easier to maintain
• Giant skills are not allowed
• It reduces the number of files to zero