Turborepo skill: command dispatcher contradicts SKILL.md on Root Tasks

[Jason-Kennemer]

Summary

The shipped Turborepo skill's slash-command dispatcher (command/turborepo.md) contains an absolute rule that contradicts the nuanced guidance in the skill's own SKILL.md, causing the skill to reject valid Turborepo configurations such as Vitest Projects' //#test.

Where it shows up

Skill version: v2.9.7-canary.13 (per SKILL.md frontmatter)

command/turborepo.md:44 — absolute, no escape clause:

**CRITICAL - When creating tasks/scripts/pipelines:**

1. **DO NOT create Root Tasks** - Always create package tasks

SKILL.md:77 — acknowledges valid cases:

Root Tasks (//#taskname) are ONLY for tasks that truly cannot exist in packages (rare).

The slash-command dispatcher is the file that fires when a user invokes /turborepo — so in practice it's the authoritative source for agent behavior on task creation, and it's strictly stricter than the reference material it's dispatching to.

Impact

When an agent follows the dispatcher verbatim, it will reject correct configurations that Turborepo's own documentation prescribes. Examples:

• Vitest Projects — uses //#test as a root task to run Vitest across projects at the repo root.
• The missing-root-task-in-turbo-json error doc — explicitly permits root tasks when they don't invoke turbo, e.g., for repo-level tooling that genuinely has no per-package home.
• Any root-level tooling (changeset publish, release-script orchestration, repo-wide linters that must run once globally, etc.) where forcing a per-package task would be awkward or impossible.

In each of these cases, an agent following the dispatcher will generate incorrect guidance — either refusing to add the root task or rewriting it into an incorrect per-package shape.

Suggested fix

Soften the command dispatcher to match SKILL.md's nuance. Minimal diff on command/turborepo.md:

 **CRITICAL - When creating tasks/scripts/pipelines:**

-1. **DO NOT create Root Tasks** - Always create package tasks
+1. **Prefer package tasks over Root Tasks.** Root Tasks (`//#taskname`) are
+   valid only for tasks that truly cannot exist in packages — e.g., Vitest
+   Projects' `//#test`, repo-wide release scripts, or tooling that doesn't
+   invoke `turbo` itself. See SKILL.md § "IMPORTANT: Package Tasks, Not Root
+   Tasks" and the Turborepo error doc `missing-root-task-in-turbo-json`.
 2. Add scripts to each relevant package's `package.json` (e.g., `apps/web/package.json`, `packages/ui/package.json`)
 3. Register the task in root `turbo.json`
 4. Root `package.json` only contains `turbo run <task>` - never actual task logic

Alternatively, add an explicit exceptions list (Vitest Projects, changesets, release tooling, etc.) so the valid cases are named rather than implied.

Context

Hit during a Codex code review of a PR that checked the skill into a client monorepo. Codex flagged the absolute instruction as generating incorrect guidance for valid repo-level tooling; filing here so the fix lands upstream rather than as a local patch.

Related downstream PR: ValescoAgency/millsreg-sanity#67 (where this was first noticed).

Thanks for shipping the skill! The reference library has been great in practice; this one dispatcher line was the only rough edge we've hit.