Agent skills are reusable units of engineering judgement for AI coding agents, but their effectiveness depends heavily on how well their descriptions are written. The description acts as selection metadata — the agent uses it to decide whether to load a skill before reading its detailed instructions. Vague or overly broad descriptions cause skills to be skipped or loaded inappropriately, leading to inconsistent output. Good descriptions should specify the trigger scenario, main capabilities, expected output, and explicit boundaries (e.g., 'Use this skill when reviewing Terraform PRs for Azure infrastructure... Do not use it for application code reviews'). As skill libraries grow, overlapping descriptions cause selection conflicts. Testing descriptions against real engineer prompts — including negative tests where the skill should NOT load — is essential to validate selection boundaries.
