@@ -53,10 +53,12 @@ every time**:
 # The board's fields, once per session. Refuses to go on from a failed call.
 FIELDS=$(gh project field-list 43 --owner modelcontextprotocol --format json) || FIELDS=
 # opt <Field> <Option name> → the option's current id, or nothing.
+# The arguments reach jq through --args, never as shell positional parameters:
+# Claude Code rewrites those in a skill invoked with arguments (#5160).
 opt() {
-  jq -r --arg f "$1" --arg o "$2" \
-    '.fields[] | select(.name == $f) | .options[] | select(.name == $o) | .id' \
-    <<<"$FIELDS"
+  jq -r '$ARGS.positional as [$f, $o]
+    | .fields[] | select(.name == $f) | .options[] | select(.name == $o) | .id' \
+    --args "$@" <<<"$FIELDS"
 }
 
 STATUS_OPT=$(opt Status "Todo")
 
@@ -429,7 +429,9 @@ measure it, is [`docs/skill-authoring.md`](./docs/skill-authoring.md).
    works while the skill can never auto-fire; an unquoted `#` truncates the
    description silently.
    **Quote any description containing `#` or `:`**, and keep the opening `---`
-   on the file's first line.
+   on the file's first line. **A body holds no `$0`–`$9` and no `$ARGUMENTS`**:
+   Claude Code substitutes them when a skill is invoked with arguments, so a
+   recipe's shell parameters or awk fields reach the model rewritten.
 2. **Every skill declares `disable-model-invocation` explicitly. Default it to
    `false`.** Invoking a skill has no side effects (it loads instructions), and
    work is usually asked for in prose, which a `true` skill can never answer. A
 
@@ -81,6 +81,22 @@ Three further rules, each learned the expensive way:
   rate, and a prompt-only eval can never exercise a path trigger, so shipping it
   means shipping an untestable claim.
 
+## Writing the body
+
+**No `$0`–`$9` and no `$ARGUMENTS` anywhere in a body.** When a skill is
+invoked _with_ arguments (`/board-ops add #5159 as In Progress`, or the model
+passing `args`), Claude Code substitutes those placeholders before the model
+reads the body, so a recipe that uses shell positional parameters or awk fields
+arrives rewritten. `board-ops`'s `opt()` once reached the model as
+`--arg f "issue"` in place of its field-name parameter, and so resolved no
+option id for any field (#5160). Invoked without arguments the body is
+untouched, which is why reading the skill by hand never shows it.
+
+Name the values instead: hand a shell function's arguments to jq with
+`--args "$@"` and read `$ARGS.positional`, pass awk values with `-v`, or set a
+named variable before the call. `${NAME}` and jq's `$ARGS` are not
+placeholders. `verify:skills` rejects every occurrence, by line.
+
 ## Writing an eval case
 
 ### The first-move rule
@@ -567,7 +583,8 @@ release changes the default model.
    description from that point on so it stays *non-empty* — which is why it went
    unnoticed until `board-ops` lost both its board numbers. `verify:skills` now
    rejects that truncation, so the gate catches it; quote the value rather than
-   relying on the check to tell you.
+   relying on the check to tell you. The body holds no `$<digit>` or
+   `$ARGUMENTS` (see [Writing the body](#writing-the-body)).
 2. `disable-model-invocation` is declared explicitly; default it to `false`.
 3. Description is action-first, with `Use when …; when …; when …`.
 4. **If the skill is model-invoked**, `evals/evals.json` carries **at least
 
@@ -73,7 +73,35 @@ export function splitFrontmatter(text) {
 }
 
 /**
- * Parse and validate one skill's frontmatter.
+ * Argument placeholders in a skill's body: `$0`–`$9` and `$ARGUMENTS`.
+ *
+ * When a skill is invoked WITH arguments, Claude Code substitutes these before
+ * the model reads the body, so a shell positional parameter or an awk field in
+ * a recipe arrives rewritten. `board-ops`'s option lookup reached the model with
+ * its field name replaced by a word of the arguments, and resolved no option id
+ * (#5160). Invoked without arguments the body is untouched, which is why a spot
+ * check passes. No skill here takes arguments on purpose, so every occurrence is
+ * the hazard; a skill that did would need an allowance here.
+ *
+ * @param {string} text Full file contents.
+ * @param {string} body The part after the frontmatter, from `splitFrontmatter`.
+ * @returns {Array<{ line: number, placeholder: string }>} 1-based file lines.
+ */
+export function findArgumentPlaceholders(text, body) {
+  const firstBodyLine = text
+    .slice(0, text.length - body.length)
+    .split("\n").length;
+  const hits = [];
+  body.split("\n").forEach((line, i) => {
+    for (const m of line.matchAll(/\$(?:ARGUMENTS|\d)/g)) {
+      hits.push({ line: firstBodyLine + i, placeholder: m[0] });
+    }
+  });
+  return hits;
+}
+
+/**
+ * Parse and validate one skill's frontmatter and body.
  *
  * @param {string} dirName Directory the SKILL.md lives in — the skill's identity.
  * @param {string} text Full file contents.
@@ -82,7 +110,7 @@ export function splitFrontmatter(text) {
  */
 export function parseSkill(dirName, text) {
   const errors = [];
-  const { frontmatter, error } = splitFrontmatter(text);
+  const { frontmatter, body, error } = splitFrontmatter(text);
   if (error) return { errors: [error] };
 
   let doc;
@@ -197,6 +225,13 @@ export function parseSkill(dirName, text) {
     );
   }
 
+  for (const hit of findArgumentPlaceholders(text, body)) {
+    errors.push(
+      `line ${hit.line} has \`${hit.placeholder}\`, which Claude Code replaces when the skill is invoked with arguments (#5160); ` +
+        "write the recipe without it (jq `--args`, awk `-v`, a named variable)",
+    );
+  }
+
   // A skill nothing can reach is dead weight that still costs a directory.
   if (!modelInvoked && meta["user-invocable"] === false) {
     errors.push(
 
@@ -9,6 +9,7 @@ import assert from "node:assert/strict";
 import {
   splitFrontmatter,
   parseSkill,
+  findArgumentPlaceholders,
   isChainCase,
   MIN_CHAIN_LENGTH,
   MIN_POSITIVE_CASES,
@@ -147,6 +148,37 @@ test("parseSkill rejects a skill nothing can reach", () => {
   assert.match(r.errors.join(), /unreachable/);
 });
 
+test("parseSkill rejects argument placeholders in the body", () => {
+  // Claude Code substitutes these when a skill is invoked with arguments, so a
+  // recipe's shell positional parameters arrive rewritten (#5160).
+  const head =
+    "---\nname: x\ndescription: d\ndisable-model-invocation: true\n---\n";
+  const r = parseSkill(
+    "x",
+    head + '\nopt() {\n  jq --arg f "$1" --arg o "$2"\n}\nSee $ARGUMENTS.\n',
+  );
+  assert.deepEqual(
+    r.errors.map((e) => e.split(",")[0]),
+    ["line 8 has `$1`", "line 8 has `$2`", "line 10 has `$ARGUMENTS`"],
+  );
+  // jq's `$ARGS`, named variables and `${VAR}` are not placeholders.
+  assert.deepEqual(
+    parseSkill(
+      "x",
+      head + 'jq -r \'$ARGS.positional as [$f]\' --args "$@" "${FIELD}"\n',
+    ).errors,
+    [],
+  );
+});
+
+test("findArgumentPlaceholders counts lines from the top of the file", () => {
+  const text = "---\na: b\n---\nfirst\n$0 here\n";
+  const { body } = splitFrontmatter(text);
+  assert.deepEqual(findArgumentPlaceholders(text, body), [
+    { line: 5, placeholder: "$0" },
+  ]);
+});
+
 test("parseSkill validates the paths list", () => {
   assert.match(
     parseSkill(