feat(mastra): add use-mastra workflow skill

[amondnet]

Summary

Adds a hand-written use-mastra workflow skill under plugins/mastra/.agents/skills/use-mastra/ that mirrors Vercel's use-ai-sdk and follows the pattern established in #159 (use-better-auth).

The skill redirects coding agents to version-accurate documentation shipped inside the mastra / @mastra/* npm packages at node_modules/<pkg>/dist/docs/SKILL.md + references/*.md, instead of relying on stale training-data APIs.

What's new

• plugins/mastra/.agents/skills/use-mastra/SKILL.md — trigger-heavy frontmatter (createWorkflow, createTool, createStep, @mastra/core, semantic recall, provider/model, etc.); sections: Prerequisites → Don't-trust-knowledge → Finding Documentation → Package Map → Building Agents & Workflows → When Typecheck Fails → Relationship to the existing mastra primer → References.
• references/packages.md — table of the 10 Mastra packages confirmed (via npm pack) to ship dist/docs/SKILL.md, plus @mastra/observability flagged as remote-only.
• references/agents-and-workflows.md — canonical recipes for agent+tools+memory, workflow+steps+.commit(), RAG pipeline; each ends with the verification command to read against dist/docs/.
• references/common-errors.md — 11 symptom → cause → fix entries (ESM config, tool-registration mismatch, missing .commit(), memory without storage, semantic recall without vector/embedder, invalid model string, suspension/resume, etc.).

What's not touched

• plugins/mastra/.agents/skills/mastra/ — the existing v2.0.0 primer installed via skills.sh from mastra-ai/skills stays byte-identical.
• plugins/mastra/skills-lock.json — unchanged.
• No new scripts, sync automation, marketplace entries, or submodules.

Versioning

Bumps plugins/mastra from 1.2.0 → 1.3.0 and prepends a [1.3.0] - 2026-04-23 entry to CHANGELOG.md matching the format used in #159.

Verification

• claude plugin validate plugins/mastra/ — ✔ passes.
• Verified via npm pack that mastra@1.6.2, @mastra/core@1.27.0, @mastra/memory@1.17.0, @mastra/rag@2.2.1, @mastra/evals@1.2.1, @mastra/deployer@1.27.0, @mastra/server@1.27.0, @mastra/pg@1.9.2, @mastra/libsql@1.9.0, @mastra/mcp@1.5.1 all ship dist/docs/SKILL.md + dist/docs/references/*.md.
• @mastra/observability@1.10.0 ships no bundled docs — flagged as remote-only in references/packages.md.
• Existing mastra skill directory has an empty git diff --stat.

Related

• Pattern source: feat(better-auth): add use-better-auth workflow skill #159 (adds use-better-auth under plugins/better-auth/.agents/skills/use-better-auth/).
• Model skill: vercel/ai use-ai-sdk.

---

Summary by cubic

Add a new use-mastra workflow skill that routes coding agents to versioned Mastra docs in node_modules and provides concise recipes and fixes. The existing mastra primer stays as-is; plugin bumped to 1.3.0.

• New Features

  • Add plugins/mastra/.agents/skills/use-mastra/ with SKILL.md and references/agents-and-workflows.md, common-errors.md, packages.md.
  • Route agents to node_modules/<pkg>/dist/docs/ for mastra and @mastra/* (except @mastra/observability, which is remote-only).
  • Update examples to use nested memory: { thread, resource } in agent.generate() and switch the vector-query recipe to createVectorQueryTool from @mastra/rag.

• Refactors

  • Add .claude/agent-memory/review-review-cubic-reviewer/* notes recording a clean cubic review pass for PR feat(mastra): add use-mastra workflow skill #161.

^{Written for commit 388bf88. Summary will update on new commits.}

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
claude-code-plugins	Ready	Preview, Comment	Apr 23, 2026 2:24pm

[gemini-code-assist]

Code Review

This pull request introduces a new use-mastra workflow skill designed to guide agents toward version-accurate documentation within node_modules. It includes detailed recipes for agents, workflows, and RAG pipelines, along with a common errors reference and a package map. Feedback indicates that the placement of these files under .agents/skills/ violates the repository style guide, which designates that path as read-only for externally managed skills. Additionally, the changelog entry for version 1.3.0 requires formatting adjustments to match the existing project style.

[cubic-dev-ai]

3 issues found across 6 files

Confidence score: 3/5

• There is a concrete user-impact risk in plugins/mastra/.agents/skills/use-mastra/references/agents-and-workflows.md: the guide still shows removed top-level threadId/resourceId instead of memory: { thread, resource } (severity 7/10, high confidence).
• The same file documents createTool() with reversed argument order (validated input should be first, execution context second), which can lead readers to implement tools incorrectly.
• The vector-query recipe currently points to createTool instead of createVectorQueryTool from @mastra/rag, so example code may fail or require rework for consumers following the docs.
• Pay close attention to plugins/mastra/.agents/skills/use-mastra/references/agents-and-workflows.md - multiple API-usage examples appear outdated or incorrect and could mislead downstream implementations.

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="plugins/mastra/.agents/skills/use-mastra/references/agents-and-workflows.md">

<violation number="1" location="plugins/mastra/.agents/skills/use-mastra/references/agents-and-workflows.md:23">
P2: Take the validated input as the first argument; execution context is the second argument in `createTool()`.</violation>

<violation number="2" location="plugins/mastra/.agents/skills/use-mastra/references/agents-and-workflows.md:56">
P1: Use `memory: { thread, resource }` here instead of the removed top-level `threadId`/`resourceId` fields.</violation>

<violation number="3" location="plugins/mastra/.agents/skills/use-mastra/references/agents-and-workflows.md:133">
P2: Use `createVectorQueryTool` from `@mastra/rag` here; `createTool` is the wrong helper for the vector-query recipe.</violation>
</file>

Architecture diagram

sequenceDiagram
    participant User
    participant AI as AI Agent (Claude Code)
    participant Skill as use-mastra Skill
    participant LocalFS as Local node_modules
    participant Remote as mastra.ai (Remote)

    User->>AI: Ask to build Agent/Workflow
    AI->>Skill: NEW: Trigger on "Mastra", "@mastra/core", etc.
    
    Note over AI,Skill: Skill redirects AI to ground knowledge in local version

    AI->>LocalFS: Verify installation (ls node_modules/@mastra/core)
    LocalFS-->>AI: Package exists
    
    AI->>LocalFS: Read installed version (package.json)
    LocalFS-->>AI: Version info (e.g., 1.27.0)

    AI->>LocalFS: NEW: Fetch bundled docs (dist/docs/SKILL.md)
    
    alt Bundled docs found
        LocalFS-->>AI: Version-accurate API & Reference MD
    else Missing or remote-only (e.g. @mastra/observability)
        AI->>Remote: Fetch fallback (https://mastra.ai/llms.txt)
        Remote-->>AI: Latest documentation
    end

    Note over AI,LocalFS: Debugging Flow (if code fails)

    AI->>Skill: NEW: Check references/common-errors.md
    Skill-->>AI: Symptom -> Cause -> Fix map
    
    AI->>LocalFS: NEW: Grep error string in dist/ source
    LocalFS-->>AI: Line numbers and context

    AI->>User: Generate version-accurate Mastra code/fix

Loading

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}