From c33d0c7f1fff13414d0fa0861788eb84587a6910 Mon Sep 17 00:00:00 2001
From: Jonathan Hefner <jonathan@hefner.pro>
Date: Sun, 19 Apr 2026 15:25:28 -0500
Subject: [PATCH] Remove redundant `what-are-skills.mdx`

The content of this page is now adequately represented elsewhere:

- The intro, directory structure, and progressive disclosure sections
  are covered by `home.mdx` and `specification.mdx`.
- The `SKILL.md` format details are covered by `quickstart.mdx` and
  `specification.mdx`.
- The "key advantages" framing (self-documenting, extensible, portable)
  is either self-evident, conveyed by the directory trees in `home.mdx`
  and `specification.mdx`, or demonstrated by the Client Showcase.

Also adds a redirect from `/what-are-skills` to the home page so
existing inbound links don't break.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 docs/docs.json           |  5 ++-
 docs/what-are-skills.mdx | 71 ----------------------------------------
 2 files changed, 4 insertions(+), 72 deletions(-)
 delete mode 100644 docs/what-are-skills.mdx

diff --git a/docs/docs.json b/docs/docs.json
index f70663f..8145589 100644
--- a/docs/docs.json
+++ b/docs/docs.json
@@ -21,7 +21,6 @@
   "navigation": {
     "pages": [
       "home",
-      "what-are-skills",
       "specification",
       "clients",
       {
@@ -58,6 +57,10 @@
     {
       "source": "/integrate-skills",
       "destination": "/client-implementation/adding-skills-support"
+    },
+    {
+      "source": "/what-are-skills",
+      "destination": "/"
     }
   ]
 }
diff --git a/docs/what-are-skills.mdx b/docs/what-are-skills.mdx
deleted file mode 100644
index 0f80ba0..0000000
--- a/docs/what-are-skills.mdx
+++ /dev/null
@@ -1,71 +0,0 @@
----
-title: "What are skills?"
-description: "Agent Skills are a lightweight, open format for extending AI agent capabilities with specialized knowledge and workflows."
----
-
-At its core, a skill is a folder containing a `SKILL.md` file. This file includes metadata (`name` and `description`, at minimum) and instructions that tell an agent how to perform a specific task. Skills can also bundle scripts, templates, and reference materials.
-
-```directory
-my-skill/
-├── SKILL.md          # Required: instructions + metadata
-├── scripts/          # Optional: executable code
-├── references/       # Optional: documentation
-└── assets/           # Optional: templates, resources
-```
-
-## How skills work
-
-Skills use **progressive disclosure** to manage context efficiently:
-
-1. **Discovery**: At startup, agents load only the name and description of each available skill, just enough to know when it might be relevant.  
-     
-2. **Activation**: When a task matches a skill's description, the agent reads the full `SKILL.md` instructions into context.  
-     
-3. **Execution**: The agent follows the instructions, optionally loading referenced files or executing bundled code as needed.
-
-This approach keeps agents fast while giving them access to more context on demand.
-
-## The SKILL.md file
-
-Every skill starts with a `SKILL.md` file containing YAML frontmatter and Markdown instructions:
-
-```mdx
----
-name: pdf-processing
-description: Extract PDF text, fill forms, merge files. Use when handling PDFs.
----
-
-# PDF Processing
-
-## When to use this skill
-Use this skill when the user needs to work with PDF files...
-
-## How to extract text
-1. Use pdfplumber for text extraction...
-
-## How to fill forms
-...
-```
-
-The following frontmatter is required at the top of `SKILL.md`:
-
-- `name`: A short identifier 
-- `description`: When to use this skill
-
-The Markdown body contains the actual instructions and has no specific restrictions on structure or content.
-
-This simple format has some key advantages:
-
-- **Self-documenting**: A skill author or user can read a `SKILL.md` and understand what it does, making skills easy to audit and improve.
-
-- **Extensible**: Skills can range in complexity from just text instructions to executable code, assets, and templates.
-
-- **Portable**: Skills are just files, so they're easy to edit, version, and share.
-
-## Next steps
-
-- [View the specification](/specification) to understand the full format.
-- [Add skills support to your agent](/client-implementation/adding-skills-support) to build a compatible client.
-- [See example skills](https://github.com/anthropics/skills) on GitHub.
-- [Read authoring best practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices) for writing effective skills.
-- [Use the reference library](https://github.com/agentskills/agentskills/tree/main/skills-ref) to validate skills and generate prompt XML.