From 8ab6466c6bdf49cd5afd107171552b5c48707e8b Mon Sep 17 00:00:00 2001 From: raphaeelsamyquantumlends Date: Mon, 16 Mar 2026 14:42:02 -0300 Subject: [PATCH] docs: clarify that When to Use section is required for skills The skill template in plugin-structure.md showed the ## When to Use section but didn't explain why it matters. Without explicit guidance, skill authors may include the description frontmatter but skip the body section, degrading skill discovery and activation. Added explanation of the two-layer discovery mechanism (description for filtering, When to Use for confirmation) and marked both as required. Co-Authored-By: Claude Opus 4.6 (1M context) --- .../references/plugin-structure.md | 8 ++++++++ 1 file changed, 8 insertions(+) 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