Building a docs manager

In this tutorial, you'll build a documentation manager that maintains your project's docs. It creates well-structured markdown files and keeps documentation organized while preventing accidental overwrites. You'll set up a workspace filesystem and create an agent with document management instructions. Then you'll use conversational prompts to generate and update documentation.

Prerequisites

• Node.js v22.13.0 or later installed
• An API key from a supported Model Provider
• An existing Mastra project (Follow the installation guide to set up a new project)

Set up the workspace

The workspace uses a local filesystem to manage documentation files. The agent reads and writes files within the workspace directory. In your src/mastra/index.ts file, import the Workspace and LocalFilesystem classes.

import { Mastra } from '@mastra/core'
import { resolve } from 'node:path'
import { Workspace, LocalFilesystem } from '@mastra/core/workspace'
const workspace = new Workspace({
  filesystem: new LocalFilesystem({
    basePath: resolve(import.meta.dirname, '../../workspace'),
  }),
})
export const mastra = new Mastra({
  workspace,
})

At the root of your project, create a new folder called workspace. This is where all documentation files will be stored and managed by the agent.

Add example documentation

Inside the workspace directory, create the following folders:

• docs/guides/: For how-to guides
• docs/api/: For API reference documentation
• docs/tutorials/: For step-by-step tutorials

Create workspace/docs/README.md as the documentation index:

# Project Documentation
 
Welcome to the documentation!
 
## Sections
 
- [Guides](./guides/): How-to guides
- [API](./api/): API reference
- [Tutorials](./tutorials/): Step-by-step tutorials

Add a sample guide so the agent can see the existing documentation style:

# Getting Started
 
Quickstart guide for the project.
 
## Installation
 
```bash
npm install example-package
```
 
## Quick example
 
```typescript
import { Example } from 'example-package'
 
const example = new Example()
example.run()
```

Create the docs manager

Now it's time to create the documentation manager agent. This agent will have instructions for creating and updating markdown files in the workspace. Create a new file src/mastra/agents/docs-manager.ts and define the agent:

import { Agent } from '@mastra/core/agent'
 
export const docsManager = new Agent({
  id: 'docs-manager',
  name: 'Docs Manager',
  instructions: `You are a documentation manager that creates and maintains markdown docs.
 
When creating new docs:
1. Ask for topic and target audience
2. Create well-structured markdown with clear sections
3. Include relevant code examples with syntax highlighting
4. Save in the appropriate directory:
   - /docs/guides/ for user guides and how-tos
   - /docs/api/ for API reference
   - /docs/tutorials/ for step-by-step tutorials
 
When updating existing docs:
1. ALWAYS read the file first
2. Make targeted updates without removing unrelated content
3. Preserve existing structure and formatting
 
Use kebab-case naming for files (getting-started.md).
Always explain what you're creating and why.`,
  model: 'openai/gpt-5.6-sol',
})

Define the agent by importing it inside src/mastra/index.ts and registering it with the Mastra instance:

import { Mastra } from '@mastra/core'
import { resolve } from 'node:path'
import { Workspace, LocalFilesystem } from '@mastra/core/workspace'
import { docsManager } from './agents/docs-manager'
 
const workspace = new Workspace({
  filesystem: new LocalFilesystem({
    basePath: resolve(import.meta.dirname, '../../workspace'),
  }),
})
 
export const mastra = new Mastra({
  workspace,
  agents: { docsManager },
})

Test the docs manager

Start Studio and interact with the agent to see it in action.

npm run dev

Open localhost:4111 and navigate to the docs manager.

Create a new document

Ask the agent to create a tutorial:

Create a tutorial for setting up authentication. Cover installation, configuration, and a basic example.

The agent should create a file like docs/tutorials/authentication-setup.md. Since agent responses are non-deterministic, the exact content will vary, but you should see something similar to:

# Authentication Setup
 
Learn how to add authentication to your application.
 
## Installation
 
Install the auth package:
 
```bash
npm install @example/auth
```
 
## Configuration
 
Create a config file:
 
```typescript
// auth.config.ts
export const authConfig = {
  provider: 'oauth',
  clientId: process.env.AUTH_CLIENT_ID,
  secret: process.env.AUTH_SECRET,
}
```
 
## Basic example
 
```typescript
import { createAuth } from '@example/auth'
import { authConfig } from './auth.config'
 
const auth = createAuth(authConfig)
 
app.get('/protected', auth.requireAuth(), (req, res) => {
  res.json({ user: req.user })
})
```

Update an existing document

Try updating an existing document:

Update the getting started guide to include a section on configuration after the Quick Example

The agent should read the existing getting-started.md file and find the right insertion point. It should add the new section without disrupting existing content.

Organize documentation

Ask the agent to create an index:

List all tutorial files and create an index page that links to all of them

The agent should create a file like /docs/tutorials/index.md that links to all available tutorials.

Next steps

You can extend this manager to:

• Add BM25 or vector search to find relevant documentation
• Create skills for documentation templates
• Build automated doc generation from source code
• Integrate with GitHub to update docs on commits
• Add validation to check links and formatting