Test harness for Claude Code skill argument substitution — demonstrates capture-block pre-declaration, XML tag referencing, unintentional variable corruption in code blocks, and correct placement of shell examples in reference files. Use when verifying substitution behavior before applying a pattern to other skills, testing how arguments flow from skill invocations, or understanding the pre-declaration and reference file pattern with greet/farewell/inspect actions.
Installation
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Test harness for Claude Code skill argument substitution — demonstrates capture-block pre-declaration, XML tag referencing, unintentional variable corruption in code blocks, and correct placement of shell examples in reference files. Use when verifying substitution behavior before applying a pattern to other skills, testing how arguments flow from skill invocations, or understanding the pre-declaration and reference file pattern with greet/farewell/inspect actions.
argument-hint
<action> [target] [--flag]
user-invocable
true
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.
State your hypothesis — write exactly what you expect to appear in the output
Add the pattern — put it in a new section below with an **Expected with 10 args:** and **Expected with 0 args:** annotation
Run with 0 args — /example-argument-substitution
Run with 10 CANARY args — /example-argument-substitution CANARY_A CANARY_B ...
Observe — does the rendered output match your hypothesis exactly?
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)
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.
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: <all_args>
A skill instruction that uses the value directly:
Process the file using mode .
Expected with 10 args: prose shows CANARY_A, CANARY_B, 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:.
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.
Expected with 10 args:$1 → CANARY_A, $2 → CANARY_B — 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} → CANARY_A, ${2} → CANARY_B — 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 → CANARY_F, $1 → CANARY_A — 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:
Capture args into XML tags at the very top of SKILL.md (as in the Capture Block above)
Use <tagname> throughout the rest of SKILL.md — never bare $N after the capture block
