Skills

Purpose and Scope

A Turborepo skill is a way to give an AI coding assistant Turborepo-specific operating knowledge before it edits a repository. In the first-party docs, Agent Skills are described as an open standard made of folders of instructions, scripts, and resources that agents can use to work more accurately and efficiently. For Turborepo, that means the agent should understand monorepo structure, task configuration, caching tradeoffs, integration patterns, and common anti-patterns rather than treating every workspace as an unrelated JavaScript project.

The most useful mental model is that the skill packages documentation intent into agent-consumable guidance. The tool guide sources show the kind of knowledge that matters: each guide names a tool, states the integration goal, declares prerequisites or related docs, and then teaches a concrete Turborepo task design. Biome is presented as an unusually fast tool that may be best modeled as a root task, Jest is shown as package-level test tasks with a separate persistent watch task, and Docker is framed around pruning a monorepo for deployable inputs. Sources: apps/docs/content/docs/guides/tools/biome.mdx, apps/docs/content/docs/guides/tools/docker.mdx, apps/docs/content/docs/guides/tools/jest.mdx

Relevant Source Files

• apps/docs/content/docs/guides/tools/biome.mdx — Shows a tool integration guide with root-task recommendations, cache tradeoff language, and concrete package.json plus turbo.json examples that an agent should learn to reproduce correctly.
• apps/docs/content/docs/guides/tools/create-turbo-callout.tsx — Defines the shared callout that many tool guides use to set the baseline repository assumption: create-turbo or a similarly structured workspace.
• apps/docs/content/docs/guides/tools/docker.mdx — Documents a monorepo-specific deployment problem and the turbo prune --docker solution, which is the kind of workflow-specific knowledge a skill should preserve for agents.
• apps/docs/content/docs/guides/tools/index.mdx — Provides the overview page for tool integrations and establishes that Turborepo works with many development tools through task and caching guidance.
• apps/docs/content/docs/guides/tools/jest.mdx — Demonstrates package-scoped task setup, package-manager-specific install commands, cacheable test execution, and persistent watch-mode configuration.
• apps/docs/content/docs/guides/tools/meta.json — Supplies the navigation metadata for the tools guide section, reinforcing that these integrations are a documented documentation family rather than isolated examples.

Core Primitives

The Agent Skill primitive is not a Turborepo runtime feature like turbo run; it is an agent-facing distribution format for expertise. The installation command from the official docs is:

npx skills add vercel/turborepo

After installation, an AI assistant can consult the Turborepo Skill when it needs to modify turbo.json, add tasks, reason about package boundaries, or choose between caching strategies. The skill should steer the agent toward first-party terminology: root tasks, package tasks, persistent tasks, cacheable outputs, pruning, package-manager workspaces, and guide-specific assumptions such as a create-turbo-style repository layout.

A second primitive is the repository context that the agent applies the skill to. The shared CreateTurboCallout component says the tool guides assume create-turbo or a repository with a similar structure. That matters because many examples rely on conventional apps and packages folders, a root package.json, and a root turbo.json. An agent using the skill should first inspect whether the current repository matches those conventions before copying a guide exactly. Sources: apps/docs/content/docs/guides/tools/create-turbo-callout.tsx, apps/docs/content/docs/guides/tools/index.mdx

A third primitive is task shape. The Jest guide distinguishes a normal test task, which exits and can be cached, from test:watch, which stays alive and should be marked persistent with caching disabled. The Biome guide distinguishes root tasks from per-package scripts because Biome is fast enough that less configuration may be better than maximizing cache-hit granularity. These distinctions are precisely the kind of operational judgment that a Turborepo-aware skill should add to an AI assistant. Sources: apps/docs/content/docs/guides/tools/biome.mdx, apps/docs/content/docs/guides/tools/jest.mdx

System-to-Code Mapping

The skill should map high-level user requests to the same document patterns used by the Turborepo guides. When a user asks to add a tool, the agent should identify whether the integration belongs at the root or in individual workspaces, add scripts in the correct package.json files, and register matching tasks in turbo.json. When the tool produces long-running output, the agent should consider persistent and cache: false. When the tool produces deterministic output and exits, the agent should make the task cacheable unless the guide recommends a specific exception.

The Biome guide provides a compact example of root-task mapping. It creates root scripts named format-and-lint and format-and-lint:fix, then registers them as //#format-and-lint and //#format-and-lint:fix in turbo.json, disabling cache for the write-mode task. A skill-guided agent should preserve the special root-task syntax rather than inventing package scripts in every workspace. It should also preserve the documented tradeoff: root Biome usage can cause cache misses when the Biome version or configuration changes, but the reduced configuration is often worth it. Sources: apps/docs/content/docs/guides/tools/biome.mdx

The Docker guide provides a different mapping. The user problem is not task execution alone; it is Docker layer invalidation caused by a global monorepo lockfile. The documented solution is turbo prune api --docker, which writes a pruned repository into ./out, with install-focused files under ./out/json and the fuller workspace content under ./out/full. A Turborepo skill should help an agent explain why pruning is needed before editing a Dockerfile, because the important behavior is minimizing unrelated dependencies and lockfile churn. Sources: apps/docs/content/docs/guides/tools/docker.mdx

Execution Flow

A practical AI workflow starts with intent classification. If the user asks, “add Jest to this monorepo,” the agent should treat that as a tool-integration task, not merely an npm install. It should inspect workspace names, choose package-manager commands that match the repository, add test scripts to the relevant packages, and register a root test task. If the user also needs watch mode, the agent should add a separate test:watch script and configure the Turborepo task as persistent and uncached, following the guide’s distinction between finite and long-running processes. Sources: apps/docs/content/docs/guides/tools/jest.mdx

For formatting and linting requests, the skill should guide the agent to ask whether the tool is a fast whole-repository tool or a package-scoped task. The Biome guide recommends a root task because Biome is extraordinarily fast, while still documenting the cache-hit tradeoff. That gives the agent a decision rule: prefer the guide’s root-task pattern when adding Biome, but do not generalize that rule to all tools. For deployment requests, the Docker guide should redirect the agent from naive COPY . . edits toward turbo prune --docker and staged Docker inputs.

Reference: Agent-Facing Patterns

The key contract for a Turborepo skill is conservative specificity. It should not tell an agent to “add a task” in the abstract; it should carry the exact patterns that the docs use for common tools. It should also preserve caveats, such as Biome’s cache-miss tradeoff and Jest watch mode being a development task rather than a cacheable CI task. That is what turns a generic coding assistant into a monorepo-aware collaborator.

Next Steps

After adding the skill with npx skills add vercel/turborepo, validate agent output against the relevant guide before merging changes. Check that package.json scripts match the intended workspace scope, turbo.json uses the correct task names and flags, and Docker workflows use pruning when the deployment target is a subset of the monorepo. For broader AI workflows, pair the skill with task descriptions in turbo.json and with cache-aware worktree practices so multiple agents can share fast feedback without overwriting each other’s changes.