diff --git a/skills/developing-claude-code-plugins/references/plugin-structure.md b/skills/developing-claude-code-plugins/references/plugin-structure.md
index 7eadfac..9018a29 100644
--- a/skills/developing-claude-code-plugins/references/plugin-structure.md
+++ b/skills/developing-claude-code-plugins/references/plugin-structure.md
@@ -178,6 +178,13 @@ For local testing, create in `.claude-plugin/`:
 
 ### Skills (skills/skill-name/SKILL.md)
 
+Skills have two discovery mechanisms that work together:
+
+1. **`description` frontmatter** — Claude reads this to decide whether to load the skill. Must include both what the skill does AND triggering conditions.
+2. **`## When to Use` body section** — Once loaded, this section gives Claude specific scenarios to match against. Without it, Claude may load the skill but fail to apply it correctly.
+
+**Both are required.** The `description` is the "should I look at this?" filter. The `## When to Use` section is the "does this actually apply?" confirmation. Omitting either one degrades skill discovery and activation.
+
 ```markdown
 ---
 name: skill-name
@@ -194,6 +201,7 @@ What this skill does in 1-2 sentences.
 
 - Specific scenario 1
 - Specific scenario 2
+- Key phrases or patterns that should trigger this skill
 
 ## Workflow