rpiv-args

Pass arguments to your skills like a shell command. rpiv-args adds $1, $ARGUMENTS, $@, ${@:N}, and ${@:N:L} placeholders to Pi Agent skills — write /skill:deploy api production and your skill body sees $1 = api, $2 = production. Skills without placeholders are untouched, so installing rpiv-args is safe for any existing skill collection.

Install

pi install npm:@juicesharp/rpiv-args

Or run /rpiv-setup if you have @juicesharp/rpiv-pi installed.

Placeholders

| Placeholder | Replaced with | Example | |---|---|---| | $1, $2, … | Positional argument (1-indexed) | /skill:foo a b c → $1 = a, $2 = b | | $ARGUMENTS | All arguments as a single string | /skill:foo a b c → a b c | | $@ | Same as $ARGUMENTS | /skill:foo a b c → a b c | | ${@:N} | Arguments from position N onward | /skill:foo a b c → ${@:2} = b c | | ${@:N:L} | L arguments starting at position N | /skill:foo a b c d → ${@:2:2} = b c |

Indexing is 1-based — $1 is the first argument, $2 is the second. Out-of-range positions resolve to an empty string. For ${@:N[:L]}, N is clamped to ≥ 1 and out-of-range slices yield an empty string.

Multi-word values use shell-style quoting:

/skill:deploy "staging server" --force

→ $1 = staging server, $2 = --force, $ARGUMENTS = staging server --force

How it works

rpiv-args intercepts the input event (fires before Pi's built-in skill expansion). When a skill body contains at least one placeholder, the extension:

1. Parses arguments using shell-style quoting
2. Substitutes all placeholders in the body
3. Wraps the result in a <skill> block byte-identical to Pi's native format
4. Appends the raw arguments after the block — matches Pi's standard output so any tool that parses <skill> blocks continues to work unchanged

When no placeholders are found in the skill body, the output is byte-identical to Pi's built-in expansion — zero behavioral change.

Writing skills with arguments

$ARGUMENTS vs $1 — which to use

Use $ARGUMENTS (or $@) when the input is freeform text the LLM should interpret naturally:

---
name: fix-issue
description: Fix a GitHub issue by number or description
---

Fix the following issue: $ARGUMENTS

/skill:fix-issue login page crashes on mobile

→ Fix the following issue: login page crashes on mobile

Use $1, $2 only for skills with a fixed, structured invocation pattern:

---
name: migrate-component
description: Migrate a component between frameworks
---

Migrate the $1 component from $2 to $3.
Preserve all existing behavior and tests.

/skill:migrate-component SearchBar React Vue

→ Migrate the SearchBar component from React to Vue.

Why this matters

If a positional skill receives natural language input:

/skill:migrate-component can you migrate the search bar please

→ Migrate the can component from you to migrate. — broken.

The LLM is good at interpreting $ARGUMENTS as a whole, but positional placeholders blindly split on spaces. Use $ARGUMENTS unless your skill has a strict arg structure.

argument-hint frontmatter

Add an argument-hint to document what the skill expects:

---
name: fix-issue
description: Fix a GitHub issue
argument-hint: [issue-number-or-description]
---

---
name: migrate-component
description: Migrate a component between frameworks
argument-hint: [component] [from] [to]
---

rpiv-args ignores this field — substitution is triggered by placeholders in the body, not the hint.

Note: Pi currently surfaces argument-hint in autocomplete for prompt templates (commands/*.md) but not for skills (/skill:<name>). The field is read by Pi but not displayed in the /skill: autocomplete UI at present — treat it as documentation metadata until upstream Pi exposes it.

Full example

---
name: deploy
description: Deploy a service to an environment
argument-hint: [service] [environment]
---

Deploy service $1 to $2.

## Steps
1. Run the test suite for $1
2. Build the Docker image
3. Push to the $2 registry
4. Verify the deployment

/skill:deploy api production

→ The LLM receives:

<skill name="deploy" location="...">
Deploy service api to production.

## Steps
1. Run the test suite for api
2. Build the Docker image
3. Push to the production registry
4. Verify the deployment
</skill>

api production

Note: the raw arguments (api production) are also appended after the </skill> block — this is Pi's standard behavior and is preserved for backward compatibility.

Backward compatibility

• Skills without placeholders → output is byte-identical to Pi's built-in expansion
• Skills with placeholders → body gets substitution, raw args still appended after block
• The argument-hint frontmatter field is read but not enforced in v1

Limitations

| Limitation | Detail | |---|---| | No type validation | $1 expecting a file path receives whatever the user types | | No flag parsing | --env=prod is a single positional token, not a parsed flag | | Literal substitution | Placeholders are replaced even inside code blocks and inline code | | steer()/followUp() paths | session.steer() / session.followUp() bypass the input event (see agent-session.js:861-887); placeholders are not resolved on those paths. Use the primary prompt path for argument-substituted skills. | | No recursive substitution | A $ARGUMENTS value containing $1 is not re-expanded |

License

MIT