ai-driven-dev · alexsoyes · Jun 19, 2026 · Jun 18, 2026 · Jun 18, 2026
diff --git a/lefthook.yml b/lefthook.yml
@@ -62,6 +62,15 @@ pre-commit:
             exit 1
           fi
         done
+    sync-skill-argument-hints:
+      glob: "plugins/*/skills/**"
+      run: |
+        if ! command -v node >/dev/null 2>&1; then
+          echo "ℹ️  node not available; skipping sync-skill-argument-hints"
+          exit 0
+        fi
+        node scripts/sync-skill-argument-hints.mjs >/dev/null
+        git add plugins/*/skills/*/SKILL.md 2>/dev/null || true
     summarize-plugin-catalogs:
       run: |
         [ -d plugins ] || exit 0
@@ -73,7 +82,7 @@ pre-commit:
           name=$(basename "$plugin")
           node scripts/summarize-markdown.js "$plugin" "${plugin}CATALOG.md" \
             --depth=4 \
-            --fields=description,argument-hint \
+            --fields=description \
             --title="$name catalog" \
             --tagline="Auto-generated index of skills, agents, references and assets shipped by the \`$name\` plugin." \
             >/dev/null

diff --git a/plugins/aidd-context/skills/00-onboard/SKILL.md b/plugins/aidd-context/skills/00-onboard/SKILL.md
@@ -1,6 +1,7 @@
 ---
 name: 00-onboard
 description: Guide the user through the AIDD framework on the current project. Explain the flow in plain language and suggest the next logical step, adapted to what is already set up and which AIDD plugins are installed. Use when the user asks where to start, what to do next, how AIDD works, or to be onboarded. Not for listing every installed surface (the explore skill does that) or running a skill the user already knows they need (invoke it directly).
+argument-hint: read-project | orient | act
 ---
 
 # Onboard

diff --git a/plugins/aidd-context/skills/01-bootstrap/SKILL.md b/plugins/aidd-context/skills/01-bootstrap/SKILL.md
@@ -1,6 +1,7 @@
 ---
 name: 01-bootstrap
 description: Imagine and validate the technical architecture of a new SaaS through interactive Q&A, candidate-stack comparison, multi-agent audit, and an INSTALL.md output. Use when starting a new SaaS project, choosing a stack, designing the architecture pattern (monolith vs microservices vs serverless), or producing a project's INSTALL.md. Do NOT use for editing an existing project's stack, database schema design, or scaffolding actual files (this skill produces docs only, no code).
+argument-hint: gather-needs | propose-candidates | audit-candidates | pick-and-design | write-install-md
 ---
 
 # Bootstrap

diff --git a/plugins/aidd-context/skills/02-project-memory/SKILL.md b/plugins/aidd-context/skills/02-project-memory/SKILL.md
@@ -1,6 +1,7 @@
 ---
 name: 02-project-memory
 description: Initialize or refresh the project memory bank. Not for updating one memory file after it exists (use the learn skill) or editing a single rule (edit it directly).
+argument-hint: init-context-file | scaffold-docs | generate-memory | review-memory | sync-memory
 ---
 
 # Project Memory

diff --git a/plugins/aidd-context/skills/04-skill-generate/SKILL.md b/plugins/aidd-context/skills/04-skill-generate/SKILL.md
@@ -1,6 +1,7 @@
 ---
 name: 04-skill-generate
 description: Generate a router-based skill across the host AI tools a project uses. Use when the user wants to create, scaffold, or refactor a skill, or turn a workflow into one. Not for other artifacts like rules, agents, commands, hooks.
+argument-hint: capture-intent | decompose-actions | draft-skill | write-actions | validate
 ---
 
 # Skill Generate

diff --git a/plugins/aidd-context/skills/04-skill-generate/actions/03-draft-skill.md b/plugins/aidd-context/skills/04-skill-generate/actions/03-draft-skill.md
@@ -14,7 +14,7 @@ One SKILL.md per confirmed tool, and the list of files written.
 
 1. **Build.** Copy `@../assets/skill-template.md` into one canonical SKILL.md. Strip the scaffold (comments + `<...>`).
    - Modify: edit in place. Keep non-router sections, change only the touched rows.
-2. **Frontmatter.** Fill per R5 and the naming (`@../references/skill-authoring.md`). `name` equals the folder. Manual mode adds the manual-only flag.
+2. **Frontmatter.** Fill per R5 and the naming (`@../references/skill-authoring.md`). `name` equals the folder. For plugin source, or host tools that support it, `argument-hint` lists action names only when the skill has two or more actions, joined with ` | `, and must match the action plan. Manual mode adds the manual-only flag.
    - Host: per-tool frontmatter (`@../references/tool-paths.md`).
    - Plugin source: keep canonical `name` + `description`. Reconciled at install.
 3. **Body.** Write the action table. State the flow in one line.
@@ -31,4 +31,4 @@ One SKILL.md per confirmed tool, and the list of files written.
 
 - Each SKILL.md exists and starts with `---` frontmatter.
 - Each is 500 lines or fewer and sits under the target base.
-- The action-table slugs match the plan.
+- The action-table slugs match the plan. `argument-hint` is omitted for one-action skills; when emitted, its action names match the plan.
diff --git a/plugins/aidd-context/skills/04-skill-generate/actions/04-write-actions.md b/plugins/aidd-context/skills/04-skill-generate/actions/04-write-actions.md
@@ -14,11 +14,13 @@ One file per action, per confirmed tool, at `<skills root>/<name>/actions/<NN>-<
 
 1. **Resolve.** Host mode: for each confirmed tool, resolve the skills root from `@../references/tool-paths.md`. Plugin source: use `plugins/<plugin>/skills/<name>/`.
 2. **Fill.** For each action, fill `@../assets/action-template.md`: strip the scaffold (comments + `<...>`), copy the test from 02 verbatim into `## Test`.
+3. **Sync hint.** When the parent SKILL.md accepts `argument-hint` and has two or more actions, update it from the final action file names only, joined with ` | `. Omit it for one-action skills. In this repository, run `node scripts/sync-skill-argument-hints.mjs`; otherwise edit the field directly.
    - Modify: write only the changed actions, leave the rest untouched.
-3. **Compose.** Include any template or reference via `@<path>`. Never "read X then apply".
-4. **Validate.** Run the write-target validation (`@../references/tool-paths.md`).
+4. **Compose.** Include any template or reference via `@<path>`. Never "read X then apply".
+5. **Validate.** Run the write-target validation (`@../references/tool-paths.md`).
 
 ## Test
 
 - Each action file exists and carries `## Output`, `## Process`, `## Test`.
+- One-action skills omit `argument-hint`. When present, the parent SKILL.md `argument-hint` lists the same action names as the action files.
 - Each sits under the target base.
diff --git a/plugins/aidd-context/skills/04-skill-generate/assets/skill-template.md b/plugins/aidd-context/skills/04-skill-generate/assets/skill-template.md
@@ -1,6 +1,7 @@
 ---
 name: <skill-name>
 description: <What the skill does, third person, one clause>. Use when <explicit, slightly pushy trigger phrases users actually type; the model under-triggers, so over-list>. <Optional: "Not for <X>, use <Y>" only when a sibling skill could mis-trigger.> (<= 1024 chars, third person, no XML tags; all "when" lives here, not in the body.)
+argument-hint: <action-name-1 | action-name-2> # omit when the skill has only one action
 ---
 
 # <Skill Name>

diff --git a/plugins/aidd-context/skills/04-skill-generate/references/skill-authoring.md b/plugins/aidd-context/skills/04-skill-generate/references/skill-authoring.md
@@ -41,6 +41,7 @@ The router: YAML frontmatter + markdown body.
 
 - `name` (kebab-case, <= 64 chars) MUST equal the skill's folder name. No colon, slash, dot, plugin prefix, or namespace. Reserved words forbidden: `anthropic`, `claude`. Regex `^[a-z0-9]+(-[a-z0-9]+)*$`.
 - `description`: per R5.
+- `argument-hint` when supported or in plugin source and the skill has two or more actions: action names only, joined with ` | `, matching the files in `actions/`. Omit it for one-action skills.
 - A manual-only flag makes the skill user-only. The exact frontmatter key is per tool.
 - Body: pure router. The action table maps each `#` and slug to a role and input. State the flow (a sequential chain or a trigger-to-action map). Self-skips stated explicitly.
 

diff --git a/plugins/aidd-context/skills/05-rule-generate/SKILL.md b/plugins/aidd-context/skills/05-rule-generate/SKILL.md
@@ -1,6 +1,7 @@
 ---
 name: 05-rule-generate
 description: Generate a coding rule that governs editor and agent behavior, across the host AI tools a project uses. Use when the user wants to write, add, or refactor a rule, a convention, or a coding standard, or to scan a codebase and propose rules. Not for other artifacts like skills, agents, commands, hooks.
+argument-hint: capture-rule | write-rule | validate
 ---
 
 # Rule Generate

diff --git a/plugins/aidd-context/skills/06-agent-generate/SKILL.md b/plugins/aidd-context/skills/06-agent-generate/SKILL.md
@@ -1,6 +1,7 @@
 ---
 name: 06-agent-generate
 description: Generate an agent across the host AI tools a project uses. Use when the user wants to create, scaffold, or refactor an agent, subagent or specialized role. Not for other artifacts like skills, rules, commands, hooks.
+argument-hint: capture-agent | write-agent | validate
 ---
 
 # Agent Generate

diff --git a/plugins/aidd-context/skills/07-command-generate/SKILL.md b/plugins/aidd-context/skills/07-command-generate/SKILL.md
@@ -1,6 +1,7 @@
 ---
 name: 07-command-generate
 description: Generate a flat slash command across the host AI tools a project uses. Use when the user wants to create, scaffold, or refactor a one-shot slash command. Not for multi-step skills or other artifacts like rules, agents, hooks.
+argument-hint: capture-command | write-command | validate
 ---
 
 # Command Generate

diff --git a/plugins/aidd-context/skills/08-hook-generate/SKILL.md b/plugins/aidd-context/skills/08-hook-generate/SKILL.md
@@ -1,6 +1,7 @@
 ---
 name: 08-hook-generate
 description: Generate a hook (a handler that runs automatically at a lifecycle event) across the host AI tools a project uses. Use when the user wants to create, scaffold, or refactor a hook, or automate an action at a lifecycle point. Not for other artifacts like skills, rules, agents, commands.
+argument-hint: capture-hook | write-hook | validate
 ---
 
 # Hook Generate

diff --git a/plugins/aidd-context/skills/10-learn/SKILL.md b/plugins/aidd-context/skills/10-learn/SKILL.md
@@ -1,6 +1,7 @@
 ---
 name: 10-learn
 description: Capture durable project learnings from the conversation or the project's git history and route them to memory, a decision record, a rule, or a new skill. Use when the user asks to capture, record, or remember a decision, a convention, or a lesson, or to distill what recent work taught. Scores each candidate and confirms before writing. Not for personal or AI preferences, routine edits, or anything already captured.
+argument-hint: gather | assess | write | sync
 ---
 
 # Learn

diff --git a/plugins/aidd-context/skills/11-explore/SKILL.md b/plugins/aidd-context/skills/11-explore/SKILL.md
@@ -1,6 +1,7 @@
 ---
 name: 11-explore
 description: Explore the current project across its tooling, context, and codebase. Use to survey what is installed and set up, see what is available, or find which installed skill, agent, or rule fits a goal. Not for the next step to take (onboard does that) or running an item (this skill only points).
+argument-hint: survey | drill
 ---
 
 # Explore

diff --git a/plugins/aidd-context/skills/12-cook/SKILL.md b/plugins/aidd-context/skills/12-cook/SKILL.md
@@ -1,6 +1,7 @@
 ---
 name: 12-cook
 description: Manage the project's recipes/ how-to sheets: list them as a table, or create and update one from the canonical template. Use for "list recipes", "new recipe", "update a recipe", "cook a recipe".
+argument-hint: list | upsert
 ---
 
 # Cook

diff --git a/plugins/aidd-dev/CATALOG.md b/plugins/aidd-dev/CATALOG.md
@@ -53,18 +53,18 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai
 
 #### `skills/01-plan`
 
-| Group | File | Description | Argument Hint |
-|-------|------|---|---|
-| `actions` | [01-plan.md](skills/01-plan/actions/01-plan.md) | - | - |
-| `actions` | [02-components-behavior.md](skills/01-plan/actions/02-components-behavior.md) | - | - |
-| `actions` | [03-image-extract-details.md](skills/01-plan/actions/03-image-extract-details.md) | - | - |
-| `assets` | [master-plan-template.md](skills/01-plan/assets/master-plan-template.md) | `Parent plan template orchestrating multiple child plans with validation gates` | - |
-| `assets` | [plan-template.md](skills/01-plan/assets/plan-template.md) | `Living implementation plan - frozen objective, phases, and acceptance criteria.` | - |
-| `assets` | [tech-choice-template.md](skills/01-plan/assets/tech-choice-template.md) | `Technology selection and comparison template` | - |
-| `-` | [README.md](skills/01-plan/README.md) | - | - |
-| `references` | [mermaid-conventions.md](skills/01-plan/references/mermaid-conventions.md) | `Rules for generating valid, high-quality Mermaid diagrams. Apply when creating or reviewing any Mermaid diagram (flowchart, state, ER, sequence, gantt).` | - |
-| `references` | [plan-status.md](skills/01-plan/references/plan-status.md) | `Plan lifecycle status field - values, meaning, who writes each, and when.` | - |
-| `-` | [SKILL.md](skills/01-plan/SKILL.md) | `Generate technical implementation plans, define component behaviors, and extract design details from images.` | - |
+| Group | File | Description |
+|-------|------|---|
+| `actions` | [01-plan.md](skills/01-plan/actions/01-plan.md) | - |
+| `actions` | [02-components-behavior.md](skills/01-plan/actions/02-components-behavior.md) | - |
+| `actions` | [03-image-extract-details.md](skills/01-plan/actions/03-image-extract-details.md) | - |
+| `assets` | [master-plan-template.md](skills/01-plan/assets/master-plan-template.md) | `Parent plan template orchestrating multiple child plans with validation gates` |
+| `assets` | [plan-template.md](skills/01-plan/assets/plan-template.md) | `Living implementation plan - frozen objective, phases, and acceptance criteria.` |
+| `assets` | [tech-choice-template.md](skills/01-plan/assets/tech-choice-template.md) | `Technology selection and comparison template` |
+| `-` | [README.md](skills/01-plan/README.md) | - |
+| `references` | [mermaid-conventions.md](skills/01-plan/references/mermaid-conventions.md) | `Rules for generating valid, high-quality Mermaid diagrams. Apply when creating or reviewing any Mermaid diagram (flowchart, state, ER, sequence, gantt).` |
+| `references` | [plan-status.md](skills/01-plan/references/plan-status.md) | `Plan lifecycle status field - values, meaning, who writes each, and when.` |
+| `-` | [SKILL.md](skills/01-plan/SKILL.md) | `Generate technical implementation plans, define component behaviors, and extract design details from images.` |
 
 #### `skills/02-implement`
 
@@ -88,29 +88,29 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai
 
 #### `skills/04-audit`
 
-| Group | File | Description | Argument Hint |
-|-------|------|---|---|
-| `actions` | [01-code-quality.md](skills/04-audit/actions/01-code-quality.md) | - | - |
-| `actions` | [02-architecture.md](skills/04-audit/actions/02-architecture.md) | - | - |
-| `actions` | [03-security.md](skills/04-audit/actions/03-security.md) | - | - |
-| `actions` | [04-dependencies.md](skills/04-audit/actions/04-dependencies.md) | - | - |
-| `actions` | [05-performance.md](skills/04-audit/actions/05-performance.md) | - | - |
-| `actions` | [06-tests.md](skills/04-audit/actions/06-tests.md) | - | - |
-| `actions` | [07-ui.md](skills/04-audit/actions/07-ui.md) | - | - |
-| `assets` | [audit-template.md](skills/04-audit/assets/audit-template.md) | `Codebase audit report template` | - |
-| `-` | [README.md](skills/04-audit/README.md) | - | - |
-| `-` | [SKILL.md](skills/04-audit/SKILL.md) | `Read-only codebase audit across quality pillars (code-quality, architecture, security, dependencies, performance, tests, ui). Diagnoses and reports findings; never edits code. Use when the user wants to assess, audit, or health-check a codebase or one dimension of it, then hands off to the act-skills (refactor, test, impeccable) to fix. Do NOT use for fixing the findings (hand off to refactor/test/impeccable), per-PR code review (use 05-review), or validating that a feature works (use 03-assert).` | - |
+| Group | File | Description |
+|-------|------|---|
+| `actions` | [01-code-quality.md](skills/04-audit/actions/01-code-quality.md) | - |
+| `actions` | [02-architecture.md](skills/04-audit/actions/02-architecture.md) | - |
+| `actions` | [03-security.md](skills/04-audit/actions/03-security.md) | - |
+| `actions` | [04-dependencies.md](skills/04-audit/actions/04-dependencies.md) | - |
+| `actions` | [05-performance.md](skills/04-audit/actions/05-performance.md) | - |
+| `actions` | [06-tests.md](skills/04-audit/actions/06-tests.md) | - |
+| `actions` | [07-ui.md](skills/04-audit/actions/07-ui.md) | - |
+| `assets` | [audit-template.md](skills/04-audit/assets/audit-template.md) | `Codebase audit report template` |
+| `-` | [README.md](skills/04-audit/README.md) | - |
+| `-` | [SKILL.md](skills/04-audit/SKILL.md) | `Read-only codebase audit across quality pillars (code-quality, architecture, security, dependencies, performance, tests, ui). Diagnoses and reports findings; never edits code. Use when the user wants to assess, audit, or health-check a codebase or one dimension of it, then hands off to the act-skills (refactor, test, impeccable) to fix. Do NOT use for fixing the findings (hand off to refactor/test/impeccable), per-PR code review (use 05-review), or validating that a feature works (use 03-assert).` |
 
 #### `skills/05-review`
 
-| Group | File | Description | Argument Hint |
-|-------|------|---|---|
-| `actions` | [01-review-code.md](skills/05-review/actions/01-review-code.md) | - | - |
-| `actions` | [02-review-functional.md](skills/05-review/actions/02-review-functional.md) | - | - |
-| `assets` | [review-code-template.md](skills/05-review/assets/review-code-template.md) | `Code review report template for a diff` | - |
-| `assets` | [review-functional-template.md](skills/05-review/assets/review-functional-template.md) | `Functional review report template for a diff against a plan` | - |
-| `-` | [README.md](skills/05-review/README.md) | - | - |
-| `-` | [SKILL.md](skills/05-review/SKILL.md) | `Read-only review of a diff (a PR or working changes) - code quality against project rules, and feature behavior against the plan's acceptance criteria. Surfaces findings with a verdict; never patches. Use to review changes in progress. Do NOT use for a whole-codebase health check (use 04-audit), fixing the findings (hand off to 07-refactor / 02-implement / 08-debug), or validating a feature runs (use 03-assert).` | - |
+| Group | File | Description |
+|-------|------|---|
+| `actions` | [01-review-code.md](skills/05-review/actions/01-review-code.md) | - |
+| `actions` | [02-review-functional.md](skills/05-review/actions/02-review-functional.md) | - |
+| `assets` | [review-code-template.md](skills/05-review/assets/review-code-template.md) | `Code review report template for a diff` |
+| `assets` | [review-functional-template.md](skills/05-review/assets/review-functional-template.md) | `Functional review report template for a diff against a plan` |
+| `-` | [README.md](skills/05-review/README.md) | - |
+| `-` | [SKILL.md](skills/05-review/SKILL.md) | `Read-only review of a diff (a PR or working changes) - code quality against project rules, and feature behavior against the plan's acceptance criteria. Surfaces findings with a verdict; never patches. Use to review changes in progress. Do NOT use for a whole-codebase health check (use 04-audit), fixing the findings (hand off to 07-refactor / 02-implement / 08-debug), or validating a feature runs (use 03-assert).` |
 
 #### `skills/06-test`
 
@@ -146,14 +146,14 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai
 
 #### `skills/09-for-sure`
 
-| Group | File | Description | Argument Hint |
-|-------|------|---|---|
-| `actions` | [01-init-tracking.md](skills/09-for-sure/actions/01-init-tracking.md) | - | - |
-| `actions` | [02-auto-accept.md](skills/09-for-sure/actions/02-auto-accept.md) | - | - |
-| `actions` | [03-autonomous-loop.md](skills/09-for-sure/actions/03-autonomous-loop.md) | - | - |
-| `assets` | [plan-template.md](skills/09-for-sure/assets/plan-template.md) | `For Sure autonomous-loop tracking file. Extends the 01-plan format with `success_condition` and `iteration` (For-Sure-only), which the loop runs and increments.` | - |
-| `-` | [README.md](skills/09-for-sure/README.md) | - | - |
-| `-` | [SKILL.md](skills/09-for-sure/SKILL.md) | `Iterative agent loop that tracks attempts and retries until a success condition is met. Use when the user says "for sure", "make sure", "keep trying until", "loop until done", "don't stop until", or needs guaranteed completion of a task with explicit success criteria.` | - |
+| Group | File | Description |
+|-------|------|---|
+| `actions` | [01-init-tracking.md](skills/09-for-sure/actions/01-init-tracking.md) | - |
+| `actions` | [02-auto-accept.md](skills/09-for-sure/actions/02-auto-accept.md) | - |
+| `actions` | [03-autonomous-loop.md](skills/09-for-sure/actions/03-autonomous-loop.md) | - |
+| `assets` | [plan-template.md](skills/09-for-sure/assets/plan-template.md) | `For Sure autonomous-loop tracking file. Extends the 01-plan format with `success_condition` and `iteration` (For-Sure-only), which the loop runs and increments.` |
+| `-` | [README.md](skills/09-for-sure/README.md) | - |
+| `-` | [SKILL.md](skills/09-for-sure/SKILL.md) | `Iterative agent loop that tracks attempts and retries until a success condition is met. Use when the user says "for sure", "make sure", "keep trying until", "loop until done", "don't stop until", or needs guaranteed completion of a task with explicit success criteria.` |
 
 #### `skills/10-todo`