medusa
Medusa headless commerce - modules, workflows, API routes, admin UI
33
30%
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 topic areas but fails to describe concrete actions or provide any trigger guidance for when Claude should select this skill. It reads more like a topic tag list than a functional description, making it difficult for Claude to confidently choose this skill in a multi-skill environment.
Suggestions
Add a 'Use when...' clause with explicit triggers, e.g., 'Use when the user asks about building with Medusa, creating commerce modules, defining workflows, or customizing the Medusa admin dashboard.'
Replace the category list with specific concrete actions, e.g., 'Creates custom Medusa modules and services, defines multi-step workflows, builds API routes with middleware, and extends the admin UI with custom widgets.'
Include additional natural trigger terms and variations such as 'MedusaJS', 'e-commerce', 'storefront', 'subscribers', 'scheduled jobs', or 'Medusa v2' to improve keyword coverage.
| 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 (e.g., 'create modules', 'define workflows', 'build API routes'). | 2 / 3 |
Completeness | It partially addresses 'what' by listing topic areas but lacks any 'when' guidance. There is no 'Use when...' clause or equivalent explicit trigger guidance, and the 'what' itself is weak since it only lists categories without describing actions. | 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's missing common variations and related terms like 'e-commerce', 'storefront', 'MedusaJS', 'plugins', or 'subscribers'. | 2 / 3 |
Distinctiveness Conflict Risk | The mention of 'Medusa' specifically helps distinguish it from generic commerce or API skills. However, terms like 'modules', 'workflows', 'API routes', and 'admin UI' are very generic and could overlap with many other framework-related skills. | 2 / 3 |
Total | 7 / 12 Passed |
Implementation
27%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 Medusa tutorial rather than a focused, token-efficient skill file. While it contains useful concrete code examples for API routes, modules, and workflows, it is far too verbose — including marketing content, deployment configurations for three platforms, built-in API usage examples, and payment integration that bloat the file well beyond what's needed. The lack of any progressive disclosure or bundle files means everything is crammed into one massive document.
Suggestions
Remove the 'Why Medusa' table, Store API built-in examples, and deployment platform configs — these are documentation concerns, not skill-specific guidance. Focus on the customization patterns (modules, workflows, routes, subscribers).
Split deployment, payment integration, and Store API usage into separate referenced files (e.g., DEPLOYMENT.md, INTEGRATIONS.md) to reduce the main skill to a concise overview with clear navigation links.
Complete the placeholder implementations (ReviewModuleService methods, getReviewsForProduct) or remove them — incomplete code reduces actionability.
Add explicit validation checkpoints to the development workflow: e.g., after registering a module run `npx medusa db:sync`, after adding routes verify with a curl command.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Extremely verbose for a skill file. The 'Why Medusa' table, Store API usage examples (fetch calls), deployment configs for three platforms, payment integration, and the checklist are all things Claude already knows or can derive. This reads like a getting-started tutorial, not a concise skill reference. The 'Why Medusa' section is pure marketing copy with zero instructional value. | 1 / 3 |
Actionability | Code examples are mostly concrete and copy-paste ready (API routes, modules, workflows), but several are incomplete — the ReviewModuleService methods have empty '// Implementation' bodies, getReviewsForProduct/createReview are undefined helper functions, and the notification service is referenced without setup. The workflow example is well-structured with compensation functions though. | 2 / 3 |
Workflow Clarity | The workflow section demonstrates step sequencing with compensation/rollback, which is good. However, there are no validation checkpoints for the overall development workflow (e.g., after creating a module, run migrations; after adding routes, verify they load). The deployment section lists commands but lacks verification steps (check health endpoint, validate DB connection). The checklist at the end is a static list, not an integrated workflow. | 2 / 3 |
Progressive Disclosure | This is a monolithic wall of text (~500+ lines) with no references to external files and no bundle files to support it. Everything from quick start to deployment to payment integration is inlined. Content like deployment configs, Store API examples, and payment setup should be in separate referenced files. The skill tries to be a complete documentation site in one file. | 1 / 3 |
Total | 6 / 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
65efb33
- 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.