medusa
Medusa headless commerce - modules, workflows, API routes, admin UI
29
23%
Does it follow best practices?
Impact
—
No eval scenarios have been run
Risky
Do not use without reviewing
Optimize this skill with Tessl
npx tessl skill review --optimize ./skills/medusa/SKILL.mdQuality
Discovery
32%Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.
The description identifies the domain (Medusa headless commerce) and lists broad capability areas, but lacks concrete actions and any explicit trigger guidance ('Use when...'). It reads more like a topic tag list than a functional skill description, making it difficult for Claude to confidently select this skill over others.
Suggestions
Add a 'Use when...' clause specifying triggers, e.g., 'Use when the user asks about building with Medusa, creating custom commerce modules, defining workflows, or extending the Medusa admin UI.'
Replace the category list with specific concrete actions, e.g., 'Creates custom Medusa modules, defines multi-step workflows, builds API routes for storefronts, and extends the admin dashboard with custom widgets.'
Include additional natural trigger terms users might say, such as 'MedusaJS', 'e-commerce', 'storefront', 'online store', or 'commerce backend'.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Names the domain (Medusa headless commerce) and lists some areas (modules, workflows, API routes, admin UI), but these are categories rather than concrete actions. It doesn't describe what specific actions are performed, like 'create custom modules' or 'build API routes'. | 2 / 3 |
Completeness | It partially answers 'what' (Medusa-related areas) but provides no 'when' clause or explicit trigger guidance. Per the rubric, a missing 'Use when...' clause caps completeness at 2, and since the 'what' is also weak (just listing categories), this scores a 1. | 1 / 3 |
Trigger Term Quality | Includes relevant keywords like 'Medusa', 'headless commerce', 'modules', 'workflows', 'API routes', and 'admin UI' that users might mention. However, it misses common variations like 'e-commerce', 'storefront', 'MedusaJS', 'plugins', or 'checkout'. | 2 / 3 |
Distinctiveness Conflict Risk | 'Medusa headless commerce' is a fairly specific domain that distinguishes it from generic commerce or other e-commerce platforms. However, terms like 'modules', 'workflows', 'API routes', and 'admin UI' are very generic and could overlap with skills for other frameworks. | 2 / 3 |
Total | 7 / 12 Passed |
Implementation
14%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This skill reads as a comprehensive but verbose Medusa documentation mirror rather than a focused, actionable skill for Claude. It includes marketing content ('Why Medusa'), explains concepts Claude already knows, and dumps extensive reference material inline without progressive disclosure. The code examples are mostly concrete but several contain placeholder implementations, and the document lacks operational workflows with validation checkpoints for multi-step processes like module creation or deployment.
Suggestions
Cut the content by 60-70%: remove the 'Why Medusa' table, common events reference table, widget zones table, and Store API examples (Claude can look these up). Focus on patterns and gotchas Claude wouldn't know.
Split into multiple files: keep SKILL.md as a concise overview (~100 lines) with references to separate files like MODULES.md, WORKFLOWS.md, API-ROUTES.md, and DEPLOYMENT.md.
Add explicit multi-step workflows with validation: e.g., 'Creating a custom module: 1. Create service file → 2. Create index.ts → 3. Register in medusa-config.ts → 4. Run `npx medusa db:migrate` → 5. Verify: hit API endpoint to confirm module resolves'.
Complete the placeholder code examples (ReviewModuleService methods, getReviewsForProduct) or remove them — incomplete examples reduce actionability.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Extremely verbose at ~500+ lines. Includes a 'Why Medusa' marketing table, explains basic concepts (what headless means, what open source is), lists common events Claude already knows, and provides extensive boilerplate that could be in separate reference files. The 'Quick Start' section explains what `npx create-medusa-app` creates with inline comments. Much of this is documentation replication rather than targeted skill instruction. | 1 / 3 |
Actionability | Contains many concrete code examples with proper TypeScript and file paths, which is good. However, several examples are incomplete (e.g., ReviewModuleService methods have `// Implementation` placeholders, `getReviewsForProduct` and `createReview` are undefined functions). The skill reads more like a reference manual than actionable instructions for specific tasks Claude should perform. | 2 / 3 |
Workflow Clarity | No clear multi-step workflows with validation checkpoints. The deployment section lists commands without verification steps. Module creation spans multiple files but lacks a sequenced process with validation (e.g., no 'run migrations after adding module', no 'verify module is registered'). The checklist at the end is a static list, not an operational workflow. Complex operations like payment integration lack error handling or verification steps. | 1 / 3 |
Progressive Disclosure | Monolithic wall of text with no references to external files despite the content clearly warranting separation (API reference, deployment guides, module creation guides could each be separate files). Everything is inlined into one massive document. No bundle files exist to support progressive disclosure, and the skill doesn't attempt to organize content across multiple files. | 1 / 3 |
Total | 5 / 12 Passed |
Validation
81%Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.
Validation — 9 / 11 Passed
Validation for skill structure
| Criteria | Description | Result |
|---|---|---|
skill_md_line_count | SKILL.md is long (767 lines); consider splitting into references/ and linking | Warning |
frontmatter_unknown_keys | Unknown frontmatter key(s) found; consider removing or moving to metadata | Warning |
Total | 9 / 11 Passed | |
- Repository
- alinaqi/claude-bootstrap
- Commit
7e5f7a2
- Reviewed
Table of Contents
Is this your skill?
If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.