Two Dev.to posts describe a common, silent failure in custom AI agent skills: the skill “looks perfect” but never runs. The articles say the agent’s selection logic relies on the skill’s SKILL.md description. When a user request is made, the agent scans installed skills and compares the user’s wording to each skill’s description. If the match is close enough, the skill loads; otherwise it is skipped without error.
Both sources argue the main cause is descriptions written too narrowly, functioning like labels rather than trigger maps. For example, a description such as “Reviews pull requests” may fail when users ask in different language like “check this,” “look over my code,” “audit my code,” or “review this diff,” because those natural phrases are not covered.
The suggested fix is to rewrite the description around how users actually phrase requests, using plain language task wording and listing synonyms. They also recommend testing with casual, natural prompts and iterating the description until the skill triggers reliably. Finally, both posts advise writing the description first—before the skill body—to ensure the trigger conditions are correct.
