fix(install): map APM prompt 'input' to Claude 'arguments' front-matter

CHANGELOG.md

@@ -7,6 +7,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 
 ## [Unreleased]
+### Added
+
+- Slash commands installed from APM packages now surface argument hints in Claude Code -- `apm install` automatically maps prompt `input:` to Claude's `arguments:` front-matter, rewrites `${input:name}` references to `$name`, and auto-generates `argument-hint`. Argument names are validated against an allowlist to prevent YAML injection from third-party packages, and the mapping is reported at install time. (#1039)
 
 ## [0.11.0] - 2026-04-29
 ### Added

docs/src/content/docs/guides/prompts.md

@@ -99,6 +99,49 @@ Reference script inputs using the `${input:name}` syntax:
 - Start time: ${input:start_time}
 ```
 
+### Input formats
+
+The `input:` frontmatter key accepts several formats:
+
+```yaml
+# Simple list (most common)
+input:
+  - service_name
+  - environment
+
+# Object list with descriptions
+input:
+  - service_name: "Name of the service to analyze"
+  - environment: "Target environment (prod, staging)"
+
+# Bare dictionary
+input:
+  service_name: "Name of the service"
+  environment: "Target environment"
+
+# Single string (one parameter)
+input: service_name
+```
+
+### Target-specific mapping
+
+When APM installs a prompt as a Claude Code slash command, it maps `input:` to Claude's native `arguments:` frontmatter. The `${input:name}` references in the prompt body are converted to `$name` placeholders, and an `argument-hint` is auto-generated if one is not already set.
+
+```yaml
+# APM prompt frontmatter
+input:
+  - feature_name
+  - priority
+
+# Becomes Claude command frontmatter
+arguments:
+  - feature_name
+  - priority
+argument-hint: <feature_name> <priority>
+```
+
+This mapping is automatic during `apm install` -- no extra configuration is needed. If you set an explicit `argument-hint:` in the prompt frontmatter, APM preserves it instead of generating one.
+
 ## MCP servers in prompts
 
 Prompts can declare MCP server dependencies in their frontmatter under the `mcp:` key (see the deployment-health-check example below). To add an MCP server to your project, see the [MCP Servers guide](../mcp-servers/).

docs/src/content/docs/integrations/ide-tool-integration.md

@@ -272,7 +272,37 @@ apm install microsoft/apm-sample-package
 **How it works:**
 1. `apm install` detects `.prompt.md` files in the package
 2. Converts each to Claude command format in `.claude/commands/`
-3. `apm uninstall` automatically removes the package's commands
+3. Maps APM `input:` frontmatter to Claude `arguments:` frontmatter
+4. Converts `${input:name}` references to `$name` placeholders
+5. Auto-generates `argument-hint` from input names (unless one is already set)
+6. `apm uninstall` automatically removes the package's commands
+
+**Input-to-arguments mapping example:**
+
+```yaml
+# APM prompt (.prompt.md)
+---
+description: Review a feature
+input:
+  - feature_name
+  - priority
+---
+Review ${input:feature_name} with priority ${input:priority}.
+```
+
+Becomes:
+
+```yaml
+# Claude command (.claude/commands/review.md)
+---
+description: Review a feature
+arguments:
+  - feature_name
+  - priority
+argument-hint: <feature_name> <priority>
+---
+Review $feature_name with priority $priority.
+```
 
 ### Automatic Skills Integration
 

docs/src/content/docs/reference/cli-commands.md

@@ -132,6 +132,18 @@ See [Dependencies: Transport selection](../../guides/dependencies/#transport-sel
 - Each `http://` dependency is warned at install time before any fetch begins
 - Transitive `http://` dependencies are allowed automatically when they use the same host as a direct insecure dependency you approved with `--allow-insecure`; other transitive hosts require `--allow-insecure-host HOSTNAME`
 
+**Claude Code: prompt `input:` -> slash command `arguments:`:**
+
+When installing into `.claude/commands/`, prompt files with an `input:` front-matter key are transformed so Claude Code can surface typed argument hints in the slash-command picker:
+
+- `input:` is mapped to Claude's `arguments:` front-matter (preserving order).
+- An `argument-hint:` is auto-generated as `<name1> <name2> ...` unless the prompt already sets one explicitly.
+- `${input:name}` references in the body are rewritten to Claude-style `$name` placeholders (double-brace `${{input:name}}` is also accepted).
+- Argument names are restricted to `^[A-Za-z][\w-]{0,63}$`; names containing YAML-significant characters are rejected with a warning and dropped from the output.
+- A short install-time message lists the mapped arguments per file so the transformation is visible without `--verbose`.
+
+This transformation only applies to the `claude` target. Other targets receive the prompt content unchanged.
+
 **Local `.apm/` Content Deployment:**
 
 After integrating dependencies, `apm install` deploys primitives from the project's own `.apm/` directory (instructions, prompts, agents, skills, hooks, commands) to target directories (`.github/`, `.claude/`, `.cursor/`, etc.). Local content takes priority over dependencies on collision. Deployed files are tracked in the lockfile for cleanup on subsequent installs. This works even with zero dependencies -- just `apm.yml` and `.apm/` content is enough.

packages/apm-guide/.apm/skills/apm-usage/package-authoring.md

@@ -122,19 +122,23 @@ applyTo: "**/*"
 
 ### 4. Prompt / Agent Workflow (`*.prompt.md`)
 
-Executable workflows with parameters.
+Executable workflows with parameters. Use the `input:` key to declare
+parameters, and `${input:name}` to reference them in the prompt body.
 
 ```yaml
 ---
 description: "Code review workflow"
-model: "gpt-4"
-parameters:
-  - name: pr_url
-    description: "GitHub PR URL"
-    required: true
+input:
+  - pr_url
+  - focus_areas
 ---
+Review ${input:pr_url} focusing on ${input:focus_areas}.
 ```
 
+When installed as a Claude Code slash command, APM maps `input:` to
+Claude's `arguments:` frontmatter and converts `${input:name}` to `$name`
+placeholders. An `argument-hint` is auto-generated unless one is already set.
+
 ### 5. Agent (`*.agent.md`)
 
 Agent persona and behavior definition.