From ecd82994e7b0acd08f721350b97a578f4e2f8bea Mon Sep 17 00:00:00 2001 From: alexsoyes Date: Thu, 18 Jun 2026 07:39:47 +0200 Subject: [PATCH] feat(skills): sync argument hints --- lefthook.yml | 11 +- .../aidd-context/skills/00-onboard/SKILL.md | 1 + .../aidd-context/skills/01-bootstrap/SKILL.md | 1 + .../skills/02-project-memory/SKILL.md | 1 + .../skills/04-skill-generate/SKILL.md | 1 + .../actions/03-draft-skill.md | 4 +- .../actions/04-write-actions.md | 6 +- .../assets/skill-template.md | 1 + .../references/skill-authoring.md | 1 + .../skills/05-rule-generate/SKILL.md | 1 + .../skills/06-agent-generate/SKILL.md | 1 + .../skills/07-command-generate/SKILL.md | 1 + .../skills/08-hook-generate/SKILL.md | 1 + plugins/aidd-context/skills/10-learn/SKILL.md | 1 + .../aidd-context/skills/11-explore/SKILL.md | 1 + plugins/aidd-context/skills/12-cook/SKILL.md | 1 + plugins/aidd-dev/CATALOG.md | 80 ++++++------ plugins/aidd-dev/skills/00-sdlc/SKILL.md | 1 + plugins/aidd-dev/skills/01-plan/SKILL.md | 1 + plugins/aidd-dev/skills/03-assert/SKILL.md | 1 + plugins/aidd-dev/skills/04-audit/SKILL.md | 1 + plugins/aidd-dev/skills/05-review/SKILL.md | 1 + plugins/aidd-dev/skills/06-test/SKILL.md | 1 + plugins/aidd-dev/skills/07-refactor/SKILL.md | 1 + plugins/aidd-dev/skills/08-debug/SKILL.md | 1 + plugins/aidd-dev/skills/09-for-sure/SKILL.md | 1 + .../skills/00-async-dev/SKILL.md | 1 + plugins/aidd-pm/CATALOG.md | 26 ++-- plugins/aidd-pm/skills/04-spec/SKILL.md | 1 + .../aidd-refine/skills/01-brainstorm/SKILL.md | 1 + .../aidd-refine/skills/03-condense/SKILL.md | 1 + .../skills/04-shadow-areas/SKILL.md | 1 + .../aidd-refine/skills/05-fact-check/SKILL.md | 1 + plugins/aidd-vcs/CATALOG.md | 56 ++++----- scripts/summarize-markdown.js | 11 +- scripts/sync-skill-argument-hints.mjs | 119 ++++++++++++++++++ 36 files changed, 253 insertions(+), 88 deletions(-) create mode 100755 scripts/sync-skill-argument-hints.mjs diff --git a/lefthook.yml b/lefthook.yml index 1277fc94..0eda5ab4 100644 --- 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 index c873ebca..38f9202c 100644 --- 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 index d5f8efa2..a2ce5d0c 100644 --- 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 index 28af6162..de12e39c 100644 --- 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 index 34aa875d..fbe94307 100644 --- 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 index 5b29b1ac..db3d136a 100644 --- 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 index 26862bfa..4dfdd597 100644 --- 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 `//actions/-< 1. **Resolve.** Host mode: for each confirmed tool, resolve the skills root from `@../references/tool-paths.md`. Plugin source: use `plugins//skills//`. 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 `@`. Never "read X then apply". -4. **Validate.** Run the write-target validation (`@../references/tool-paths.md`). +4. **Compose.** Include any template or reference via `@`. 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 index 3af4e1bd..4d161330 100644 --- 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: description: . Use when . , use " 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: # omit when the skill has only one action --- # 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 index c9582fbd..746aabc5 100644 --- 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 index 696b9f74..67e51723 100644 --- 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 index bbebf4ee..ed658a19 100644 --- 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 index f0d40d02..6f349a3d 100644 --- 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 index 07769648..ac77e824 100644 --- 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 index 2abbab67..8ee8014b 100644 --- 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 index d7558dd2..34b9338b 100644 --- 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 index e0b61a88..2cd52dbc 100644 --- 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 index ec41b86e..32595145 100644 --- 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` diff --git a/plugins/aidd-dev/skills/00-sdlc/SKILL.md b/plugins/aidd-dev/skills/00-sdlc/SKILL.md index c6c4162a..6f650312 100644 --- a/plugins/aidd-dev/skills/00-sdlc/SKILL.md +++ b/plugins/aidd-dev/skills/00-sdlc/SKILL.md @@ -1,6 +1,7 @@ --- name: 00-sdlc description: Pure orchestrator for the full AIDD development flow. Use when a human (or Gardener) needs to take a free-form request from idea to shipped code, end-to-end. Coordinates spec generation, planning, implementation, review, and shipping by composing other skills and agents. Supports two modes - `auto` (default, no human interaction) and `interactive` (pauses for human confirmation at key gates). Holds no business logic of its own; every step is delegated. +argument-hint: spec | plan | implement | review | ship --- # Skill: sdlc diff --git a/plugins/aidd-dev/skills/01-plan/SKILL.md b/plugins/aidd-dev/skills/01-plan/SKILL.md index 9fd3e2d9..097dcbf4 100644 --- a/plugins/aidd-dev/skills/01-plan/SKILL.md +++ b/plugins/aidd-dev/skills/01-plan/SKILL.md @@ -1,6 +1,7 @@ --- name: 01-plan description: Generate technical implementation plans, define component behaviors, and extract design details from images. +argument-hint: plan | components-behavior | image-extract-details model: opus context: fork agent: planner diff --git a/plugins/aidd-dev/skills/03-assert/SKILL.md b/plugins/aidd-dev/skills/03-assert/SKILL.md index 32646380..6594114d 100644 --- a/plugins/aidd-dev/skills/03-assert/SKILL.md +++ b/plugins/aidd-dev/skills/03-assert/SKILL.md @@ -1,6 +1,7 @@ --- name: 03-assert description: Assert features work as intended - general assertions, architecture conformance, and frontend UI validation. +argument-hint: assert | assert-architecture | assert-frontend model: sonnet --- diff --git a/plugins/aidd-dev/skills/04-audit/SKILL.md b/plugins/aidd-dev/skills/04-audit/SKILL.md index d4f98968..714f7d2d 100644 --- a/plugins/aidd-dev/skills/04-audit/SKILL.md +++ b/plugins/aidd-dev/skills/04-audit/SKILL.md @@ -1,6 +1,7 @@ --- name: 04-audit description: 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). +argument-hint: code-quality | architecture | security | dependencies | performance | tests | ui model: opus --- diff --git a/plugins/aidd-dev/skills/05-review/SKILL.md b/plugins/aidd-dev/skills/05-review/SKILL.md index 5de8c5f9..b5d2fdbc 100644 --- a/plugins/aidd-dev/skills/05-review/SKILL.md +++ b/plugins/aidd-dev/skills/05-review/SKILL.md @@ -1,6 +1,7 @@ --- name: 05-review description: 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). +argument-hint: review-code | review-functional model: opus context: fork agent: reviewer diff --git a/plugins/aidd-dev/skills/06-test/SKILL.md b/plugins/aidd-dev/skills/06-test/SKILL.md index aa1e8bd8..9f67186d 100644 --- a/plugins/aidd-dev/skills/06-test/SKILL.md +++ b/plugins/aidd-dev/skills/06-test/SKILL.md @@ -1,6 +1,7 @@ --- name: 06-test description: Write and iterate on tests until they pass, and validate user journeys end-to-end in the browser. +argument-hint: test | test-journey model: sonnet --- diff --git a/plugins/aidd-dev/skills/07-refactor/SKILL.md b/plugins/aidd-dev/skills/07-refactor/SKILL.md index a0a88431..52e66b60 100644 --- a/plugins/aidd-dev/skills/07-refactor/SKILL.md +++ b/plugins/aidd-dev/skills/07-refactor/SKILL.md @@ -1,6 +1,7 @@ --- name: 07-refactor description: Improve code without breaking behavior across four axes - cleanup (clean-code + tech debt), performance, security, architecture. Scans and fixes, or fixes the findings of an audit report pushed in by the caller. Use when the user wants to refactor, clean up, optimize, harden, or restructure code. Do NOT use for read-only diagnosis (use 04-audit), adding tests (use 06-test), or UI redesign (use the impeccable skill). +argument-hint: performance | security | cleanup | architecture --- # Skill: refactor diff --git a/plugins/aidd-dev/skills/08-debug/SKILL.md b/plugins/aidd-dev/skills/08-debug/SKILL.md index f809908c..1c5a1f1d 100644 --- a/plugins/aidd-dev/skills/08-debug/SKILL.md +++ b/plugins/aidd-dev/skills/08-debug/SKILL.md @@ -1,6 +1,7 @@ --- name: 08-debug description: Reproduce and fix bugs systematically using test-driven workflow, root cause analysis, and hypothesis validation. +argument-hint: reproduce | debug | reflect-issue model: opus --- diff --git a/plugins/aidd-dev/skills/09-for-sure/SKILL.md b/plugins/aidd-dev/skills/09-for-sure/SKILL.md index f4f5fcac..989821e3 100644 --- a/plugins/aidd-dev/skills/09-for-sure/SKILL.md +++ b/plugins/aidd-dev/skills/09-for-sure/SKILL.md @@ -1,6 +1,7 @@ --- name: 09-for-sure description: 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. +argument-hint: init-tracking | auto-accept | autonomous-loop --- # For Sure diff --git a/plugins/aidd-orchestrator/skills/00-async-dev/SKILL.md b/plugins/aidd-orchestrator/skills/00-async-dev/SKILL.md index c4bf21d5..d045bc2a 100644 --- a/plugins/aidd-orchestrator/skills/00-async-dev/SKILL.md +++ b/plugins/aidd-orchestrator/skills/00-async-dev/SKILL.md @@ -1,6 +1,7 @@ --- name: 00-async-dev description: Single entry point for the async-dev pipeline (setup, run, review). Hybrid router decides which sub-flow to execute from $ARGUMENTS keyword (`setup` / `run` / `review`), trigger source (label `to-implement` / `to-review`, comment `@claude /implement` / `/review`), repo state (workflow + config presence, PR linked to issue), or natural-language intent. Use when the user says "set up async dev", "run async dev on issue #N", "address review on PR #N", "/async-dev", "claude on issues", or when triggered by a webhook with the matching labels or comments. Do NOT use for plain status checks on the async pipeline or for SDLC orchestration unrelated to issue/PR automation. +argument-hint: collect-comments | detect-stop | fix-iteration | finalize | poll-ready | resolve-deps | acquire-lock | check-sdlc | delegate-sdlc | write-audit | detect-context | ask-config | generate-workflow | generate-local-script | write-config | bootstrap-labels | install-user-scope-plugins | configure-remote-secrets | bootstrap-scheduling | commit-and-push | smoke-test --- # Async-dev diff --git a/plugins/aidd-pm/CATALOG.md b/plugins/aidd-pm/CATALOG.md index e2860668..5da05e2f 100644 --- a/plugins/aidd-pm/CATALOG.md +++ b/plugins/aidd-pm/CATALOG.md @@ -33,22 +33,22 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai #### `skills/02-user-stories-create` -| Group | File | Description | Argument Hint | -|-------|------|---|---| -| `actions` | [01-create-user-stories.md](skills/02-user-stories-create/actions/01-create-user-stories.md) | - | - | -| `assets` | [user-story-template.md](skills/02-user-stories-create/assets/user-story-template.md) | `Template for defining user stories with estimation and acceptance criteria` | - | -| `-` | [README.md](skills/02-user-stories-create/README.md) | - | - | -| `-` | [SKILL.md](skills/02-user-stories-create/SKILL.md) | `Generate INVEST-compliant user stories from a feature description. Use when the user says "user stories", "create user stories", "write user stories for X", "INVEST stories", "draft stories", or invokes `/user-stories-create`. Do NOT use for writing code, drafting a full PRD, refining a single existing story, or copying ready text into a tracker.` | - | +| Group | File | Description | +|-------|------|---| +| `actions` | [01-create-user-stories.md](skills/02-user-stories-create/actions/01-create-user-stories.md) | - | +| `assets` | [user-story-template.md](skills/02-user-stories-create/assets/user-story-template.md) | `Template for defining user stories with estimation and acceptance criteria` | +| `-` | [README.md](skills/02-user-stories-create/README.md) | - | +| `-` | [SKILL.md](skills/02-user-stories-create/SKILL.md) | `Generate INVEST-compliant user stories from a feature description. Use when the user says "user stories", "create user stories", "write user stories for X", "INVEST stories", "draft stories", or invokes `/user-stories-create`. Do NOT use for writing code, drafting a full PRD, refining a single existing story, or copying ready text into a tracker.` | #### `skills/03-prd` -| Group | File | Description | Argument Hint | -|-------|------|---|---| -| `actions` | [01-prd.md](skills/03-prd/actions/01-prd.md) | - | - | -| `assets` | [prd-template.md](skills/03-prd/assets/prd-template.md) | `Product Requirements Document template (15 sections)` | - | -| `assets` | [task-template.md](skills/03-prd/assets/task-template.md) | `Task tracking system to ensure all tasks are categorized and addressed` | - | -| `-` | [README.md](skills/03-prd/README.md) | - | - | -| `-` | [SKILL.md](skills/03-prd/SKILL.md) | `Generate a structured Product Requirements Document from a feature description or user stories, validated with the user before save. Use when the user says "prd", "draft prd", "write prd", "product requirements for X", "generate a prd", or invokes `/prd`. Do NOT use for writing user stories, drafting a technical implementation plan, or writing source code.` | - | +| Group | File | Description | +|-------|------|---| +| `actions` | [01-prd.md](skills/03-prd/actions/01-prd.md) | - | +| `assets` | [prd-template.md](skills/03-prd/assets/prd-template.md) | `Product Requirements Document template (15 sections)` | +| `assets` | [task-template.md](skills/03-prd/assets/task-template.md) | `Task tracking system to ensure all tasks are categorized and addressed` | +| `-` | [README.md](skills/03-prd/README.md) | - | +| `-` | [SKILL.md](skills/03-prd/SKILL.md) | `Generate a structured Product Requirements Document from a feature description or user stories, validated with the user before save. Use when the user says "prd", "draft prd", "write prd", "product requirements for X", "generate a prd", or invokes `/prd`. Do NOT use for writing user stories, drafting a technical implementation plan, or writing source code.` | #### `skills/04-spec` diff --git a/plugins/aidd-pm/skills/04-spec/SKILL.md b/plugins/aidd-pm/skills/04-spec/SKILL.md index b72ce125..a356c7b3 100644 --- a/plugins/aidd-pm/skills/04-spec/SKILL.md +++ b/plugins/aidd-pm/skills/04-spec/SKILL.md @@ -1,6 +1,7 @@ --- name: 04-spec description: Generate or refine a project spec from a free-form human request, an existing PRD, or reviewer findings. Use when the user says "draft spec", "spec for X", "refine the spec", "generate spec from prd", "/spec", or when an orchestrator needs a normalized contract before planning. Do NOT use for writing source code, drafting a full PRD, or modifying a validated and locked spec. +argument-hint: build | refine --- # Spec diff --git a/plugins/aidd-refine/skills/01-brainstorm/SKILL.md b/plugins/aidd-refine/skills/01-brainstorm/SKILL.md index 994506a3..d43d2f54 100644 --- a/plugins/aidd-refine/skills/01-brainstorm/SKILL.md +++ b/plugins/aidd-refine/skills/01-brainstorm/SKILL.md @@ -1,6 +1,7 @@ --- name: 01-brainstorm description: Interactive brainstorming session to clarify and refine requests through iterative questioning. Use when user mentions unclear requirements, vague ideas, or needs clarification on features. Do NOT use for clear technical specs, implementation details, or when requirements are already well-defined. +argument-hint: capture-request | ask-probing-questions | integrate-answers | refine-and-validate | confirm-approval --- # Brainstorm diff --git a/plugins/aidd-refine/skills/03-condense/SKILL.md b/plugins/aidd-refine/skills/03-condense/SKILL.md index 67533545..70173e0e 100644 --- a/plugins/aidd-refine/skills/03-condense/SKILL.md +++ b/plugins/aidd-refine/skills/03-condense/SKILL.md @@ -1,6 +1,7 @@ --- name: 03-condense description: Toggle terse output mode with intensity levels (lite, full, ultra) so prose drops articles, filler, and pleasantries while code, quoted errors, and security warnings stay verbatim. Also reports real token usage and estimated savings under condense mode for the current session. Use when the user says "condense", "condense output", "be more concise", "shorter answers", "tighten output", "/condense", "/condense full", "/condense ultra", "stop condense", "normal mode", "/condense-stats", "how much have we saved", or "token savings". Do NOT use for editing existing prose, summarizing a long document, or compressing source code (only output style is affected, not content). +argument-hint: condense | stats --- # Condense diff --git a/plugins/aidd-refine/skills/04-shadow-areas/SKILL.md b/plugins/aidd-refine/skills/04-shadow-areas/SKILL.md index 3df59f34..a6c7fdf4 100644 --- a/plugins/aidd-refine/skills/04-shadow-areas/SKILL.md +++ b/plugins/aidd-refine/skills/04-shadow-areas/SKILL.md @@ -1,6 +1,7 @@ --- name: 04-shadow-areas description: Analytical scan of a markdown artifact (idea, user-stories, PRD, spec) to surface blind spots - unstated assumption, missing actor, missing failure mode, ambiguous term, missing acceptance criterion, missing edge case, and missing dependency - emitting a structured shadow report grouped by category and sorted by severity. Use when the user says "find blind spots in this spec", "what's missing in this PRD", "shadow report", "shadow analysis", "scan for gaps", "find what's missing", "spot blind spots", "review for gaps", or asks for an analytical gap scan of a written artifact. Do NOT use for interactive clarification through iterative Q&A (use aidd-refine:01-brainstorm for that), implementing features, writing tests, or reviewing code style. +argument-hint: detect | render-report | diff --- # Shadow Areas diff --git a/plugins/aidd-refine/skills/05-fact-check/SKILL.md b/plugins/aidd-refine/skills/05-fact-check/SKILL.md index af670ba6..b09fae28 100644 --- a/plugins/aidd-refine/skills/05-fact-check/SKILL.md +++ b/plugins/aidd-refine/skills/05-fact-check/SKILL.md @@ -1,6 +1,7 @@ --- name: 05-fact-check description: Verify factual claims in a piece of text against authoritative sources and rewrite it with footnote citations, hedging any claim that cannot be confirmed. Runs a cheapest-first verification cascade (project memory and docs, then codebase inspection, then web lookup) and reports both sources when they disagree. Use when the user says "fact-check this", "verify that claim", "are you sure about that", "is that actually true", "cite your sources", "where did you get that fact", "did you make that up", "double-check the version you gave me", "vérifie cette information", or "es-tu sûr de ça". Do NOT use to auto-guard the AI's own output (this skill only fires on an explicit request), to judge code logic correctness, or to clarify vague requirements through iterative Q&A - use `aidd-refine:01-brainstorm` for that. +argument-hint: identify-claims | verify | report --- # Fact-check diff --git a/plugins/aidd-vcs/CATALOG.md b/plugins/aidd-vcs/CATALOG.md index 4cc8de8d..9f9bf6c2 100644 --- a/plugins/aidd-vcs/CATALOG.md +++ b/plugins/aidd-vcs/CATALOG.md @@ -25,41 +25,41 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai #### `skills/01-commit` -| Group | File | Description | Argument Hint | -|-------|------|---|---| -| `actions` | [01-commit.md](skills/01-commit/actions/01-commit.md) | - | - | -| `assets` | [commit-template.md](skills/01-commit/assets/commit-template.md) | `VCS commit message template` | - | -| `-` | [README.md](skills/01-commit/README.md) | - | - | -| `-` | [SKILL.md](skills/01-commit/SKILL.md) | `Create an atomic git commit with conventional message format. Use when the user says "commit", "git commit", "create a commit", "commit my changes", "commit and push", or invokes `/commit`. Do NOT use for amending existing commits, force-pushing, rebasing, opening pull requests, or release tagging.` | - | +| Group | File | Description | +|-------|------|---| +| `actions` | [01-commit.md](skills/01-commit/actions/01-commit.md) | - | +| `assets` | [commit-template.md](skills/01-commit/assets/commit-template.md) | `VCS commit message template` | +| `-` | [README.md](skills/01-commit/README.md) | - | +| `-` | [SKILL.md](skills/01-commit/SKILL.md) | `Create an atomic git commit with conventional message format. Use when the user says "commit", "git commit", "create a commit", "commit my changes", "commit and push", or invokes `/commit`. Do NOT use for amending existing commits, force-pushing, rebasing, opening pull requests, or release tagging.` | #### `skills/02-pull-request` -| Group | File | Description | Argument Hint | -|-------|------|---|---| -| `actions` | [01-pull-request.md](skills/02-pull-request/actions/01-pull-request.md) | - | - | -| `assets` | [branch.md](skills/02-pull-request/assets/branch.md) | `VCS branch naming convention template` | - | -| `assets` | [CONTRIBUTING.md](skills/02-pull-request/assets/CONTRIBUTING.md) | `Project contribution guidelines template` | - | -| `assets` | [pull_request.md](skills/02-pull-request/assets/pull_request.md) | `VCS pull/merge request template` | - | -| `assets` | [README.md](skills/02-pull-request/assets/README.md) | `Project README template` | - | -| `-` | [README.md](skills/02-pull-request/README.md) | - | - | -| `-` | [SKILL.md](skills/02-pull-request/SKILL.md) | `Create a draft pull or merge request from the current branch. Use when the user says "open a pr", "open a pull request", "create a pr", "create a merge request", "open mr", "draft a pr for this branch", or invokes `/pull-request`. Do NOT use for committing changes, pushing a branch directly, tagging releases, merging an existing request, or amending commits.` | - | +| Group | File | Description | +|-------|------|---| +| `actions` | [01-pull-request.md](skills/02-pull-request/actions/01-pull-request.md) | - | +| `assets` | [branch.md](skills/02-pull-request/assets/branch.md) | `VCS branch naming convention template` | +| `assets` | [CONTRIBUTING.md](skills/02-pull-request/assets/CONTRIBUTING.md) | `Project contribution guidelines template` | +| `assets` | [pull_request.md](skills/02-pull-request/assets/pull_request.md) | `VCS pull/merge request template` | +| `assets` | [README.md](skills/02-pull-request/assets/README.md) | `Project README template` | +| `-` | [README.md](skills/02-pull-request/README.md) | - | +| `-` | [SKILL.md](skills/02-pull-request/SKILL.md) | `Create a draft pull or merge request from the current branch. Use when the user says "open a pr", "open a pull request", "create a pr", "create a merge request", "open mr", "draft a pr for this branch", or invokes `/pull-request`. Do NOT use for committing changes, pushing a branch directly, tagging releases, merging an existing request, or amending commits.` | #### `skills/03-release-tag` -| Group | File | Description | Argument Hint | -|-------|------|---|---| -| `actions` | [01-release-tag.md](skills/03-release-tag/actions/01-release-tag.md) | - | - | -| `assets` | [release-template.md](skills/03-release-tag/assets/release-template.md) | `VCS release notes template` | - | -| `-` | [README.md](skills/03-release-tag/README.md) | - | - | -| `-` | [SKILL.md](skills/03-release-tag/SKILL.md) | `Cut a semver release with annotated tag and release notes. Use when the user says "release", "tag", "tag this release", "bump version", "release v1.2.0", "cut a release", or invokes `/release-tag`. Do NOT use for plain commits without a tag, opening pull requests, pushing a branch only, or amending existing tags.` | - | +| Group | File | Description | +|-------|------|---| +| `actions` | [01-release-tag.md](skills/03-release-tag/actions/01-release-tag.md) | - | +| `assets` | [release-template.md](skills/03-release-tag/assets/release-template.md) | `VCS release notes template` | +| `-` | [README.md](skills/03-release-tag/README.md) | - | +| `-` | [SKILL.md](skills/03-release-tag/SKILL.md) | `Cut a semver release with annotated tag and release notes. Use when the user says "release", "tag", "tag this release", "bump version", "release v1.2.0", "cut a release", or invokes `/release-tag`. Do NOT use for plain commits without a tag, opening pull requests, pushing a branch only, or amending existing tags.` | #### `skills/04-issue-create` -| Group | File | Description | Argument Hint | -|-------|------|---|---| -| `actions` | [01-issue-create.md](skills/04-issue-create/actions/01-issue-create.md) | - | - | -| `assets` | [CONTRIBUTING.md](skills/04-issue-create/assets/CONTRIBUTING.md) | `Project contribution guidelines template` | - | -| `assets` | [issue-template.md](skills/04-issue-create/assets/issue-template.md) | `VCS issue/ticket template` | - | -| `-` | [README.md](skills/04-issue-create/README.md) | - | - | -| `-` | [SKILL.md](skills/04-issue-create/SKILL.md) | `Create an issue in the configured ticketing tool. Use when the user says "new issue", "create an issue", "file a bug", "file an issue", "report bug", "open an issue", or invokes `/issue-create`. Do NOT use for committing changes, opening pull requests, tagging releases, or commenting on existing issues.` | - | +| Group | File | Description | +|-------|------|---| +| `actions` | [01-issue-create.md](skills/04-issue-create/actions/01-issue-create.md) | - | +| `assets` | [CONTRIBUTING.md](skills/04-issue-create/assets/CONTRIBUTING.md) | `Project contribution guidelines template` | +| `assets` | [issue-template.md](skills/04-issue-create/assets/issue-template.md) | `VCS issue/ticket template` | +| `-` | [README.md](skills/04-issue-create/README.md) | - | +| `-` | [SKILL.md](skills/04-issue-create/SKILL.md) | `Create an issue in the configured ticketing tool. Use when the user says "new issue", "create an issue", "file a bug", "file an issue", "report bug", "open an issue", or invokes `/issue-create`. Do NOT use for committing changes, opening pull requests, tagging releases, or commenting on existing issues.` | diff --git a/scripts/summarize-markdown.js b/scripts/summarize-markdown.js index e3aa25c9..a589e12b 100755 --- a/scripts/summarize-markdown.js +++ b/scripts/summarize-markdown.js @@ -69,6 +69,8 @@ for (const arg of process.argv) { const fs = require("node:fs"); const path = require("node:path"); +const NON_TABLE_FRONTMATTER_KEYS = new Set(["argument-hint"]); + function parseFrontmatter(content) { const lines = content.split("\n"); @@ -242,6 +244,11 @@ function truncateText(text, maxLength = 50) { return `${text.substring(0, maxLength - 3)}...`; } +function formatFrontmatterValue(value) { + if (!value || value === "N/A") return "-"; + return `\`${value}\``; +} + /** * Group files by their first path component (subfolder) * @param {Array} files - Array of file objects @@ -326,7 +333,7 @@ function generateTable(files, outputFile) { } parsedFiles.push({ file, frontmatter }); for (const key of Object.keys(frontmatter)) { - if (key !== "name") allKeys.add(key); + if (key !== "name" && !NON_TABLE_FRONTMATTER_KEYS.has(key)) allKeys.add(key); } } catch (error) { console.warn( @@ -354,7 +361,7 @@ function generateTable(files, outputFile) { const fileLink = `[${template}](${relativePath})`; const values = extraColumns.map((key) => { const val = frontmatter[key]; - return val && val !== "N/A" ? `\`${val}\`` : "-"; + return formatFrontmatterValue(val); }); rows.push({ group, fileLink, values }); } diff --git a/scripts/sync-skill-argument-hints.mjs b/scripts/sync-skill-argument-hints.mjs new file mode 100755 index 00000000..d4b31bf6 --- /dev/null +++ b/scripts/sync-skill-argument-hints.mjs @@ -0,0 +1,119 @@ +#!/usr/bin/env node +// Keeps SKILL.md frontmatter argument-hint values in sync with action file names. +// Omits the field when a skill has zero or one action. +// Usage: +// node scripts/sync-skill-argument-hints.mjs # rewrite stale files +// node scripts/sync-skill-argument-hints.mjs --check # exit 1 if stale + +import { readdir, readFile, writeFile } from "node:fs/promises"; +import path from "node:path"; + +const ROOT = process.cwd(); +const PLUGINS_DIR = path.join(ROOT, "plugins"); +const CHECK = process.argv.includes("--check"); + +function actionName(file) { + return path.basename(file, path.extname(file)).replace(/^\d+-/, ""); +} + +async function existsDir(dir) { + try { + const entries = await readdir(dir, { withFileTypes: true }); + return entries; + } catch (error) { + if (error.code === "ENOENT") return null; + throw error; + } +} + +async function collectMarkdownFiles(dir) { + const entries = await existsDir(dir); + if (!entries) return []; + + const files = []; + for (const entry of entries) { + const full = path.join(dir, entry.name); + if (entry.isDirectory()) { + files.push(...(await collectMarkdownFiles(full))); + } else if (entry.isFile() && entry.name.endsWith(".md")) { + files.push(full); + } + } + return files.sort((a, b) => a.localeCompare(b)); +} + +async function skillDirs() { + const plugins = await existsDir(PLUGINS_DIR); + if (!plugins) return []; + + const dirs = []; + for (const plugin of plugins) { + if (!plugin.isDirectory()) continue; + const skillsDir = path.join(PLUGINS_DIR, plugin.name, "skills"); + const skills = await existsDir(skillsDir); + if (!skills) continue; + for (const skill of skills) { + if (skill.isDirectory()) dirs.push(path.join(skillsDir, skill.name)); + } + } + return dirs.sort((a, b) => a.localeCompare(b)); +} + +function splitFrontmatter(content) { + if (!content.startsWith("---\n")) return null; + const end = content.indexOf("\n---", 4); + if (end === -1) return null; + return { + frontmatter: content.slice(4, end), + body: content.slice(end), + }; +} + +function syncArgumentHint(content, hint) { + const parts = splitFrontmatter(content); + if (!parts) return content; + + const lines = parts.frontmatter.split("\n"); + const index = lines.findIndex((value) => value.startsWith("argument-hint:")); + if (!hint) { + if (index !== -1) lines.splice(index, 1); + return `---\n${lines.join("\n")}${parts.body}`; + } + + const line = `argument-hint: ${hint}`; + if (index === -1) { + const descriptionIndex = lines.findIndex((value) => value.startsWith("description:")); + const insertAt = descriptionIndex === -1 ? lines.length : descriptionIndex + 1; + lines.splice(insertAt, 0, line); + } else { + lines[index] = line; + } + + return `---\n${lines.join("\n")}${parts.body}`; +} + +const stale = []; +for (const dir of await skillDirs()) { + const skillPath = path.join(dir, "SKILL.md"); + const actionFiles = await collectMarkdownFiles(path.join(dir, "actions")); + const names = [...new Set(actionFiles.map(actionName))]; + const hint = names.length > 1 ? names.join(" | ") : null; + const before = await readFile(skillPath, "utf8"); + const after = syncArgumentHint(before, hint); + if (after !== before) { + const relative = path.relative(ROOT, skillPath); + stale.push(relative); + if (!CHECK) await writeFile(skillPath, after); + } +} + +if (stale.length > 0) { + if (CHECK) { + console.error(`Stale argument-hint frontmatter:\n${stale.join("\n")}`); + console.error("Run: node scripts/sync-skill-argument-hints.mjs"); + process.exit(1); + } + console.log(`Synced argument-hint frontmatter in ${stale.length} SKILL.md file(s).`); +} else { + console.log("All skill argument-hint frontmatter values are current."); +}