Add paragraph about agents undertriggering and the importance of
generous trigger contexts. Add tip about explaining reasoning rather
than relying on bare directives when overriding default behaviour.
@@ -50,6 +50,8 @@ description: Extracts text and tables from PDF files. Use when working with PDFs
The description is the primary trigger mechanism. The body only loads *after* activation, so "When to Use" sections in the body don't help agents discover the skill.
+Agents tend to undertrigger — they won't load a skill unless the description clearly matches the user's request. Be generous with trigger contexts. Include the obvious keywords, but also phrases the user might use when they need the skill without naming it directly. A description that triggers a few times when it isn't needed costs less than one that misses the cases where it would help.
+
**Good**: `Extracts text and tables from PDF files, fills forms, merges documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.`
**Bad**: `Helps with PDFs.`
@@ -72,6 +74,7 @@ allowed-tools: Bash(git:*) Read
- Information should live in either SKILL.md or references, not both
- Use consistent terminology throughout
- For large reference files (>10k words), include grep search patterns in SKILL.md
+- When the skill needs the agent to override its default behaviour (e.g., "write the test before the implementation"), explain the reasoning rather than relying on bare directives. The agent will follow a well-explained rationale more reliably than an all-caps MUST. Save the token economy for informational content the agent already knows.
### Recommended sections