writing-great-skills

Predictable skill design uses a defined vocabulary and structural rules to reduce ambiguity and alignment friction, ensuring consistent agent behavior across both model-invoked and user-invoked skills. It establishes shared terms and an information hierarchy for actionable outputs.

Structure your SKILL.md using an information hierarchy that co-locates steps, branches, and context pointers. Apply progressive disclosure by placing references behind expandable sections to keep the file readable and actionable without overwhelming the agent's context load.

Leading words are part of a shared glossary that unifies skill design decisions by establishing clear triggers and branches. They guide the instruction structure to ensure predictable agent behavior and prevent duplicate operations across model-invoked and user-invoked skills.

Yes, the structural rules and glossary apply across both model-invoked and user-invoked skills. It guides description writing, branch logic, and reference placement behind progressive disclosure to ensure consistent behavior regardless of invocation type.

Avoid duplication and no-ops by following best practices for organizing steps and references within the defined information hierarchy. Map triggers and branches to the shared glossary to ensure each step performs a distinct, actionable operation.