Best Practices for Defining AI Agent Skills: Structure, Naming, and Invocation

AI agent skills are used to automate repetitive, precisely describable processes, and must be carefully structured to minimize the risk of a model generating incorrect outputs. Skills can be invoked either explicitly by a developer or implicitly by the agent itself, and each one loaded into a session consumes context, making selective use important. Each skill must reside in its own dedicated directory, with the directory name matching the skill's name, and must contain a SKILL.md file holding its definition. The skill's YAML header requires at minimum a name — formatted in lowercase kebab-case between 1 and 64 characters — and a description of up to 1,024 characters specific enough for the agent to match it to user intent. Optional fields such as license, version, and context can further refine how a skill is managed, deployed, and legally used across different environments.