medusa
Medusa headless commerce - modules, workflows, API routes, admin UI
48
37%
Does it follow best practices?
Impact
Pending
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 lacks concrete actions and any 'when to use' guidance. It reads more like a tag list than a functional description, making it difficult for Claude to confidently select this skill over others in a large skill set.
Suggestions
Add a 'Use when...' clause specifying triggers, e.g., 'Use when the user asks about building with Medusa, creating custom commerce modules, defining Medusa 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 backend', 'storefront API', 'subscribers', or 'custom plugins'.
| 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', 'define workflows', or 'build API endpoints'. | 2 / 3 |
Completeness | It partially addresses 'what' (Medusa commerce topics) but provides no 'when' guidance at all. There is no 'Use when...' clause or equivalent explicit trigger guidance, and per the rubric, a missing 'Use when' clause should cap completeness at 2, but the 'what' is also weak (just listing categories), so this falls to 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', 'subscribers', 'plugins', or specific file patterns. | 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-specific skills. | 2 / 3 |
Total | 7 / 12 Passed |
Implementation
42%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
The skill is highly actionable with excellent, executable code examples covering the full Medusa development surface area. However, it is severely bloated — it reads more like comprehensive documentation than a focused skill file, with marketing content, exhaustive reference tables, and deployment configs that should be split into separate files. The lack of progressive disclosure and excessive verbosity significantly undermine its effectiveness as a context-window-efficient skill.
Suggestions
Reduce the main file to a concise overview (~100 lines) covering project structure, config, and one example each of API routes, modules, and workflows, then link to separate files like MODULES.md, WORKFLOWS.md, ADMIN-UI.md, DEPLOYMENT.md for detailed content.
Remove the 'Why Medusa' marketing table and any explanatory text that describes what Medusa is rather than how to use it — Claude doesn't need to be sold on the framework.
Add explicit validation checkpoints to multi-step processes: after database migration, after module registration, and after deployment steps (e.g., 'Verify: curl http://localhost:9000/health').
Cut the Store API frontend fetch examples and deployment configs (Docker, Render, Railway) into referenced files — these are reference material, not core skill instructions.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Extremely verbose at ~500+ lines. Includes a 'Why Medusa' marketing table, explains basic concepts like what headless means, lists common events Claude already knows, and provides extensive boilerplate (Docker, Render YAML, Railway CLI) that inflates token cost without adding unique instructional value. The 'Features/Benefits' table is pure marketing copy. | 1 / 3 |
Actionability | Provides fully executable, copy-paste ready code examples throughout — API routes, modules, workflows, subscribers, admin widgets, deployment configs, and CLI commands are all concrete and complete with proper TypeScript types and file paths. | 3 / 3 |
Workflow Clarity | The workflow section demonstrates step creation with compensation/rollback, which is good. However, there are no validation checkpoints for the setup process, deployment steps lack verification (e.g., checking if migrations succeeded), and the overall development workflow (create module → register → use) lacks explicit validation steps between stages. | 2 / 3 |
Progressive Disclosure | Everything is crammed into a single monolithic file with no references to external files for detailed content. The Store API section, deployment configs, payment integration, and admin UI customization could all be separate referenced documents. This is a wall of text that would be better served by a concise overview linking to topic-specific files. | 1 / 3 |
Total | 7 / 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 (768 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
d4ddb03
- 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.