# The Architecture of Intelligent Retrieval : Part I

- **Authors:** Vivek Singh
- **Published:** 2026-02-28
- **Updated:** 2026-03-17T11:53:26.662Z
- **Tags:** ai, automation

---

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](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview) 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

![](https://miro.medium.com/v2/resize:fit:1400/1*i4CZwfo-nFLwpuomU1AADQ.png)

## 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.



---

## Frequently asked questions

### What is a workspace in the context of Mastra and Agentic RAG?

A workspace is a construct that lets agents perform operations over a file storage base path, enabling access to documents and skill files.

### What are skills and why are they represented as markdown files?

Skills are a hierarchy of markdown files that provide dynamic, structured context for an agent. Markdown keeps them simple, inspectable, and model-agnostic.

### What is the role of SKILL.md compared to a reference file like writing-guide.md?

SKILL.md is the entry point with broad, top-level instructions the agent should follow. Reference files are subordinate documents consulted as needed for specific guidance.

### How do you wire a skill into an agent configuration?

You reference the skill in the agent instructions (for example, “Follow the doc-standards skill”) and ensure the agent has tools (like graphQueryTool) to retrieve relevant documents.

### What does the next part of the series cover?

Part 2 focuses on knowledge-source ingestion for Agentic RAG: how documents are ingested so the agent can query them.



---

> **Originally written here:** [https://medium.com/@vivek_the_learner_here/rag-is-not-dead-if-you-do-it-right-part-1-1ea58ce022fd](https://medium.com/@vivek_the_learner_here/rag-is-not-dead-if-you-do-it-right-part-1-1ea58ce022fd)