agent-skill-mechanics

Treat the description as the trigger surface by naming the real situations that should activate the skill. Keep one trigger per distinct use, avoid stacking near-synonyms, and include aliases only when users would actually type them.

Put the most-used instructions closest to the top and keep required steps in the order the agent should perform them. End each important step with a checkable done condition, and move optional detail into support files only when some runs need it.

Add support files only when they reduce real clutter or repeated work, not for future possibilities. Every extra file should have a clear reason to exist, and the package should remain followable from SKILL.md alone.

Delete no-op sentences the agent would already follow, remove duplicate meanings, and replace repeated explanations with one strong term. Each remaining line should change invocation, execution, checking, or maintenance.

Confirm the folder name, frontmatter name, registry id, and registry path match, verify every listed support file exists, update README tables when required, run the repo's skill validator, and search for stale names or rejected aliases.