docs: rename Building agents -> Agents; URLs match the settled IA

ouiliame · claude · ouiliame · commit 5fbe64a53d72 · 2026-06-10T11:18:25.000-07:00
The section's pages now live where the sidebar says they do:
building-agents/ -&gt; agents/, and the stray top-level /mcp and /skills fold in
as /agents/mcp and /agents/skills (they were always part of the agents story —
the URLs predated the IA settling). Sidebar section header is now "Agents",
link labels updated, and every old URL 308s: /building-agents(/*) -&gt; /agents(/*),
/mcp, /skills, plus the existing capabilities/ and tools/custom-tools redirect
destinations retargeted. Verified: all five new pages render and every old-URL
class redirects correctly.

Co-Authored-By: Claude Opus 4.8 (1M context) &lt;noreply@anthropic.com&gt;
diff --git a/apps/docs/content/docs/en/agents/choosing.mdx b/apps/docs/content/docs/en/agents/choosing.mdx
@@ -48,7 +48,7 @@ In the lead scorer, a `normalizeCompanyDomain` custom tool cleans a raw website
 
 ## MCP server
 
-**MCP** (Model Context Protocol) is a standard for connecting an external tool provider. Connect an [MCP server](/mcp) and its tools appear in the agent's tool list as a set. Use it to bring in a complete toolset that Sim does not provide natively, rather than wiring each action by hand.
+**MCP** (Model Context Protocol) is a standard for connecting an external tool provider. Connect an [MCP server](/agents/mcp) and its tools appear in the agent's tool list as a set. Use it to bring in a complete toolset that Sim does not provide natively, rather than wiring each action by hand.
 
 In the lead scorer, your CRM vendor ships an MCP server. After you connect it once, the agent can read accounts and update records through the vendor's own tools. The difference from a custom tool is who maintains it: a custom tool is code you wrote, while an MCP server is a toolbox someone else maintains.
 
@@ -68,7 +68,7 @@ A workflow can also run as a fixed step: the [Workflow](/blocks/workflow) block
 
 A **skill** is reusable instructions, a written playbook an agent can follow. Each skill has a short name and description that are always visible to the agent, plus a longer body the agent loads only when it decides the skill applies. Use one to capture how something should be done, separate from the tools that do it.
 
-In the lead scorer, a `lead-scoring-rubric` skill spells out the bands and disqualifiers. The agent sees the skill's name and description on every run, and when a lead is ambiguous it loads the full rubric and applies it. The distinction is simple: a tool is an action the agent takes, and a skill is guidance the agent reads. Manage skills in your [workspace](/skills).
+In the lead scorer, a `lead-scoring-rubric` skill spells out the bands and disqualifiers. The agent sees the skill's name and description on every run, and when a lead is ambiguous it loads the full rubric and applies it. The distinction is simple: a tool is an action the agent takes, and a skill is guidance the agent reads. Manage skills in your [workspace](/agents/skills).
 
 | | Who decides it runs | Where it lives | How you author it |
 | --- | --- | --- | --- |
@@ -86,8 +86,8 @@ The lead scorer uses six kinds at once: blocks for the steps that must always ru
 ## Next
 
 <Cards>
-  <Card title="Building agents" href="/building-agents" description="The features that let an agent act, follow instructions, and use your data." />
+  <Card title="Building agents" href="/agents" description="The features that let an agent act, follow instructions, and use your data." />
   <Card title="Agent block reference" href="/blocks/agent" description="Every model, setting, and output field." />
-  <Card title="Using MCP tools" href="/mcp" description="Connect an external MCP server to your agents." />
-  <Card title="Skills" href="/skills" description="Write reusable instructions agents can load." />
+  <Card title="Using MCP tools" href="/agents/mcp" description="Connect an external MCP server to your agents." />
+  <Card title="Skills" href="/agents/skills" description="Write reusable instructions agents can load." />
 </Cards>
diff --git a/apps/docs/content/docs/en/agents/custom-tools.mdx b/apps/docs/content/docs/en/agents/custom-tools.mdx
diff --git a/apps/docs/content/docs/en/agents/index.mdx b/apps/docs/content/docs/en/agents/index.mdx
@@ -33,8 +33,8 @@ To let an agent do something in the world, give it **tools**. A tool is an actio
 Tools come from a few places:
 
 - **[Integrations](/integrations)** are the catalog of external services: Gmail, Slack, Airtable, Linear, and hundreds more.
-- **[Custom tools](/building-agents/custom-tools)** are tools you define once with a schema and a snippet of code, then reuse.
-- **[MCP tools](/mcp)** come from an external provider you connect through the Model Context Protocol.
+- **[Custom tools](/agents/custom-tools)** are tools you define once with a schema and a snippet of code, then reuse.
+- **[MCP tools](/agents/mcp)** come from an external provider you connect through the Model Context Protocol.
 - **[Workflow-as-tool](/workflows)** makes another workflow callable, so the agent runs a whole procedure as one step.
 
 <Callout type="info">
@@ -43,7 +43,7 @@ The same integration can run two ways. As a [block](/workflows#blocks) it runs b
 
 ### Follow a procedure: skills
 
-To give an agent instructions it can follow, write a [skill](/skills). A skill is a reusable playbook with a short name and description the agent always sees, plus a longer body it loads only when the skill applies. In the lead scorer, a `lead-scoring-rubric` skill spells out the bands and disqualifiers, and the agent reads the full rubric only when a lead is ambiguous. A tool is an action the agent takes; a skill is guidance it reads.
+To give an agent instructions it can follow, write a [skill](/agents/skills). A skill is a reusable playbook with a short name and description the agent always sees, plus a longer body it loads only when the skill applies. In the lead scorer, a `lead-scoring-rubric` skill spells out the bands and disqualifiers, and the agent reads the full rubric only when a lead is ambiguous. A tool is an action the agent takes; a skill is guidance it reads.
 
 ### Use your documents: knowledge
 
@@ -61,13 +61,13 @@ To make an agent's result something later blocks can act on, give it a **structu
 
 Start with one Agent block and a prompt, then add only what the task needs: a tool when the agent should act, a skill when it needs written guidance, a knowledge base when it should answer from your documents, memory when it should remember, and a structured output when a later block has to read its result.
 
-<Card title="Choosing what to use" href="/building-agents/choosing" description="A side-by-side guide to tools, skills, knowledge, and the rest, with one worked example." />
+<Card title="Choosing what to use" href="/agents/choosing" description="A side-by-side guide to tools, skills, knowledge, and the rest, with one worked example." />
 
 ## Next
 
 <Cards>
   <Card title="Agent block reference" href="/blocks/agent" description="Every model, setting, and output field of the Agent block." />
-  <Card title="Choosing what to use" href="/building-agents/choosing" description="Pick the right feature for each task." />
-  <Card title="Custom tools" href="/building-agents/custom-tools" description="Define a reusable tool with a schema and code." />
-  <Card title="Using MCP tools" href="/mcp" description="Connect an external MCP server to your agents." />
+  <Card title="Choosing what to use" href="/agents/choosing" description="Pick the right feature for each task." />
+  <Card title="Custom tools" href="/agents/custom-tools" description="Define a reusable tool with a schema and code." />
+  <Card title="Using MCP tools" href="/agents/mcp" description="Connect an external MCP server to your agents." />
 </Cards>
diff --git a/apps/docs/content/docs/en/agents/mcp.mdx b/apps/docs/content/docs/en/agents/mcp.mdx
diff --git a/apps/docs/content/docs/en/agents/skills.mdx b/apps/docs/content/docs/en/agents/skills.mdx
diff --git a/apps/docs/content/docs/en/blocks/agent.mdx b/apps/docs/content/docs/en/blocks/agent.mdx
@@ -9,7 +9,7 @@ import { FAQ } from '@/components/ui/faq'
 
 The **Agent block** runs a model inside a workflow. You give it instructions, context, and tools; the model reasons over the input, calls tools as needed, and returns plain text or structured JSON that later blocks read by reference. Most workflows are built around one or more Agent blocks.
 
-An *agent* and an *Agent block* are related but distinct. An agent is a whole workflow that reasons and acts on its own; an Agent block is one reasoning step inside it. The simplest agent is a single Agent block with tools, and larger ones wire several together with other blocks. See [Building agents](/building-agents).
+An *agent* and an *Agent block* are related but distinct. An agent is a whole workflow that reasons and acts on its own; an Agent block is one reasoning step inside it. The simplest agent is a single Agent block with tools, and larger ones wire several together with other blocks. See [Agents](/agents).
 
 <BlockPreview type="agent" />
 
@@ -42,7 +42,7 @@ Capabilities the agent can call while it runs: search a knowledge base, send a S
 
 ### Skills
 
-[Agent skills](/skills) the agent can load on demand: reusable instruction packages like a coding standard or a support playbook. Only the skill names sit in context up front, and the agent loads the full instructions when it decides a skill is relevant.
+[Agent skills](/agents/skills) the agent can load on demand: reusable instruction packages like a coding standard or a support playbook. Only the skill names sit in context up front, and the agent loads the full instructions when it decides a skill is relevant.
 
 ### Memory
 
diff --git a/apps/docs/content/docs/en/index.mdx b/apps/docs/content/docs/en/index.mdx
@@ -48,7 +48,7 @@ Welcome to Sim, the open-source AI workspace where teams build, deploy, and mana
   <Card title="Team Management" href="/permissions/roles-and-permissions">
     Set up workspace roles and permissions
   </Card>
-  <Card title="MCP Integration" href="/mcp">
+  <Card title="MCP Integration" href="/agents/mcp">
     Connect external services with Model Context Protocol
   </Card>
   <Card title="SDKs" href="/api-reference">
diff --git a/apps/docs/content/docs/en/integrations/index.mdx b/apps/docs/content/docs/en/integrations/index.mdx
@@ -23,7 +23,7 @@ Click **Integrations** in the workspace sidebar. The page shows your **Connected
   height={664}
 />
 
-The page's second tab, **Skills**, holds your workspace's [agent skills](/skills).
+The page's second tab, **Skills**, holds your workspace's [agent skills](/agents/skills).
 
 Open a service to see what it offers:
 
diff --git a/apps/docs/content/docs/en/introduction/index.mdx b/apps/docs/content/docs/en/introduction/index.mdx
@@ -41,7 +41,7 @@ A Sim system is not a single chat response. It is a set of resources that live i
 
 - **[Mothership](/mothership)** is the natural-language control plane. You describe what you want, and it builds and edits the resources for you.
 - **[Workflows](/workflows)** are visual programs made of blocks, where your logic runs. Most other resources become useful through a workflow.
-- **[Agents and tools](/building-agents)** are how a workflow acts. An agent reasons with a model, and tools let it take actions like sending an email or querying an API.
+- **[Agents and tools](/agents)** are how a workflow acts. An agent reasons with a model, and tools let it take actions like sending an email or querying an API.
 - **[Tables](/tables)** hold structured rows your workflows read, write, and process.
 - **[Knowledge bases](/knowledgebase)** are searchable memory. An agent retrieves relevant passages from your documents to ground its answers.
 - **[Files](/files)** are the documents and media your workflows store, read, and produce.
@@ -70,7 +70,7 @@ Sim provides native integrations with 1,000+ services:
 - **Search and data.** Google Search, Perplexity, Firecrawl, Exa AI.
 - **Databases.** PostgreSQL, MySQL, Supabase, Pinecone, Qdrant.
 
-For anything not built in, [MCP support](/mcp) connects any external service or tool.
+For anything not built in, [MCP support](/agents/mcp) connects any external service or tool.
 
 ## Deployment options
 
diff --git a/apps/docs/content/docs/en/mcp/meta.json b/apps/docs/content/docs/en/mcp/meta.json
diff --git a/apps/docs/content/docs/en/meta.json b/apps/docs/content/docs/en/meta.json
@@ -13,12 +13,12 @@
     "deployment",
     "triggers",
     "blocks",
-    "---Building agents---",
-    "./building-agents/index",
-    "./building-agents/choosing",
-    "./building-agents/custom-tools",
-    "./mcp/index",
-    "skills",
+    "---Agents---",
+    "./agents/index",
+    "./agents/choosing",
+    "./agents/custom-tools",
+    "./agents/mcp",
+    "./agents/skills",
     "./integrations/knowledge",
     "./integrations/memory",
     "---Tables---",
diff --git a/apps/docs/next.config.ts b/apps/docs/next.config.ts
@@ -20,7 +20,7 @@ const config: NextConfig = {
         permanent: true,
       },
       // building-agents/agents merged into the building-agents overview
-      { source: '/building-agents/agents', destination: '/building-agents', permanent: true },
+      { source: '/building-agents/agents', destination: '/agents', permanent: true },
       // form deployment removed
       { source: '/deployment/form', destination: '/deployment', permanent: true },
       // copilot deprecated and removed
@@ -32,11 +32,11 @@ const config: NextConfig = {
       { source: '/variables', destination: '/workflows/variables', permanent: true },
       { source: '/variables/:path*', destination: '/workflows/variables', permanent: true },
       // capabilities/* renamed to building-agents/*
-      { source: '/capabilities', destination: '/building-agents', permanent: true },
-      { source: '/capabilities/agents', destination: '/building-agents/agents', permanent: true },
+      { source: '/capabilities', destination: '/agents', permanent: true },
+      { source: '/capabilities/agents', destination: '/agents', permanent: true },
       {
         source: '/capabilities/choosing',
-        destination: '/building-agents/choosing',
+        destination: '/agents/choosing',
         permanent: true,
       },
       // execution/* was broken up; redirect old URLs to their new homes
@@ -51,11 +51,16 @@ const config: NextConfig = {
       { source: '/execution/chat', destination: '/deployment/chat', permanent: true },
       { source: '/execution/form', destination: '/deployment/form', permanent: true },
       { source: '/mcp/deploy-workflows', destination: '/deployment/mcp', permanent: true },
+      // building-agents section renamed to agents; mcp and skills folded into it
+      { source: '/building-agents', destination: '/agents', permanent: true },
+      { source: '/building-agents/:path*', destination: '/agents/:path*', permanent: true },
+      { source: '/mcp', destination: '/agents/mcp', permanent: true },
+      { source: '/skills', destination: '/agents/skills', permanent: true },
       // tools/ + triggers/<service> unified into per-service integrations/ pages.
       // Specific moves first (Next applies the first matching redirect):
       {
         source: '/tools/custom-tools',
-        destination: '/building-agents/custom-tools',
+        destination: '/agents/custom-tools',
         permanent: true,
       },
       { source: '/tools', destination: '/integrations', permanent: true },
