Customizing Skills

The skill files generated by mxcli init are starting points. You can modify them to match your organization’s patterns, naming conventions, and architectural standards.

Skill File Location

Skills are stored in .ai-context/skills/ (universal, shared by all tools) and optionally in .claude/skills/ (Claude Code-specific).

Modifying Existing Skills

Edit any skill file to adjust the patterns the AI follows. Common customizations include:

Naming Conventions

Change the default naming patterns in generate-domain-model.md:

-- Default pattern
CREATE PERSISTENT ENTITY Module.Customer ( ... );

-- Your convention: prefix entities with 'tbl_'
CREATE PERSISTENT ENTITY Module.tbl_Customer ( ... );

Page Layout Standards

Modify create-page.md or overview-pages.md to use your organization’s standard layouts:

-- Default
CREATE PAGE Module.CustomerOverview (
  Layout: Atlas_Core.Atlas_Default
) { ... }

-- Your standard layout
CREATE PAGE Module.CustomerOverview (
  Layout: MyTheme.MainLayout
) { ... }

Security Patterns

Update manage-security.md with your standard role hierarchy:

-- Your organization's standard roles
CREATE MODULE ROLE Module.SystemAdmin DESCRIPTION 'Full system access';
CREATE MODULE ROLE Module.PowerUser DESCRIPTION 'Extended user access';
CREATE MODULE ROLE Module.StandardUser DESCRIPTION 'Normal user access';
CREATE MODULE ROLE Module.ReadOnly DESCRIPTION 'View-only access';

Adding New Skills

Create new .md files in .ai-context/skills/ for custom patterns:

.ai-context/skills/
├── write-microflows.md          # Built-in
├── create-page.md               # Built-in
├── my-api-integration.md        # Custom: your REST API patterns
├── my-approval-workflow.md      # Custom: approval workflow template
└── my-reporting-pattern.md      # Custom: standard report pages

Skill File Structure

A good skill file includes:

1. Title and purpose – what the skill covers
2. Syntax reference – the MDL syntax for the topic
3. Complete examples – working MDL that can be adapted
4. Common mistakes – pitfalls to avoid
5. Validation checklist – steps to verify correctness

Example custom skill:

# REST API Integration Pattern

## When to Use
When creating microflows that call external REST APIs.

## Pattern

\```sql
CREATE MICROFLOW Module.Call_ExternalAPI($param: String)
RETURNS String AS $response
FOLDER 'Integration'
BEGIN
    -- Your standard REST call pattern here
    ...
END;
\```

## Common Mistakes
- Forgetting error handling for HTTP failures
- Not logging the request/response for debugging

Claude Code Commands

For Claude Code specifically, you can also add slash commands in .claude/commands/mendix/:

.claude/commands/mendix/
├── create-entity.md
├── create-overview.md
└── your-custom-command.md

These appear as /mendix:your-custom-command in the Claude Code interface.