fix(skills): align frontmatter with latest standards and wire $ARGUMENTS (#187)

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: ryzizub

agents/quality-review/pr-readiness-review-agent.md

@@ -2,7 +2,6 @@
 name: pr-readiness-review-agent
 description: Checks PR readiness — formatting, static analysis, debug artifacts, and commit hygiene — to catch mechanical issues before opening a pull request.
 model: haiku
-effort: low
 ---
 
 # PR Readiness Review Agent

skills/brainstorm/SKILL.md

@@ -1,7 +1,8 @@
 ---
 name: brainstorm
 user-invocable: true
-description: Explores requirements and approaches through collaborative dialogue before planning implementation. Use when user says "brainstorm", "explore idea", "what should we build", "think through this", or "let's discuss approaches".
+description: Explores requirements and approaches through collaborative dialogue before planning implementation.
+when_to_use: Use when user says "brainstorm", "explore idea", "what should we build", "think through this", or "let's discuss approaches".
 argument-hint: feature or idea to explore
 compatibility: Designed for Claude Code (or similar products with agent support)
 ---

skills/build/SKILL.md

@@ -1,7 +1,8 @@
 ---
 name: build
 user-invocable: true
-description: Executes an implementation plan — writes code and tests, runs quality review, and ships a pull request. Use when user says "build this", "implement the plan", "start coding", "execute the plan", or "ship it".
+description: Executes an implementation plan — writes code and tests, runs quality review, and ships a pull request.
+when_to_use: Use when user says "build this", "implement the plan", "start coding", "execute the plan", or "ship it".
 effort: high
 argument-hint: plan file path
 allowed-tools: Bash(rm -rf docs/reviews/)

skills/create-branch/SKILL.md

@@ -1,7 +1,8 @@
 ---
 name: create-branch
 user-invocable: true
-description: Sets up a workspace branch or worktree before writing artifacts. Use when user says "create a branch", "set up workspace", "start a feature branch", or "new branch".
+description: Sets up a workspace branch or worktree before writing artifacts.
+when_to_use: Use when user says "create a branch", "set up workspace", "start a feature branch", or "new branch".
 argument-hint: feature name or context
 allowed-tools: Bash(*/scripts/detect-base-branch.sh) Bash(git checkout *)
 effort: low

skills/create-commit/SKILL.md

@@ -1,8 +1,10 @@
 ---
 name: create-commit
 description: Propose and create conventional commit messages for staged changes. Follows Conventional Commits spec and VGV workflow.
+when_to_use: Use when user says "commit this", "create a commit", "write a commit message", or "commit my changes".
 argument-hint: "[optional: single-commit | ticket/issue number e.g. VGV-123]"
 allowed-tools: Bash(git commit *) Bash(git add *)
+compatibility: Designed for Claude Code (or similar products with git access)
 ---
 
 # Create a commit

skills/create-pr/SKILL.md

@@ -1,9 +1,11 @@
 ---
 name: create-pr
 description: Stage, commit, push, and open a pull request following project conventions and the Conventional Commits spec. Accepts optional skip-checks argument to bypass validation when called from /build.
+when_to_use: Use when user says "create a PR", "open a PR", "ship it", "submit a pull request", or "open a merge request".
 argument-hint: "[optional: skip-checks | ticket/issue number e.g. VGV-123 | short description]"
 disable-model-invocation: true
 allowed-tools: Bash(git push *) Bash(git add *) Bash(git commit *) Bash(gh *) Bash(glab *)
+compatibility: Designed for Claude Code (or similar products with git access)
 ---
 
 # Create a pull request

skills/create/SKILL.md

@@ -1,7 +1,8 @@
 ---
 name: create
 user-invocable: true
-description: Scaffolds a new project by routing to the right companion plugin's create skill. Use when user says "create a project", "new flutter app", "start a dart package", "scaffold", or asks to set up a new codebase.
+description: Scaffolds a new project by routing to the right companion plugin's create skill.
+when_to_use: Use when user says "create a project", "new flutter app", "start a dart package", "scaffold", or asks to set up a new codebase.
 argument-hint: what to create (e.g., "flutter app", "dart package")
 effort: low
 allowed-tools: Read Glob Skill

skills/debrief/SKILL.md

@@ -1,7 +1,8 @@
 ---
 name: debrief
 user-invocable: true
-description: Produces a structured post-incident analysis — timeline, root cause, and actionable follow-ups — while context is fresh. Use when user says "debrief", "post-mortem", "incident review", or "root cause analysis".
+description: Produces a structured post-incident analysis — timeline, root cause, and actionable follow-ups — while context is fresh.
+when_to_use: Use when user says "debrief", "post-mortem", "incident review", or "root cause analysis".
 argument-hint: incident description, PR/commit refs, or error context
 effort: high
 compatibility: Designed for Claude Code (or similar products with agent support)

skills/elements-of-style/SKILL.md

@@ -1,7 +1,8 @@
 ---
 name: elements-of-style
 user-invocable: false
-description: Applies Strunk's Elements of Style principles when writing or editing prose. Triggers on "write clearly," "edit for style," "improve writing," or tasks requiring clear, vigorous English — documents, emails, reviews.
+description: Applies Strunk's Elements of Style principles when writing or editing prose.
+when_to_use: Triggers on "write clearly," "edit for style," "improve writing," or tasks requiring clear, vigorous English — documents, emails, reviews.
 compatibility: Designed for Claude Code (or similar products)
 ---
 

skills/plan-technical-review/SKILL.md

@@ -1,15 +1,18 @@
 ---
 name: plan-technical-review
 user-invocable: true
-description: Conducts a comprehensive technical review of an implementation plan, ensuring it meets requirements and follows best practices. Use when user says "review the plan", "is this plan ready", "validate my plan", or "check the plan".
+description: Conducts a comprehensive technical review of an implementation plan, ensuring it meets requirements and follows best practices.
+when_to_use: Use when user says "review the plan", "is this plan ready", "validate my plan", or "check the plan".
 argument-hint: path to plan file
 effort: high
 compatibility: Designed for Claude Code (or similar products with agent support)
 ---
 
 # Plan technical review
 
-Run the following agents in parallel to conduct a comprehensive technical review of the proposed plan:
+**Plan file:** `$ARGUMENTS` (if empty, ask the user for the plan path or pick the most recent file under `docs/plan/`).
+
+Run the following agents in parallel to conduct a comprehensive technical review of the plan at `$ARGUMENTS`. Pass the plan path to each agent:
 
 - @code-simplicity-review-agent: Review the plan for simplicity and clarity. Ensure the implementation is as straightforward as possible while still meeting all requirements.
 - @vgv-review-agent: Review the plan for adherence to Very Good Engineering practices and project conventions. Ensure the implementation follows our established patterns and conventions.