home / skills / mastra-ai / mastra / mastra-docs

mastra-docs skill

safe

This skill enforces Mastra documentation standards, ensuring clear, consistent guides and references across docs, guides, and reference sections.

npx playbooks add skill mastra-ai/mastra --skill mastra-docs

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

2.0 KB

---
name: mastra-docs
description: Documentation guidelines for Mastra. This skill should be used when writing or editing documentation for Mastra. Triggers on tasks involving documentation creation or updates.
---

# Mastra Documentation Guidelines

Instructions and styleguides for writing and maintaining Mastra documentation. This skill should be used whenever creating or updating documentation for Mastra to ensure consistency, clarity, and quality across all docs.

## Scope

- `@docs/` - This folder contains the source code and contents of the documentation site. All documentation for Mastra should be created and maintained here.
- `@docs/src/content/en/` - This subfolder contains the actual markdown files for the documentation site, organized into `docs/`, `guides/`, and `reference/` sections. The `models/` subfolder contains auto-generated documentation for model providers and should not be edited manually.

## Styleguides

Follow the general styleguide at `@docs/styleguides/STYLEGUIDE.md` for all documentation. Additionally, refer to these specific styleguides when writing different types of documentation:

- `@docs/styleguides/DOC.md` - For any file inside `@docs/src/content/en/docs/`
- For any file inside `@docs/src/content/en/guides/` choose the correct styleguide based on content:
  - `@docs/styleguides/GUIDE_QUICKSTART.md` - For quickstart guides that get the reader to a working result as fast as possible with a specific library/framework.
  - `@docs/styleguides/GUIDE_TUTORIAL.md` - For tutorial guides that teach the reader how to build something specific with Mastra, going deeper into concepts.
  - `@docs/styleguides/GUIDE_INTEGRATION.md` - For integration guides that provide a comprehensive reference for using Mastra with a specific external library or ecosystem.
  - `@docs/styleguides/GUIDE_DEPLOYMENT.md` - For deployment guides that walk the reader through deploying their Mastra application to a specific platform.
- `@docs/styleguides/REFERENCE.md` - For any file inside `@docs/src/content/en/reference/`

Overview

This skill provides documentation guidelines and templates for writing and maintaining Mastra docs. It centralizes scope, folder conventions, and specific styleguides so documentation is consistent, accurate, and easy to review. Use it whenever you create or update content for the Mastra docs site.

How this skill works

It inspects the documentation task and maps the content to the correct folder and styleguide rules. The skill enforces where files must live, which styleguide to apply (docs, guides, or reference), and flags areas that must not be edited manually, such as autogenerated model docs. It guides structure, tone, and procedural steps for publishing changes.

When to use it

Creating a new documentation page for Mastra features or APIs
Updating existing guides, tutorials, or reference entries
Converting user-contributed content into the official docs format
Preparing docs for release or a docs site deployment
Reviewing pull requests that modify files under the docs hierarchy

Best practices

Place all docs under @docs/src/content/en/, organized into docs/, guides/, or reference/
Select the specific styleguide before writing: DOC.md for docs, GUIDE_* for guides, REFERENCE.md for reference
Do not edit autogenerated files under models/; update the source generator instead
Keep quickstarts concise and actionable; use GUIDE_QUICKSTART.md for those
Use tutorials to teach workflows with deeper explanations and examples
Follow the central styleguide for tone, formatting, and accessibility

Example use cases

Authoring a quickstart that gets a Mastra app running with TypeScript and Next.js
Writing an integration guide for using Mastra with an external model provider
Updating API reference after a TypeScript interface changes
Converting a community tutorial into the official guides format
Drafting deployment instructions for hosting Mastra apps on a cloud platform

FAQ

Where should I add a new how-to guide?

Add it under @docs/src/content/en/guides/ and choose the appropriate GUIDE_* styleguide based on whether it’s a quickstart, tutorial, integration, or deployment guide.

Can I edit autogenerated model docs?

No. Files in the models/ subfolder are autogenerated; modify the generator or the source metadata instead of editing those files directly.