diff --git a/src/aipass/skills/apps/handlers/discovery_handler.py b/src/aipass/skills/apps/handlers/discovery_handler.py
index e9c09274..86644465 100644
--- a/src/aipass/skills/apps/handlers/discovery_handler.py
+++ b/src/aipass/skills/apps/handlers/discovery_handler.py
@@ -90,16 +90,18 @@ def discover_skills_in_path(search_path, source_label):
         if not isinstance(metadata, dict):
             continue
 
-        skills.append(
-            {
-                "name": metadata.get("name", item.name),
-                "description": metadata.get("description", "No description"),
-                "path": item,
-                "has_handler": metadata.get("has_handler", False),
-                "source": source_label,
-                "tags": metadata.get("tags", []),
-            }
-        )
+        skill_entry = {
+            "name": metadata.get("name", item.name),
+            "description": metadata.get("description", "No description"),
+            "path": item,
+            "has_handler": metadata.get("has_handler", False),
+            "source": source_label,
+            "tags": metadata.get("tags", []),
+        }
+        when_to_use = metadata.get("when_to_use")
+        if when_to_use:
+            skill_entry["when_to_use"] = when_to_use
+        skills.append(skill_entry)
 
     json_handler.log_operation(
         "discovery_scan",
diff --git a/src/aipass/skills/catalog/github/SKILL.md b/src/aipass/skills/catalog/github/SKILL.md
index 780616cc..c722896d 100644
--- a/src/aipass/skills/catalog/github/SKILL.md
+++ b/src/aipass/skills/catalog/github/SKILL.md
@@ -3,6 +3,11 @@ name: github
 description: "GitHub operations via gh CLI: issues, PRs, CI runs, code review, API queries."
 version: 1.0.0
 tags: [dev, git, ci, github]
+when_to_use:
+  - Checking PR status, reviews, or merge readiness
+  - Viewing CI/workflow run status and logs
+  - Creating, closing, or commenting on issues or PRs
+  - Querying GitHub API for repository data
 requires:
   bins: [gh]
   pip: []
diff --git a/src/aipass/skills/templates/full/SKILL.md b/src/aipass/skills/templates/full/SKILL.md
index 6b2a1026..8442682a 100644
--- a/src/aipass/skills/templates/full/SKILL.md
+++ b/src/aipass/skills/templates/full/SKILL.md
@@ -3,6 +3,8 @@ name: {{SKILL_NAME}}
 description: TODO — describe what this skill does
 version: 1.0.0
 tags: []
+when_to_use:
+  - TODO — trigger phrase describing when an agent should reach for this skill
 requires:
   pip: []
   bins: []
@@ -16,10 +18,15 @@ has_handler: true
 TODO
 
 ## When to Use
-TODO
+Use this skill when:
+- TODO — concrete scenario or trigger phrase
+
+Do NOT use this skill when:
+- TODO — scenario where a different approach is better
 
 ## Steps
 1. TODO
+   - **Done when:** TODO — checkable success criterion for this step
 
 ## Example
 ```
diff --git a/src/aipass/skills/templates/markdown_only/SKILL.md b/src/aipass/skills/templates/markdown_only/SKILL.md
index d51bd04e..af27a30c 100644
--- a/src/aipass/skills/templates/markdown_only/SKILL.md
+++ b/src/aipass/skills/templates/markdown_only/SKILL.md
@@ -3,6 +3,8 @@ name: {{SKILL_NAME}}
 description: TODO — describe what this skill does
 version: 1.0.0
 tags: []
+when_to_use:
+  - TODO — trigger phrase describing when an agent should reach for this skill
 requires:
   pip: []
   bins: []
@@ -16,10 +18,15 @@ has_handler: false
 TODO
 
 ## When to Use
-TODO
+Use this skill when:
+- TODO — concrete scenario or trigger phrase
+
+Do NOT use this skill when:
+- TODO — scenario where a different approach is better
 
 ## Steps
 1. TODO
+   - **Done when:** TODO — checkable success criterion for this step
 
 ## Example
 ```
diff --git a/src/aipass/skills/templates/with_handler/SKILL.md b/src/aipass/skills/templates/with_handler/SKILL.md
index 6b2a1026..8442682a 100644
--- a/src/aipass/skills/templates/with_handler/SKILL.md
+++ b/src/aipass/skills/templates/with_handler/SKILL.md
@@ -3,6 +3,8 @@ name: {{SKILL_NAME}}
 description: TODO — describe what this skill does
 version: 1.0.0
 tags: []
+when_to_use:
+  - TODO — trigger phrase describing when an agent should reach for this skill
 requires:
   pip: []
   bins: []
@@ -16,10 +18,15 @@ has_handler: true
 TODO
 
 ## When to Use
-TODO
+Use this skill when:
+- TODO — concrete scenario or trigger phrase
+
+Do NOT use this skill when:
+- TODO — scenario where a different approach is better
 
 ## Steps
 1. TODO
+   - **Done when:** TODO — checkable success criterion for this step
 
 ## Example
 ```