feat(skills): frontmatter discipline — when_to_use triggers + per-step success criteria (FPLAN-0284 P5/D2, DPLAN-0213)

Harvested from Claude Code's skill-authoring spec:
- when_to_use frontmatter field (trigger phrases) on all 3 SKILL.md templates + github catalog exemplar; discovery scan surfaces it so agents see triggers without loading the full body.
- Per-step 'Done when:' success criteria in the Steps section.
- 'Use when / Do NOT use when' structure in the When to Use section.

252/252 tests pass.

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",

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: []

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
 ```

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
 ```

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
 ```