The Architecture of Intelligent Retrieval : Part I

Recently, I was working on Agentic RAG and got fascinated by what Mastra was doing under the hood. In this part, we focus on a feature they provide called workspace, a construct that gives agents the ability to perform operations on file storage.

Project Structure

We will follow a specific folder structure and build on it iteratively as part of a larger series:

my-project/
├── workspace/              ← basePath
│   ├── docs/
│   └── skills/             ← skills folder lives here
│       └── doc-standards/
│           ├── SKILL.md
│           └── references/
│               └── writing-guide.md
├── src/
│   └── mastra/
│       └── index.ts

What Are Skills?

While setting up the workspace, I also came across the skills concept that has been getting a lot of attention. The idea is to create a hierarchy of markdown files that give the agent dynamic, structured context to work with.

In this example, SKILL.md is the entry point — the file the agent consults first. The writing-guide.md acts as a subordinate reference, consulted on demand. One of the strengths of skills in a framework like Mastra is that they remain model-agnostic, letting you focus purely on the agent you are building.

Here is how the two files differ in purpose:

Press enter or click to view image in full size

SKILL.md

This file contains broad, top-level instructions for the agent:

---name: doc-standardsdescription : Standards for reading and summarizing the project documentations 
version: 1.0.0---
# Documentation StandardsWhen answering questions about project docs:1. Always cite the source document
2. Summarize clearly and concisely
3. If unsure, say so — never fabricate
4. Check references/writing-guide.md for tone guidelines

Wiring the Skill to an Agent

Once the skill is configured, you instruct the agent to use it when formulating responses:

export const docAgent = new Agent({
  id: 'doc-agent',
  name: 'Documentation Q&A Agent',
  instructions: `You are a documentation assistant.
Use the graphQueryTool to find relevant information and relationships across documents.
Follow the doc-standards skill when formulating answers.
Always cite which document your answer comes from.`,
  model: 'openai/gpt-4o',
  tools: { graphQueryTool },
  memory: new Memory({
    options: {
      lastMessages: 10,
    },
  }),
})

writing-guide.md

The supporting reference file handles tone and formatting guidelines:

# Writing guide
- Use plain language
- Prefer bullet points for lists
- Keep answers under 200 words unless detail is requested

What’s Next

In Part 2, we will focus on the knowledge-source ingestion aspect of Agentic RAG , how documents actually get into the system for the agent to query. Thanks for reading.