From 81f55665e4c00809f565d9a89938652a22b71cc4 Mon Sep 17 00:00:00 2001 From: AIOSAI Date: Thu, 18 Jun 2026 17:57:54 -0700 Subject: [PATCH] =?UTF-8?q?feat(skills):=20frontmatter=20discipline=20?= =?UTF-8?q?=E2=80=94=20when=5Fto=5Fuse=20triggers=20+=20per-step=20success?= =?UTF-8?q?=20criteria=20(FPLAN-0284=20P5/D2,=20DPLAN-0213)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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. --- .../skills/apps/handlers/discovery_handler.py | 22 ++++++++++--------- src/aipass/skills/catalog/github/SKILL.md | 5 +++++ src/aipass/skills/templates/full/SKILL.md | 9 +++++++- .../skills/templates/markdown_only/SKILL.md | 9 +++++++- .../skills/templates/with_handler/SKILL.md | 9 +++++++- 5 files changed, 41 insertions(+), 13 deletions(-) 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 ```