Skills
Every Mercur project created with @mercurjs/cli@latest create includes a set of skills — reusable prompt modules that teach your AI coding tool how to work with Mercur correctly.
Skills encode domain knowledge, enforce patterns, and catch common mistakes. Instead of prompting your AI with “please follow the Mercur conventions for forms”, the skill handles it automatically.
How skills work
Skills are markdown files in your project’s .claude/skills/ directory. They’re loaded by Claude Code (and compatible tools) in two ways:
- Slash command — type
/skill-name to invoke a skill explicitly
- Auto-trigger — the AI detects that your task matches a skill’s description and loads it automatically
Each skill contains rules, checklists, and workflows tailored to a specific aspect of Mercur development.
Included skills
Every project created from the Mercur starter template includes these skills:
| Skill | What it does | When it triggers |
|---|
mercur-cli | Guides correct usage of CLI commands (create, init, add, search, view, diff) | Working with the Mercur CLI |
mercur-blocks | Discovers, evaluates, installs, and verifies blocks using blocks.json aliases | Adding or updating blocks |
migration-guide | Analyzes a 1.x project and walks through migration to 2.0 step by step | Upgrading from Mercur 1.x |
dashboard-page-ui | Enforces correct routing, page composition, and i18n for dashboard pages | Building admin or vendor pages |
dashboard-form-ui | Enforces form structure, validation, submission guards, and UI conventions | Building forms in dashboards |
dashboard-tab-ui | Enforces tab structure, validation scope, and wizard conventions | Adding tabs to multi-step forms |
medusa-ui-conformance | Keeps custom UI aligned with @medusajs/ui patterns and local wrappers | Adding reusable UI components |
Using skills
Invoke explicitly
Type the slash command in Claude Code:
The skill loads its full context and guides you through the workflow.
Let it auto-trigger
Just describe your task naturally:
Add the reviews block to my project
mercur-blocks skill and activates it automatically.
Pass arguments
Some skills accept arguments:
/migration-guide /path/to/old-project
Where skills live
your-project/
└── .claude/
└── skills/
├── mercur-cli/
│ └── SKILL.md
├── mercur-blocks/
│ └── SKILL.md
├── dashboard-page-ui/
│ └── SKILL.md
├── dashboard-form-ui/
│ └── SKILL.md
├── dashboard-tab-ui/
│ └── SKILL.md
├── medusa-ui-conformance/
│ └── SKILL.md
└── migration-guide/
└── SKILL.md
SKILL.md file with frontmatter metadata and the skill content.
Creating custom skills
You can create your own skills to encode project-specific patterns and workflows.
1. Create the skill directory
mkdir -p .claude/skills/my-custom-skill
2. Write the skill file
Create .claude/skills/my-custom-skill/SKILL.md:
---
name: my-custom-skill
description: One sentence describing when this skill should trigger.
---
# My Custom Skill
Use this skill when:
- [trigger condition 1]
- [trigger condition 2]
## Rules
- [rule 1]
- [rule 2]
## Workflow
1. [step 1]
2. [step 2]
3. Key conventions
- Directory name must be
kebab-case and match the name in frontmatter
- File must be named
SKILL.md (uppercase)
- Description is the primary trigger — write it clearly so the AI knows when to activate
- Keep skills focused on one domain; split broad skills into smaller ones
Frontmatter options
| Field | Required | Purpose |
|---|
name | Yes | Must match directory name |
description | Yes | Primary trigger — AI uses this to decide relevance |
allowed-tools | No | Restrict available tools (e.g., Read, Grep, Glob for review-only skills) |
argument-hint | No | Hint shown in slash command menu (e.g., "[block-name]") |
Start with just name and description. Add other fields only when they change runtime behavior.
Skills ship in .claude/skills/ by default, but they’re plain markdown files — any AI coding tool that reads project-level prompts can use them. The recommended approach is to use a shared .ai/skills/ directory as the canonical source and symlink from each tool’s config directory.
OpenAI Codex
Codex reads skills from .codex/skills/. Symlink to the shared directory:
# Option A: symlink from .claude/skills (what ships with the template)
mkdir -p .codex
ln -s ../.claude/skills .codex/skills
# Option B: if you've set up a shared .ai/skills/ directory
mkdir -p .codex
ln -s ../.ai/skills .codex/skills
SKILL.md files and triggers them the same way.
Cursor
Cursor reads project rules from .cursor/rules/. You can convert skills to Cursor rules:
mkdir -p .cursor/rules
# Copy a skill as a Cursor rule
cp .claude/skills/mercur-blocks/SKILL.md .cursor/rules/mercur-blocks.md
globs) can be added for file-pattern triggering.
Shared directory pattern
For projects where multiple team members use different AI tools, set up a shared canonical directory:
# 1. Create shared directory
mkdir -p .ai/skills
# 2. Move skills there
mv .claude/skills/* .ai/skills/
# 3. Symlink from each tool
ln -sf ../.ai/skills .claude/skills
ln -sf ../.ai/skills .codex/skills
.ai/skills/ and every tool gets the change.
Skills are markdown — they work with any AI tool that supports project-level context. If your tool doesn’t have a conventional directory, you can paste skill content into custom instructions or system prompts.
