DEV Community

Cover image for Build a Semantic Movie Discovery App with Claude Code and Weaviate Agent Skills
Studio1 profile image Arindam Majumder
Arindam Majumder Subscriber for Studio1

Posted on

Build a Semantic Movie Discovery App with Claude Code and Weaviate Agent Skills

#mcp #rag #ai #webdev

Introduction

Versatility in agentic coding is increasing as new tools such as Model Context Protocol (MCP) servers and Agent Skills become more common. At the same time, many developers ask the same question when building AI applications: should they use MCP servers or Agent Skills? The important thing is understanding what each approach does well and choosing the one that fits your use case.

In this post, we’ll explain what MCP servers and Agent Skills are and how they differ, including architecture diagrams and technical details. In the later sections, we’ll also walk through how to use Weaviate Agent Skills with Claude Code to build a “Semantic Movie Discovery” application with several useful features.

Let’s get started!

Understanding MCP

The Model Context Protocol (MCP) is an open standard introduced by Anthropic that enables Large Language Models (LLMs) to interact with external systems such as data sources, APIs and services. MCP provides a structured way for an AI agent to connect to compliant tools through a single interface instead of requiring custom integrations for each service.

MCP Architecture

MCP Architecture

The MCP system operates on a client–server model and consists of three main components.

  • Host: the application that runs the AI model and provides the environment where the agent operates.
  • Client: the protocol connector inside the host that handles communication between the model and MCP servers.
  • Server: an external service that exposes tools, resources, or prompts that the agent can access.

MCP and Agentic Coding

Before MCP, each AI tool required custom integrations for every external service it wanted to connect to. MCP simplifies this process by introducing a shared protocol that multiple agents and tools can use.

Developers can now expose capabilities through an MCP server once and allow any compatible agent to access them without building separate integrations for each system.

Understanding Agent Skills

Agent Skills, also introduced by Anthropic, provide developers with a simple way to extend AI coding agents without running MCP servers. An Agent Skill is a structured configuration file, usually written as markdown files with YAML metadata that defines capabilities, parameter schemas and natural-language instructions describing how the agent should use those capabilities.

AI tools such as Claude Code read these files at session start and load the skills directly into the agent's working context without requiring an additional runtime.

Agent Skills with an AI tool (Claude Code)

How Agent Skills Work

  • When Claude Code detects a skill file in the project directory (typically under .claude/skills/), it loads the manifest into the agent's context at the beginning of the session.
  • The skill definition describes available capabilities, how to invoke them correctly and when to prefer one approach over another. Because the instructions are written in natural language alongside parameter schemas, the agent can reason about how to use the skill.
  • Skills are portable across repositories. If a developer commits a skill file to a repository, any collaborator who clones the project and opens it in Claude Code automatically gains access to the same capabilities without additional setup.

MCP and Agent Skills solve different problems in agent systems. MCP provides a standardized way for AI agents to connect to external tools, APIs, databases and services through a client–server architecture with structured schemas. Agent Skills extend the agent’s capabilities through configuration files that define workflows, instructions and parameter schemas without requiring a running server.

In simple terms, MCP enables agents to access external systems, while Agent Skills define how agents perform tasks or workflows within their environment.

Weaviate Agent Skills

Weaviate has released an official set of Agent Skills designed for use with Claude Code and other compatible agent-based development environments like Cursor, Antigravity, Windsurf and more. These skills provide structured access to Weaviate vector databases, allowing agents to perform common operations such as search, querying, schema inspection, data exploration and collection management.

The repository includes ready-to-use skill definitions for tasks like semantic, hybrid and keyword search, along with natural language querying through the Query Agent. It also supports workflows such as creating collections, importing data and fetching filtered results, and cookbooks. This enables agents to interact/build with Weaviate and perform multi-step retrieval and agentic tasks more effectively.

Weaviate Ecosystem Tools and Features

Agent Skills and Vector Databases

AI coding agents face difficulties when working with vector databases. Vector database APIs provide extensive capabilities, including basic “key–value” retrieval, single-vector near-text searches, multimodal near-image searches, hybrid BM25-plus-vector search, generative modules and multi-tenant system support. Without structured guidance, even a capable coding agent may produce suboptimal queries: correct syntax but the wrong search strategy, missing parameters or failure to use powerful features like the Weaviate Query Agent.

Weaviate Agent Skills address this by providing correct usage patterns, parameter recommendations and decision logic, enabling coding agents to generate production-ready code from their initial attempts.

The Weaviate Agent Skills repository is organized into two main parts:

Overview of Weaviate Agent Skills

  1. Weaviate 𝗦𝗸𝗶𝗹𝗹 (skills/weaviate): Focused scripts for tasks such as schema inspection, data ingestion and vector search. Agents use these while writing application logic or backend code.
  2. 𝗖𝗼𝗼𝗸𝗯𝗼𝗼𝗸𝘀 Skill (skills/weaviate-cookbooks): End-to-end project examples that combine tools such as FastAPI, Next.js and Weaviate to demonstrate full application workflows.

Weaviate Agent Skills work with several development environments, including Claude Code, Cursor, GitHub Copilot, VS Code and Gemini CLI. When connected to a Weaviate Cloud instance, agents can directly interact with database modules and perform search, data management and retrieval tasks.

To evaluate how effective Weaviate Agent Skills really are, let’s build a small project and see how they accelerate RAG and agentic application development with Claude Code.

Building the Semantic Movie Discovery Application

We will build a Movie Discovery App that takes a natural-language description and returns the most semantically similar movies from a Weaviate collection. In the process, we will explore Weaviate capabilities such as multimodal storage, named vector search, generative AI (RAG) and the Query Agent in action with Claude Code, showing how these Agentic tools help you build applications faster.

Prerequisites

Step 1: Project Setup

Create a movie-discovery-app folder

mkdir movie-discovery-app
Enter fullscreen mode Exit fullscreen mode

Create and activate a  Python virtual environment in the folder

cd movie-discovery-app py -m venv venv && source venv\Scripts\activate.bat
Enter fullscreen mode Exit fullscreen mode

Install Python dependencies

pip install weaviate-client==4.20.1 fastapi uvicorn[standard] openai weaviate-agents>=1.3.0 requests python-dotenv
Enter fullscreen mode Exit fullscreen mode

Install Node.js dependencies for the frontend

cd frontend && npm install
Enter fullscreen mode Exit fullscreen mode

Now, create a .env file at the project root. Add the following parameters to configure Weaviate Agent Skills with Claude Code, along with your OpenAI API key and TMDB API key.

WEAVIATE_URL=your-cluster-host-without-https
WEAVIATE_API_KEY=your-api-key
OPENAI_API_KEY=your-openai-key
TMDB API key=your-tmdb-api-key
Enter fullscreen mode Exit fullscreen mode

After signing up for Weaviate, click the Create Cluster button to start a new cluster for your use.

Image1

Click “How to Connect” to view the required Weaviate connection parameters.

Now that everything is set up, we can connect Weaviate Cloud with Claude Code by running claude in your project terminal:

Claude Code screnshot

Use the following prompt in your Claude terminal:

Write and run `check_modules.py` that connects using `weaviate.connect_to_weaviate_cloud`with `skip_init_checks=True`, loads credentials from `.env` with `python-dotenv`,
and prints the full JSON list of enabled Weaviate modules.
Run it with `venv/Scripts/python check_modules.py`."
Enter fullscreen mode Exit fullscreen mode

Step 2: Create A Weaviate Collection and Import Sample Movie Data

In this step, we create a Weaviate collection and import the movie dataset into Weaviate. The dataset contains movie metadata sourced from the TMDB API. Each entry includes: title, overview, release_date, poster_url, popularity, and other important movie fields. You can import a JSON or CSV dataset directly into Weaviate.

Run this prompt to retrieve the dataset from the TMDB API and save it to a file named movies.json.

Create a TMDB dataset JSON file, movies.json, that contains 100 movie metadata and poster URLs directly from the TMDB API.
Enter fullscreen mode Exit fullscreen mode

Afterwards, Weaviate Import Skills creates a Weaviate collection and imports the data from movies.json into the Weaviate database. Claude code activates Weaviate to perform this action when prompted with:

Import `movie.json` into a new Weaviate collection called Movie
Enter fullscreen mode Exit fullscreen mode

Claude Code

Then the data is imported

Terminal Output

Step 3: Building the FastAPI Backend and Next.js Frontend with Weaviate Cookbooks

Weaviate cookbooks enable the app to use a two-layer architecture: a FastAPI backend that exposes REST endpoints and a Next.js frontend that renders the UI. The backend connects directly to Weaviate Cloud and the Weaviate Query Agent. Weaviate cookbooks also include some frontend guidelines to communicate with the Weaviate backend over HTTP.

The app is organized into two views accessed via a collapsible sidebar:

  1. Search view: performs semantic search and RAG using Weaviate named vectors.
  2. Chat view: handles multi-turn conversations through the Weaviate Query Agent.

Our app includes the following features:

Layer Component Role
Backend backend.py (FastAPI) - REST API on port 8000/docs Routes: GET /health, GET /search, POST /ai/explain, POST /ai/plan, POST /chat
Frontend Next.js + TypeScript (port 3000) Single-page app with sidebar navigation
SearchView.tsx Semantic search (near_text), AI explanations (single_prompt), Movie Night Planner (grouped_task)
MovieCard.tsx Renders base64 poster inline, watchlist add/remove button
ChatView.tsx Multi-turn Query AI Agent chat
AppSidebar.tsx Navigation (Search/Chat), Weaviate logo + feature summary, watchlist manager with ‘.txt’ export

Use the following prompts with Claude Code to generate the backend and frontend:

Backend Prompt:

/weaviate cookbooks 

Create `backend.py`: a FastAPI app with CORS enabled for localhost:3000.
Connect to Weaviate Cloud using credentials from .env with skip_init_checks=True.
The /search endpoint should return genre and vote_average alongside title, description, release_year, and poster.
Implement these routes:  

- GET  /health                  → {"status": "ok"}  
- GET  /search?q=...&limit=3    → near_text on text_vector, return title/description/release_year/poster  
- POST /ai/explain              → generate.near_text with single_prompt  
- POST /ai/plan                 → generate.near_text with grouped_task  
- POST /chat                    → QueryAgent.ask() with full message history
Enter fullscreen mode Exit fullscreen mode

Frontend Prompt:

Using Weaviate cookbooks frontend reference, create a Next.js TypeScript app in the frontend/ folder.
MovieCard.tsx should display a star rating (vote_average) and genre tag beneath the movie title. 

Components needed:  

- page.tsx        — SidebarProvider layout, view state (search | chat)  
- SearchView.tsx  — search input, MovieCard grid, AI explain and plan buttons  
- MovieCard.tsx   — poster image, title, year, description, watchlist button  
- ChatView.tsx    — message bubbles, source citations, clear chat  
- AppSidebar.tsx  — navigation, Weaviate logo + feature list, watchlist + exportBackend base URL from NEXT_PUBLIC_BACKEND_HOST env var (default localhost:8000)

Run backend and frontend servers with: uvicorn backend:app --reload --port 800 and npm run dev
Enter fullscreen mode Exit fullscreen mode

After this, Claude Code will automatically build the app by adding relevant files and start both servers. You can start using the application immediately.

The FastAPI backend runs at http://localhost:8000/docswhile the frontend app is available at http://localhost:3000

You can also manually start both processes in separate terminals:

# Terminal 1 — Backend 
uvicorn backend:app --reload --port 8000
# Terminal 2 — Frontend
cd frontend && npm run dev
Enter fullscreen mode Exit fullscreen mode

Congratulations! You’ve completed the project without needing to do much manual configuration or coding. 🔥

Demo

So far, we have used Weaviate Agent Skills with Claude Code to build a Semantic Movie Discovery Application powered by an OpenAI API key, a TMDB API key, and Weaviate.

The Movie Discovery app we built includes the following features:

  • Semantic search: Describe a mood or theme and retrieve matching movies using vector-based search (near_text).
  • AI explanations: Generate per-movie summaries using RAG with single_prompt.
  • Movie Night Planner: Create a viewing order, snack pairings and a theme summary using grouped_task.
  • Conversational chat: Ask questions about the movie collection through a chat interface powered by the Weaviate Query Agent, with source citations.
  • Watchlist: Save movies during your session and export the list as a .txt file.

What’s Next?

You could add image-based search to find similar movies and better meet your movie choices. You could also include a hybrid search feature that incorporates keyword-heavy queries and image search.

You can take your app even further by getting up to speed with Weaviate’s latest releases and becoming familiar with features such as server-side batching, async replication improvements, Object TTL and many more.

To explore further, check out the latest Weaviate releases and join the discussion on the community forum.

Weaviant Agent Skills in Action

Weaviate modules were used in the application:

  • Text2vec-weaviate: Responsible for text embeddings.
  • Multi2multivec-weaviate: Responsible for embedding images.
  • Generative-openai: Integrates GPT directly into the query workflow.
  • Weaviate Skill: Creates a collection and imports data.
  • Weaviate Cookbooks Skill: For defining the app’s logic.
  • Weaviate Query Agent: A higher-level abstraction that accepts natural language queries, decides the best query method, executes queries, synthesizes results and returns answers.

Weaviate Agent Skills help in shipping faster and more accurate RAG applications. Backend development tasks such as schema inspection, data ingestion and search operations are automated and optimized. Ultimately, this helps developers save valuable development time.

Conclusion

Both MCP servers and Agent Skills provide useful patterns for building AI-powered applications. MCP servers are well-suited for exposing external tools and services through a standardized interface, while Agent Skills focus on guiding coding agents with structured workflows and best practices.

In this tutorial, we demonstrated how Weaviate Agent Skills can simplify development by helping Claude Code generate correct database queries, ingestion pipelines and search logic. By combining vector search, multimodal storage and generative capabilities, we built a semantic movie discovery application with minimal manual setup.

As agentic development environments continue to evolve, tools like MCP servers and Agent Skills will likely be used together. The key is understanding where each approach fits and selecting the one that best supports your application architecture.

Happy building.

Resources

Top comments (0)