Example Argument Substitution

Argument Substitution Pattern — Example Skill

How to Use This Skill

This skill is a living test harness for argument substitution behavior. Read it, run it, observe what happened, and extend it.

Step 1 — Read this file. Do this before running. Note what you expect to see in each section.

Step 2 — Run with 0 arguments: /example-argument-substitution

Step 3 — Run with 10 arguments: /example-argument-substitution CANARY_A CANARY_B CANARY_C CANARY_D CANARY_E CANARY_F CANARY_G CANARY_H CANARY_I CANARY_J

Step 4 — Compare. Each section states what it expects. Check whether output matches.

---

How to Add a New Test

When you have a hypothesis about substitution behavior — test it here before applying it anywhere else.

1. State your hypothesis — write exactly what you expect to appear in the output
2. Add the pattern — put it in a new section below with an **Expected with 10 args:** and **Expected with 0 args:** annotation
3. Run with 0 args — /example-argument-substitution
4. Run with 10 CANARY args — /example-argument-substitution CANARY_A CANARY_B ...
5. Observe — does the rendered output match your hypothesis exactly?
6. Record the finding — if the hypothesis was wrong, correct it. If it involves literal $N syntax, record the verified fact in ./references/argument-substitution-reference.md (reference files are not substituted)
7. Only then apply the pattern to other skills

Do not document any pattern as safe without completing all 7 steps.

---

Compare each section below between the two runs. Some sections are intentional substitution — they should show values. Others are unintentional — they show what corruption looks like.

---

Capture Block (intentional substitution — should show values)

All positional args captured into named XML tags. Everything else references these tags.

$0 $1 $2 $3 $4 $5 $6 $7 $8 $9 $ARGUMENTS $ARGUMENTS[0] $ARGUMENTS[1] $ARGUMENTS[2]

Expected with 10 args: each tag holds its CANARY value. Expected with 0 args: all tags empty.

---

Intentional Substitution in Prose (should show values)

These are correct uses of substitution — injecting argument values directly into skill output.

The skill was invoked with first argument: The target is: All arguments received:

A skill instruction that uses the value directly:

> Process the file using mode .

Expected with 10 args: prose shows CANARYA, CANARYB, full CANARY string. Expected with 0 args: blanks where the values would be — still correct for a 0-arg invocation.

---

Intentional Substitution Combined with Command Substitution

Command substitution runs at load time; argument substitution also runs at load time. Both happen before Claude reads the skill. This line combines both:

!echo "Loaded at $(date '+%Y-%m-%dT%H:%M:%S') — first arg is: $0"

Expected with 10 args: timestamp + CANARY_A on the same line. Expected with 0 args: timestamp + empty string after first arg is:.

---

Unintentional Substitution — Code Examples (shows corruption)

This section intentionally demonstrates what corruption looks like when you write shell code examples in SKILL.md body. The variables below are consumed at load time.

A bash function you might want to document:

check_file() {
    local path=$1
    local mode=$2
    [[ -f $1 ]] && chmod $2 $1
}

Expected with 10 args: $1 → CANARYA, $2 → CANARYB — code is corrupted. Expected with 0 args: $1 → empty, $2 → empty — also corrupted, differently.

Brace form is equally substituted:

process() {
    echo "arg: ${1}, mode: ${2}"
}

Expected with 10 args: ${1} → CANARYA, ${2} → CANARYB — brace form is NOT safe. Expected with 0 args: both render empty — still corrupted.

Awk field references in single quotes are also substituted:

awk '{print $5, $1}' file.txt

Expected with 10 args: $5 → CANARYF, $1 → CANARYA — awk example is broken. Expected with 0 args: both disappear — single quotes provide no protection.

---

The Correct Pattern — Pre-Declaration + Reference File

For prose and output strings: use substitution directly (as shown in the Intentional sections above).

For code examples containing shell variables: move them to a reference file. Reference files are NOT subject to substitution and can show literal $1, ${1}, $ARGUMENTS syntax safely.

The pre-declaration pattern for routing skills:

1. Capture args into XML tags at the very top of SKILL.md (as in the Capture Block above)
2. Use ` throughout the rest of SKILL.md — never bare $N` after the capture block
3. Put all code examples with $N in references/*.md

---

Routing (uses `` as action — correct pattern)

flowchart TD
    Start(["Read "]) --> Q{arg0 value?}
    Q -->|"greet"| Greet["Say hello to "]
    Q -->|"farewell"| Farewell["Say goodbye to "]
    Q -->|"inspect"| Inspect["Show all captured values"]
    Q -->|"(empty)"| Help["Output usage line"]
    Q -->|"(anything else)"| Unknown["Output: Unknown action. Valid: greet, farewell, inspect"]

---

Actions

greet

Trigger: ` is greet`

Output:

Hello, !
(invoked as: )

If ` is empty, substitute world`.

farewell

Trigger: ` is farewell`

Output:

Goodbye, . It was a pleasure.
(invoked as: )

If ` is empty, substitute friend`.

inspect

Trigger: ` is inspect`

Output all captured values:

arg0              = 
arg1              = 
arg2              = 
arg3              = 
arg4              = 
arg5              = 
arg6              = 
arg7              = 
arg8              = 
arg9              = 
all_args          = 
arg_by_index_0    = 
arg_by_index_1    = 
arg_by_index_2    = 

---

Full Reference

All substitution variables, pitfall table, and verified escape evidence:

[./references/argument-substitution-reference.md](./references/argument-substitution-reference.md)

!node "${CLAUDE_PROJECT_DIR}/plugins/development-harness/skills/work-backlog-item/scripts/parser/parse.mjs" "$ARGUMENTS"

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Jamie-BitFlight
• Source: Jamie-BitFlight/claude_skills
• License: MIT

Install and usage instructions live in the source repository linked above.