// Triages GitHub issues for the Medusa repository. Use when a GitHub issue is opened or receives a new comment. Categorizes the issue, validates it, executes the correct response flow, manages labels, and closes issues when appropriate. Accepts issue number as required argument plus optional title, body, and author.
Writes and updates Medusa documentation MDX files for the book, resources, ui, user-guide, and cloud projects. Use when making documentation changes based on code diffs, adding new pages, updating existing content, or updating component examples. ALWAYS load this skill before modifying any MDX file in www/apps/.
Writes GitHub release notes for Medusa releases in the established style. Use when generating a draft release description from a list of commits and PR metadata. Covers minimal patch releases, single-highlight releases, multi-feature releases, and releases with breaking changes.
Reviews GitHub pull requests for the Medusa repository. Checks PR template compliance, contribution guidelines, code conventions, and community contribution limits. Posts a review comment and applies initial-approval or requires-more label. Use when a PR is opened or updated.
Creates Medusa documentation tutorials in two phases: first builds the tutorial feature in an example project (with planning, coding, and tests), then writes the MDX documentation. Use when creating a new how-to tutorial or integration guide for the Medusa docs. Handles both feature implementation and documentation writing, but only one phase at a time.
Adds and updates TypeDoc (TSDoc) comments to TypeScript source files in the Medusa codebase. Covers HTTP types, API routes, UI components, data models, service interfaces, JS SDK methods, abstract providers, workflow SDK functions, core-flows workflows and steps, and events. Use when adding TSDoc comments to files in packages/core/types/src/http, packages/medusa/src/api, packages/design-system/ui/src/components, packages/modules/*/src/models, packages/core/types/src, packages/core/js-sdk/src, packages/core/utils/src, packages/core/workflows-sdk/src/utils/composer, packages/core/core-flows/src, or packages/core/utils/src/core-flows/events.ts.
| name | triaging-issues |
| description | Triages GitHub issues for the Medusa repository. Use when a GitHub issue is opened or receives a new comment. Categorizes the issue, validates it, executes the correct response flow, manages labels, and closes issues when appropriate. Accepts issue number as required argument plus optional title, body, and author. |
| argument-hint | <issue_number> [title] [body] [author] |
Triage GitHub issues by categorizing them, validating content, responding appropriately, and managing labels/state.
| Argument | Required | Description |
|---|---|---|
issue_number | Yes | GitHub issue number to triage |
title | No | Issue title (fetched via script if omitted) |
body | No | Issue body (fetched via script if omitted) |
author | No | Issue author login (fetched via script if omitted) |
If title, body, or author are not provided, fetch them with:
bash scripts/get_issue.sh <issue_number>
All GitHub operations are performed via scripts in scripts/:
bash scripts/get_issue.sh <issue_number> # Fetch issue details (title, body, author, state)
bash scripts/get_comments.sh <issue_number> # Fetch all comments on the issue
bash scripts/get_labels.sh <issue_number> # Fetch current labels on the issue
bash scripts/get_linked_prs.sh <issue_number> # Fetch PRs linked to the issue (cross-ref or connected)
bash scripts/add_comment.sh <issue_number> <body> # Post a comment on the issue
bash scripts/labels.sh <issue_number> <action> <label> # Manage labels: action is "add", "edit", or "remove"
bash scripts/close_issue.sh <issue_number> # Close the issue
bash scripts/convert_to_discussion.sh <issue_number> # Convert issue to a GitHub Discussion
bash scripts/search_issues.sh <query> # Search for similar/duplicate issues
CRITICAL: Always fetch comments before doing any work to get full conversation context. Only categorize based on the original issue description, not comments. Trigger on both new issues and new comments, but always re-evaluate the original issue body for category.
Before any analysis, always run:
bash scripts/get_issue.sh <issue_number> # if issue details weren't passed as arguments
bash scripts/get_comments.sh <issue_number> # always — comments are never passed as arguments
bash scripts/get_labels.sh <issue_number> # always — current labels are never passed as arguments
After fetching context, check if any PRs are already linked to this issue:
bash scripts/get_linked_prs.sh <issue_number>
If one or more PRs are linked:
type: bug), post a short acknowledgement, and close the issue if still open. Stop.good-first-issue or help-wanted labelsreference/bug-report.md instead of soliciting contributionstype: bug, requires-team, or other applicable labelsIf no linked PRs, continue to Step 0.75.
Only applies when triggered by a new comment (not a new issue).
After fetching context, read the latest comment and assess whether it warrants triage action. Exit immediately (do nothing) if the comment is:
Only proceed with triage if the comment:
requires-more state)When in doubt, do nothing — it's better to skip unnecessary triage than to post redundant comments.
Before any categorization, search for existing issues that cover the same problem:
bash scripts/search_issues.sh "<keywords from issue title and body>"
If a matching issue is found, verify they are truly about the same problem — don't assume based on title alone. Read both issues carefully. If confirmed duplicate:
Comment template — duplicate:
This issue appears to be a duplicate of #[original_issue_number].
Please follow and comment on the original issue to keep the discussion in one place. I'm closing this one to avoid fragmentation.
If your situation is different from the original issue, please reopen and add more details explaining how it differs.
bash scripts/close_issue.sh <issue_number>
Read the issue title and body, then assign exactly one category:
| Category | When to use |
|---|---|
feature-request | User wants a new feature or enhancement that doesn't exist |
bug-report | User reports something is broken or behaving unexpectedly |
support | User needs help implementing something or understanding how to use Medusa |
docs | Issue points to missing, incorrect, or outdated documentation |
feedback | General opinion, suggestion, or experience sharing without a specific ask |
vague | Issue body is nearly empty, missing, or incomprehensible |
other | None of the above applies clearly |
Load the reference file for the assigned category and follow the detailed flow:
bug-report → Load reference/bug-report.md (complex multi-step flow)feature-request → Load reference/feature-request.mdsupport → Load reference/support.mddocs → Load reference/docs.mdfeedback, vague, other → Load reference/other-categories.md| Label | When to apply |
|---|---|
type: bug | Bug is confirmed — always apply when closing the triage on a valid bug report |
type: docs | Issue is caused by a documentation gap — apply even when the issue was originally reported as a bug |
requires-more | Issue lacks details needed to validate or reproduce |
requires-team | Critical/high priority, or needs team expertise; cannot be resolved without team review |
good-first-issue | Bug is confirmed, fix is straightforward — encourages community contribution |
help-wanted | Bug is confirmed, fix is complex — encourages community contribution |
feedback | General feedback that team will review later |
All comments posted on issues must follow these principles:
Tone — supportive and understanding:
Formatting — clear and readable:
##) to separate distinct sections in longer commentsExamples of what to avoid:
Whenever linking to Medusa docs in a comment, load reference/doc-links.md to construct the correct URL. Doc file paths in www/apps/ do not map directly to URLs — each project has its own prefix and rules.
good-first-issue or help-wanted before confirming the bug in the codebasereference/doc-links.mdtype: docs, and route to the docs flowtype: docs when the root cause is a documentation gap, even if the issue was filed as a buggood-first-issue or help-wanted when a PR is already linked to the issuereference/bug-report.md - Full bug triage flow (details check, user error, validation, priority, labels)
reference/feature-request.md - Feature existence check and response
reference/support.md - Support handling and Cloud platform exception
reference/docs.md - Documentation issue triage, fix location routing by doc type
reference/other-categories.md - Flows for: feedback, vague, other
reference/doc-links.md - URL conventions for linking to docs.medusajs.com (load when posting any doc link)