writing-great-skills

Place a strong leading word early in the description and write explicit trigger conditions rather than a summary. State each branch only once, remove identity statements the body already covers, and note when the skill should not be used if adjacent skills cause false triggers.

Use model-invoked only when the agent must discover the skill itself or other skills reference it automatically. Set disable-model-invocation for skills only called manually, which eliminates per-turn context load at the cost of user memorization.

Give every step a checkable completion criterion, such as requiring each acceptance criterion to map to a task with owned files and verification commands. If later steps still pull attention forward, split the sequence into separate skills.

Split only when it reduces risk or load: by invocation when a branch has its own trigger word, by sequence when later steps cause premature completion, or by branch when scenarios need different large references. Avoid splitting just to appear modular.

The documented failure modes are premature completion, duplication, sediment from outdated content, sprawl from excessive length, no-op instructions that change nothing, and negation phrasing that surfaces unwanted behavior instead of stating positive goals.