Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.mercurjs.com/llms.txt

Use this file to discover all available pages before exploring further.

​
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:
SkillWhat it doesWhen it triggers
mercur-cliGuides correct usage of CLI commands (create, init, add, search, view, diff)Working with the Mercur CLI
mercur-blocksDiscovers, evaluates, installs, and verifies blocks using blocks.json aliasesAdding or updating blocks
migration-guideAnalyzes a 1.x project and walks through migration to 2.0 step by stepUpgrading from Mercur 1.x
dashboard-page-uiEnforces correct routing, page composition, and i18n for dashboard pagesBuilding admin or vendor pages
dashboard-form-uiEnforces form structure, validation, submission guards, and UI conventionsBuilding forms in dashboards
dashboard-tab-uiEnforces tab structure, validation scope, and wizard conventionsAdding tabs to multi-step forms
medusa-ui-conformanceKeeps custom UI aligned with @medusajs/ui patterns and local wrappersAdding reusable UI components

​
Using skills

​
Invoke explicitly

Type the slash command in Claude Code: 
/mercur-blocks
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
Claude Code matches this to the 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
Each skill is a directory containing a 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

FieldRequiredPurpose
nameYesMust match directory name
descriptionYesPrimary trigger — AI uses this to decide relevance
allowed-toolsNoRestrict available tools (e.g., Read, Grep, Glob for review-only skills)
argument-hintNoHint shown in slash command menu (e.g., "[block-name]")
Start with just name and description. Add other fields only when they change runtime behavior.

​
Using skills with other AI tools

Skills ship in .claude/skills/ — this is the canonical location, tracked in git. They’re plain markdown files, so any AI coding tool that reads project-level prompts can use them.

​
OpenAI Codex

Codex reads skills from .codex/skills/. Symlink to .claude/skills/: 
mkdir -p .codex
ln -s ../.claude/skills .codex/skills
Codex picks up the same 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
Cursor rules use a similar markdown format — the skill content works as-is, though Cursor-specific frontmatter fields (like globs) can be added for file-pattern triggering.
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.