From ff86ef2ec4a347f20783aec15b93476078d7facf Mon Sep 17 00:00:00 2001 From: Jonathan Hefner Date: Sun, 25 Jan 2026 14:17:31 -0600 Subject: [PATCH] Expand Agent Skills guide Add intro explaining what Agent Skills are and link to the two skill files (`create-mcp-app`, `migrate-oai-app`). Reorganize headings and add "Invoke a Skill" and "Test Your App" sections. Update `README.md` link text and add tip to quickstart suggesting agent skills as an alternative. Co-Authored-By: Claude Opus 4.5 --- README.md | 2 +- docs/agent-skills.md | 25 +++++++++++++++++++------ docs/quickstart.md | 8 ++++---- 3 files changed, 24 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index 84e080053..d4a5826c1 100644 --- a/README.md +++ b/README.md @@ -53,7 +53,7 @@ This repository provides two [Agent Skills](https://agentskills.io/) for buildin /plugin install mcp-apps@modelcontextprotocol-ext-apps ``` -Or you can install the skills in your favorite AI coding agent by following the [skills installation guide](./docs/agent-skills.md). +For more information, including instructions for installing the skills in your favorite AI coding agent, see the [agent skills guide](./docs/agent-skills.md). ## Examples diff --git a/docs/agent-skills.md b/docs/agent-skills.md index 82a884aee..f494b49e1 100644 --- a/docs/agent-skills.md +++ b/docs/agent-skills.md @@ -2,13 +2,20 @@ title: Agent Skills --- -# Install the Skills +# Agent Skills -The MCP Apps repository provides two [Agent Skills](https://agentskills.io/) for AI coding agents: one for scaffolding MCP Apps with interactive UIs, and one for migrating from the OpenAI Apps SDK. +[Agent Skills](https://agentskills.io/) are instruction sets that guide AI coding agents through tasks. When you invoke a skill, the agent takes the lead — it asks clarifying questions, makes decisions based on your codebase, and executes the work. + +This repository provides two skills: + +- [**create-mcp-app**](https://github.com/modelcontextprotocol/ext-apps/blob/main/plugins/mcp-apps/skills/create-mcp-app/SKILL.md) — scaffolds a new MCP App with an interactive UI +- [**migrate-oai-app**](https://github.com/modelcontextprotocol/ext-apps/blob/main/plugins/mcp-apps/skills/migrate-oai-app/SKILL.md) — migrates an existing OpenAI App to the MCP Apps SDK + +## Install the Skills Choose one of the following installation methods based on your agent: -## Option 1: Claude Code Plugin +### Option 1: Claude Code Plugin Install via Claude Code: @@ -17,7 +24,7 @@ Install via Claude Code: /plugin install mcp-apps@modelcontextprotocol-ext-apps ``` -## Option 2: Vercel Skills CLI +### Option 2: Vercel Skills CLI Use the [Vercel Skills CLI](https://skills.sh/) to install skills across different AI coding agents: @@ -25,7 +32,7 @@ Use the [Vercel Skills CLI](https://skills.sh/) to install skills across differe npx skills add modelcontextprotocol/ext-apps ``` -## Option 3: Manual Installation +### Option 3: Manual Installation Clone the repository: @@ -45,9 +52,15 @@ Then copy the skills from `plugins/mcp-apps/skills/` to your agent's skills dire Ask your agent "What skills do you have?" — you should see `create-mcp-app` and `migrate-oai-app` among the available skills. -## Next Steps +## Invoke a Skill Try invoking the skills by asking your agent: - "Create an MCP App" — scaffolds a new MCP App with an interactive UI - "Migrate from OpenAI Apps SDK" — converts an existing OpenAI App to use the MCP Apps SDK + +The agent will guide you through the process, asking clarifying questions as needed. + +## Test Your App + +After creating or migrating your MCP App, see the [Testing MCP Apps](./testing-mcp-apps.md) guide to run and debug it locally. diff --git a/docs/quickstart.md b/docs/quickstart.md index 63e93713a..8146824a8 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -6,12 +6,12 @@ title: Quickstart This tutorial walks you through building an MCP App—a tool with an interactive **View** (a UI that renders inside an iframe) that displays in MCP hosts like Claude Desktop. -## What You'll Build +> [!TIP] +> Feel like vibe coding instead? Try the [MCP Apps agent skills](./agent-skills.md). -A simple app that fetches the current server time and displays it in an interactive View. You'll learn the core pattern: **MCP Apps = Tool + UI Resource**. +## What You'll Build -> [!NOTE] -> The complete example is available at [`examples/quickstart`](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/quickstart). +A simple app that fetches the current server time and displays it in an interactive View. You'll learn the core pattern: **MCP Apps = Tool + UI Resource**. The complete example is available in [`examples/quickstart`](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/quickstart). ## Prerequisites