Choose a valid, specific name

The skill name is a small decision with a long life. It becomes the directory name, it shows up in metadata and docs, and users will type it in requests. Pick it carefully.

The rules

The specification is strict. Use lowercase letters, numbers, and hyphens. No spaces, no uppercase, no underscores. The name in the frontmatter must match the parent directory exactly.

So this is valid:

release-readiness/
└── SKILL.md   # name: release-readiness

And this fails validation, because the two don’t match:

release-readiness/
└── SKILL.md   # name: Release_Readiness

A validator rejects the second one before the agent ever sees it.

Say what it does

Avoid names like helper, assistant, or dev-tools. They tell the agent nothing about the job. Avoid product branding too, unless the workflow truly depends on that product.

Compare release with release-readiness. The second one names the decision the skill supports. It doesn’t imply the skill publishes anything, which is exactly our boundary.

prepare-and-publish-npm-release would be a different skill. It has broader authority and a specific ecosystem baked in. Not wrong, just not ours.

Names expose scope problems

If you need three “and” words to describe the skill, you probably glued several workflows together. Split them.

If the only honest name is very narrow, like check-changelog-has-todays-date, ask whether a project script or a line in AGENTS.md would do. Not everything deserves a skill.

Pick yours

Write five candidate names for your project. For each one, answer:

• could a user guess the job from the name alone?
• does it imply an action the skill can’t perform?
• would it still make sense in a different agent host?
• does it satisfy the naming rules of the specification?

Here’s how that exercise goes for the release project:

release           → too broad, implies publishing
ship-check        → vague, "ship" means different things
npm-preflight     → ties us to one ecosystem
release-audit     → close, but "audit" suggests compliance
release-readiness → names the decision, nothing more

Choose release-readiness for the project unless your extraction note pointed at a more accurate boundary. Write down why you rejected the others. When someone proposes renaming it in six months, you’ll want that note.