Support parameterized skills with argument substitution

Skills invoked as slash commands now substitute $ARGS/$ARGUMENTS
and positional $1/$2 placeholders directly into the skill body,
e.g. `/review-pr https://github.com/org/repo/pull/123`.

Also supports legacy $ARGn placeholders for backwards compatibility.

Closes #384

🤖 Generated with [eca](https://eca.dev)

Co-Authored-By: eca <git@eca.dev>

Author: ericdallo

CHANGELOG.md

@@ -4,6 +4,7 @@
 
 - Improve summary of filesystem and shell functions making cleaner.
 - Fix `move_file` not working for renaming.
+- Support parameterized skills via slash commands with `$ARGS`/`$ARGUMENTS`/`$1`/`$2` substitution, e.g. `/review-pr URL`. #384
 
 ## 0.121.1
 

docs/config/commands.md

@@ -7,7 +7,11 @@ description: "Configure ECA commands: built-in slash commands like /init and /co
 ![](../images/features/commands.png)
 
 You can configure custom command prompts for project, global or via `commands` config pointing to the path of the commands.
-Prompts can use variables like `$ARGUMENTS`, `$ARG1`, `ARG2`, to replace in the prompt during command call.
+Prompts can use variables like `$ARGUMENTS`, `$1`, `$2`, to replace in the prompt during command call.
+
+!!! tip "Skills support arguments too"
+
+    [Skills](./skills.md#parameterized-skills) also support the same variable substitution when invoked as slash commands, e.g. `/review-pr URL`.
 
 You can configure in multiple different ways:
 
@@ -16,7 +20,7 @@ You can configure in multiple different ways:
     A `.eca/commands` folder from the workspace root containing `.md` files with the custom prompt.
 
     ```markdown title=".eca/commands/check-performance.md"
-    Check for performance issues in $ARG1 and optimize if needed.
+    Check for performance issues in $1 and optimize if needed.
     ```
 
     ECA will make available a `/check-performance` command after creating that file.
@@ -26,7 +30,7 @@ You can configure in multiple different ways:
     A `$XDG_CONFIG_HOME/eca/commands` or `~/.config/eca/commands` folder containing `.md` files with the custom command prompt.
 
     ```markdown title="~/.config/eca/commands/check-performance.md"
-    Check for performance issues in $ARG1 and optimize if needed.
+    Check for performance issues in $1 and optimize if needed.
     ```
 
     ECA will make available a `/check-performance` command after creating that file.

docs/config/skills.md

@@ -75,4 +75,28 @@ Check the examples:
     }
     ```
 
+## Parameterized skills
+
+Skills can receive arguments when invoked as slash commands, using the same variable substitution as [custom commands](./commands.md): `$ARGS`, `$ARGUMENTS`, and positional `$1`, `$2`, etc.
+
+When arguments are provided, ECA substitutes them directly into the skill body instead of asking the LLM to load the skill via `eca__skill`.
+
+```markdown title="~/.config/eca/skills/review-pr/SKILL.md"
+---
+name: review-pr
+description: Review a pull request given its URL
+---
+
+Review the following pull request: $ARGS
+Focus on code quality, correctness, and test coverage.
+```
+
+Then invoke it with:
+
+```
+/review-pr https://github.com/org/repo/pull/123
+```
+
+ECA will substitute `$ARGS` with the URL and send the full skill body as the prompt.
+
 You can have more directories and contents like `scripts/`, `references/`, `assets/` for a skill making it really powerful, check [the spec](https://agentskills.io/specification#optional-directories) for more details.

src/eca/features/commands.clj

@@ -180,17 +180,22 @@
             skills-cmds
             custom-cmds)))
 
+(defn ^:private substitute-args [content args]
+  (let [args-joined (string/join " " args)
+        content-with-args (-> content
+                              (string/replace "$ARGS" args-joined)
+                              (string/replace "$ARGUMENTS" args-joined))]
+    (reduce (fn [c [i arg]]
+              (-> c
+                  (string/replace (str "$ARG" (inc i)) arg)
+                  (string/replace (str "$" (inc i)) arg)))
+            content-with-args
+            (map-indexed vector args))))
+
 (defn ^:private get-custom-command [command args custom-cmds]
   (when-let [raw-content (:content (first (filter #(= command (:name %))
                                                   custom-cmds)))]
-    (let [args-joined (string/join " " args)
-          content-with-args (-> raw-content
-                                (string/replace "$ARGS" args-joined)
-                                (string/replace "$ARGUMENTS" args-joined))]
-      (reduce (fn [content [i arg]]
-                (string/replace content (str "$ARG" (inc i)) arg))
-              content-with-args
-              (map-indexed vector args)))))
+    (substitute-args raw-content args)))
 
 (defn ^:private format-tool-permissions [{:keys [toolCall]}]
   (when-let [approval (:approval toolCall)]
@@ -530,6 +535,8 @@
          :prompt custom-command-prompt}
         (if-let [skill (first (filter #(= command (:name %)) skills))]
           {:type :send-prompt
-           :prompt (str "Load skill: " (:name skill))}
+           :prompt (if (seq args)
+                    (substitute-args (:body skill) args)
+                    (str "Load skill: " (:name skill)))}
           {:type :text
            :text (str "Unknown command: " command)})))))

test/eca/features/commands_test.clj

@@ -31,3 +31,36 @@
     (let [custom [{:name "test" :content "Process $ARGUMENTS here"}]]
       (is (= "Process one two here"
              (#'f.commands/get-custom-command "test" ["one" "two"] custom))))))
+
+(deftest substitute-args-test
+  (testing "replaces $ARGS with all args joined"
+    (is (= "Review https://github.com/org/repo/pull/1"
+           (#'f.commands/substitute-args "Review $ARGS" ["https://github.com/org/repo/pull/1"]))))
+
+  (testing "replaces $ARGUMENTS with all args joined"
+    (is (= "Review https://github.com/org/repo/pull/1"
+           (#'f.commands/substitute-args "Review $ARGUMENTS" ["https://github.com/org/repo/pull/1"]))))
+
+  (testing "replaces positional $ARGn placeholders"
+    (is (= "First:a Second:b"
+           (#'f.commands/substitute-args "First:$ARG1 Second:$ARG2" ["a" "b"]))))
+
+  (testing "unmatched positional placeholders remain"
+    (is (= "A:x B:$ARG2"
+           (#'f.commands/substitute-args "A:$ARG1 B:$ARG2" ["x"]))))
+
+  (testing "returns content as-is when no placeholders"
+    (is (= "No placeholders here"
+           (#'f.commands/substitute-args "No placeholders here" ["ignored"]))))
+
+  (testing "works with empty args"
+    (is (= "Hello  world"
+           (#'f.commands/substitute-args "Hello $ARGS world" []))))
+
+  (testing "replaces Claude Code compatible $n positional placeholders"
+    (is (= "First:a Second:b"
+           (#'f.commands/substitute-args "First:$1 Second:$2" ["a" "b"]))))
+
+  (testing "replaces both $ARGn and $n placeholders"
+    (is (= "A:x B:x"
+           (#'f.commands/substitute-args "A:$ARG1 B:$1" ["x"])))))