# Slash-Command Tool Sequencing **Purpose:** Codify the discipline for writing slash-command bodies (whether they live as `commands/*.md` or `skills/*/SKILL.md`) so the rendered prompt produces deterministic, parallel-where-possible tool-call sequences. This is the **authoring** rule that pairs with `skill-management.md` (frontmatter discipline) and `claude-folder-spec.md` (folder structure spec). **Established:** 2026-05-11 as part of TODO #51 Workstream C. **Cross-reference:** `~/.claude/rules/skill-management.md`, `~/.claude/rules/claude-folder-spec.md`, `~/.claude/rules/askuserquestion-empty-answer.md`, `~/.claude/rules/single-option-default.md`. --- ## The Foundational Fact **A slash-command body is a single rendered prompt that enters context once and stays.** Claude does NOT re-read the file mid-session. Every instruction is a standing instruction. If a step says "now wait for the user," that wait happens once at the moment the prompt is read — the file is not consulted again when the user replies. This has three consequences for authoring: 1. **Write standing instructions, not one-time setup.** "Always read X before writing Y" is correct. "Read X. Now write Y." is correct only for the immediate turn — Claude won't re-read the rule on later turns. 2. **Pre-write gates must be phrased as ongoing invariants.** "Before any write in this skill, confirm Phase 1 status table has been emitted" beats "After Phase 1, write the status table." 3. **Sequencing is determined at render time.** What you write IS the prompt Claude sees. There's no runtime branching engine. If you want branching, write it as `if X then Y else Z` prose that Claude can pattern-match on. --- ## The Exemplar Shape Every well-formed slash command body has this shape: ``` --- description: disable-model-invocation: allowed-tools: argument-hint: --- # **Purpose:** **When to invoke:** --- ## Phase 1: Load Context (MANDATORY) **Pre-write gate:** Have I read all source files? Have I checked prior submissions? Have I loaded the rubric? — yes/yes/yes required before any subsequent phase. --- ## Phase 2+: --- ## Output --- ## Integration ``` Reference exemplars in this repo: `~/.claude/skills/1000xagent-validate-folder/SKILL.md`, `~/.claude/skills/1000xagent-audit-identity/SKILL.md`, `~/.claude/skills/1000xagent-audit-redundancy/SKILL.md`, `~/.claude/skills/spec/SKILL.md`, `~/dev/academic/cs-463-comparative-languages/.claude/skills/homework/SKILL.md`. --- ## Tool-Sequencing Discipline ### Phase 1 is ALWAYS context-load Every skill that touches more than 1 file MUST have a Phase 1 whose only output is context. No writes, no AskUserQuestion, no commits. The phase must: 1. **Enumerate sources via `find` or `Glob`** — no judgment-skipping. If 12 files match the pattern, all 12 get read. 2. **Read every enumerated file** via parallel batch (single message with multiple Read tool calls) when count is 4–15. Dispatch parallel subagents via Agent tool when count >15 or distinct-file-type count >3. 3. **Emit a status table** — one row per file with filename, read-status, one-line summary. This is the proof that context was actually built. 4. **Block with a pre-write gate** — the phrasing "Have I read all source files? Have I checked prior submissions? Have I loaded the rubric? — yes/yes/yes required" must appear verbatim or close to it before any phase that writes. **Forbidden Phase 1 patterns:** - Calling `AskUserQuestion` as Step 1 (forbidden by `~/.claude/rules/askuserquestion-empty-answer.md` + this rule). - Reading "the most relevant" file based on a heuristic — read everything, then filter by reading more (not by reading less). - Skipping the status table because "Claude saw the Read results" — the table is the audit trail and the gate. ### Subagent-Dispatch Decision Matrix | File count | Distinct file types | Approach | |---|---|---| | 1–3 | any | Direct Read tool calls, sequential is fine | | 4–15 | ≤3 | Parallel Read batch in a single message | | 4–15 | >3 | Parallel Read batch is still fine; consider an Agent subagent if the types need different processing logic | | >15 | any | Dispatch parallel subagents via Agent tool (`context: fork` in skill frontmatter if applicable). Each subagent reads a slice + returns a summary. | | >50 | any | Multi-axis subagent fan-out (the `/spec` 4-axis pattern). Subagents run in parallel in a single message. | **`context: fork` opportunity** — for research-heavy skills, set `context: fork` + `agent: Explore` in frontmatter so the skill runs in its own context window with prompt cache inherited. ### `!`bash`` vs prose tool instructions vs `@file` references | Use this when | Author as | |---|---| | Enumerating files, computing counts, checking git status — output should appear inline in the rendered prompt before Claude responds | `` `!bash` `` block | | Listing exact files to read | Prose with paths, then Read tool calls | | Always-loaded reference content (e.g., the agent's CLAUDE.md or a specific rule the skill depends on) | `@path/to/file.md` (auto-import — max depth 5) | | Reading content that depends on prior output | Prose with placeholders, let Claude resolve at run time | **`!`bash`` blocks run BEFORE Claude responds** — their output is appended to the rendered prompt. This is how to inject live data (git status, file lists, dates) into the prompt without burning Claude's tool budget. ### Parallel-tool-call encouragement language Skills that benefit from parallel tool use should say so explicitly in the body. The phrase that produces the right behavior: > "Launch these N reads in a single message so they execute in parallel." OR > "Dispatch the following N subagents in parallel via the Agent tool, each in a separate tool-use block within the same message." Don't be coy about parallelism. Saying "read these files" without the parallel-call hint produces sequential reads. Saying "read in parallel" produces a parallel batch. --- ## AskUserQuestion Discipline **Never as Step 1.** Context must be loaded first; only then can the question be precise enough to be worth asking. **Never when the answer is already on disk.** If "which week?" can be inferred from CWD + git status + `agents.yaml`, don't ask — infer. **Never as a 3-option menu when one option is obviously best.** Per `single-option-default.md`: pick the best path, ship, let Tyler interrupt. Menu-asking is the cardinal violation. **Use only when one of the four ask-triggers fires** (per `~/.claude/rules/autonomous-authority.md`): 1. Real creative / design direction 2. Genuine ambiguity in the request 3. Novel / first-of-its-kind work 4. External constraint I can't resolve **Defensive parsing:** Per `~/.claude/rules/askuserquestion-empty-answer.md`, treat empty/whitespace/punctuation-only responses as NOT answered. Re-ask in prose, never re-fire the tool. --- ## Numbered Step Discipline - **Numbered Step headers** — `## Step 1`, `## Step 2`. Not bullets, not "Now do X" prose. - **Imperative verbs** — "Read", "Write", "Commit", "Dispatch". Not "should read", not "you may want to". - **One responsibility per step** — if a step does two things, split it. If two steps do one thing, merge them. - **One responsibility per skill** — a skill that "audits AND fixes" should be two skills, or one skill with a `` argument that routes between two clearly-separated phases. --- ## Side-Effect Categories Skills/commands with any of these MUST have `disable-model-invocation: true`: | Category | Examples | |---|---| | **File writes outside CWD** | Cross-repo edits, registry mutations, log appends | | **Git mutations** | Commits, pushes, branch creation, tag creation | | **Network mutations** | Vercel deploys, GitHub API writes, Porkbun DNS edits, Cloudflare API | | **Filesystem destructive** | `rm`, `mv` over existing files, dir restructuring | | **External API writes** | Resend email send, Slack post, Discord webhook, any third-party POST | | **Auth-bearing operations** | Any tool call using a private credential | Skills that ONLY read (audits, validators, status reports, dashboards) should remain model-invocable (no `disable-model-invocation`). --- ## Frontmatter Completeness Gate Every skill / command MUST have: - [ ] `description:` — present, under 200 chars, includes both what and when - [ ] At minimum-tool declarations via `allowed-tools:` SHOULD be present (defense-in-depth Layer 5) - [ ] `disable-model-invocation: true` if any side-effect category applies - [ ] `argument-hint:` if the skill takes arguments A skill without `description:` is invisible to auto-invocation (Claude can't decide when to use it). A skill with an invalid field (`triggers:`, `match_prompt:`, etc.) silently no-ops on that field — verify field names against `claude-folder-spec.md`. --- ## 500-Line Ceiling Skills should stay under 500 lines. If a skill body crosses 500 lines, refactor: - Move reference content to supporting files in the skill directory (`reference.md`, `templates/foo.md`) - Reference them via `@path` imports or instruct Claude to Read them on-demand - Split into multiple skills if responsibilities are distinct Long skills are a smell that the responsibility is too broad OR that reference material is inline that should be linked. --- ## Anti-Patterns | Anti-pattern | Why it's wrong | Fix | |---|---|---| | Phase 1 calls `AskUserQuestion` | Bypasses context load; produces low-quality questions | Move AskUserQuestion to after Phase 1's status table | | "Now I'll read each file individually" | Sequential read burns tokens + time | "Read all N files in parallel in a single message" | | Skill description >500 chars | Eats context budget; rarely matches more accurately | Tighten to one sentence with both what + when | | `triggers:` field in frontmatter | Silently ignored — Claude Code only honors `description` for matching | Migrate trigger keywords into `description:` | | Skill that audits AND fixes in one mode | Audit reports drift away from actions; user can't dry-run | Split into `` argument modes | | Skill body with 3-option menu | Violates `single-option-default.md` | Pick the best path; let Tyler redirect | | Skill with no `allowed-tools:` | Permission prompts on every tool call (without bypass-permissions) | Declare minimum tool set | | Skill that re-implements another skill | Skill drift; future maintenance pain | Invoke the existing skill via the Skill tool | --- ## When to Revise This Rule - Claude Code ships a new frontmatter field — update the completeness gate. - Anthropic publishes new guidance on subagent dispatch — update the decision matrix. - A new skill in this repo crosses 500 lines and the refactor pattern doesn't fit — add a refactor case to the 500-line section. - A pattern emerges that's reusable across skills but doesn't have a home here — add it. --- *Established 2026-05-11 as part of TODO #51 Workstream C. Pairs with `skill-management.md` (frontmatter discipline), `claude-folder-spec.md` (folder structure), `askuserquestion-empty-answer.md` (defensive parsing), and `single-option-default.md` (response shape).*