effective-agent-skills

A SKILL.md description should include three elements: what the skill does, when to use it with concrete trigger phrases, and a differentiator from related skills. The description is the only text the agent sees before deciding to load the skill, so routing failures are almost always description problems.

Skills fail to trigger when the description lacks the specific phrases users actually say. Add explicit trigger phrases and situations to the description, then test by asking the agent a matching request without naming the skill directly.

The official ceiling is under 500 lines, but the practical target is under 100 lines. Content beyond that should move into a references/ directory that the agent loads only when needed, keeping activation cheap.

Progressive disclosure is the three-stage loading model: name and description stay in context for discovery, the full SKILL.md body loads on activation, and referenced files or scripts load only on demand. This keeps bundled content from consuming tokens until accessed.

Third-party skills can execute arbitrary code and steer agent behavior, so audit every file before installing. Check scripts for unexpected network calls or file access, scan references for prompt injection, verify the name is not typosquatting, and run in a sandbox first.