Skip to main content
skill CX Codex

espocrm — Claude Code skill: what it does, how to install

EspoCRM development guide skill. Keeps assistants aligned with metadata architecture, EntityManager queries, and service layers.

MIT 202 installs ★ 80 updated 2026-07-18

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add bobmatnyc/claude-mpm-skills --skill espocrm -a claude-code
Open on GitHub

What espocrm does

This skill guides coding assistants through custom module and extension development for EspoCRM 7.4 and newer. It enforces platform architecture where layouts and schemas live in JSON metadata, database queries run via ORM EntityManager, and business logic stays isolated in Service classes.

The reference material covers custom field types, lifecycle hooks based on core interfaces (BeforeSave, AfterSave), SelectBuilder queries, and API endpoints. Direct dependency injection replaces raw container passing.

Any metadata update under custom/Espo/Modules/{ModuleName}/Resources/metadata/ breaks expected output until you run bin/command rebuild.

What it helps with

  • scaffold a custom EspoCRM module or entity
  • implement business actions inside Service classes
  • write lifecycle event hooks using proper interfaces
  • build complex database filters with SelectBuilder
  • prepare an extension package with an install manifest

Example prompts for the agent

  • Create a custom Invoice entity in a new EspoCRM module
  • Write an AfterSave hook for Contact that reacts to updated emails
  • Construct a SelectBuilder query with joins for active accounts

How to install espocrm

1Skills CLI (Vercel)

npx skills add bobmatnyc/claude-mpm-skills --skill espocrm -a claude-code

2Manually: put the files in place

~/.claude/skills/espocrm/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/espocrm/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about espocrm

How to install espocrm in Claude Code?

Run npx skills add bobmatnyc/claude-mpm-skills --skill espocrm -a claude-code in your terminal. The rule file will be placed in ~/.claude/skills/espocrm/SKILL.md.

What does the espocrm skill do?

It enforces EspoCRM development patterns, ensuring data operations use EntityManager while business routines remain inside dedicated service classes.

Why does the skill reject raw PDO access?

Direct PDO queries bypass entity events, metadata validation, and repository abstractions. EspoCRM requires using EntityManager for database interactions.

Source text

SKILL.md · MIT
---
name: espocrm
description: Comprehensive guide for developing on EspoCRM - metadata-driven CRM with service layer architecture
user-invocable: false
disable-model-invocation: true
version: 1.2.0
updated: "2026-06-15"
category: development
author: Claude MPM Team
license: MIT
progressive_disclosure:
  entry_point:
    summary: "Metadata-driven CRM development using service layer, ORM EntityManager, and hook-based business logic"
    when_to_use: "When developing custom modules, entities, hooks, or integrations for EspoCRM"
    quick_start: "1. Understand metadata-driven architecture 2. Use EntityManager for data access 3. Implement business logic in Services 4. Register hooks for lifecycle events 5. Rebuild cache after changes"
  references:
    - architecture.md
    - development-workflow.md
    - hooks-and-services.md
    - frontend-customization.md
    - common-tasks.md
    - testing-debugging.md
    - select-builder.md
    - api-actions.md
    - custom-field-types.md
    - extension-packages.md
    - php-quality-antipatterns.md
context_limit: 800
tags:
  - espocrm
  - php
  - crm
  - metadata-driven
  - orm
requires_tools: []
---

# EspoCRM Development

## Overview

EspoCRM is a metadata-driven CRM platform where configuration lives in JSON files, business logic belongs in Services, and data access happens through ORM EntityManager. This skill enforces architectural patterns to prevent common mistakes like passing Container dependencies, bypassing the service layer, or implementing business logic in hooks.

## When to Use This Skill

Activate when developing custom EspoCRM modules, entities, relationships, hooks, services, API endpoints, or integrations. **Use especially when:** working with ORM (EntityManager required), implementing business logic (belongs in Services), creating hooks (use interfaces), modifying metadata (requires cache rebuild), building custom field types, creating complex queries with SelectBuilder, implementing custom API actions, or packaging extensions.

## The Iron Law

**BUSINESS LOGIC IN SERVICES, NOT HOOKS | DATA ACCESS VIA ENTITYMANAGER, NEVER DIRECT PDO | NEVER PASS CONTAINER AS DEPENDENCY**

Accessing Container directly or writing business logic in hooks violates architecture.

## Core Architecture Principles

1. **Metadata-Driven**: Entity definitions, layouts, field configs live in JSON
2. **Service Layer**: All business logic implemented in Service classes
3. **ORM EntityManager**: Central access point for all database operations
4. **Dependency Injection**: Constructor injection, never pass Container
5. **Hook System**: Lifecycle events for validation and side effects (not business logic)
6. **Repository Pattern**: Entities accessed through repositories

## Quick Start

1. **Setup Development Environment** - Use ext-template, work in `src/` directory (EspoCRM 7.4+), understand metadata structure: `custom/Espo/Modules/{ModuleName}/Resources/metadata/`

2. **Access Data with EntityManager**
   ```php
   use Espo\ORM\EntityManager;

   public function __construct(private EntityManager $entityManager) {}

   // Find entity
   $account = $this->entityManager->getEntityById('Account', $id);

   // Query with conditions
   $collection = $this->entityManager
       ->getRDBRepository('Contact')
       ->where(['accountId' => $accountId])
       ->find();
   ```

3. **Implement Business Logic in Services**
   ```php
   namespace Espo\Modules\MyModule\Services;

   use Espo\Services\Record;

   class MyEntity extends Record {
       public function customAction(string $id, object $data): object {
           // Business logic here
           $entity = $this->entityManager->getEntityById($this->entityType, $id);
           // ... process ...
           $this->entityManager->saveEntity($entity);
           return $entity;
       }
   }
   ```

4. **Register Hooks for Lifecycle Events**
   ```php
   namespace Espo\Modules\MyModule\Hooks\Account;

   use Espo\ORM\Entity;
   use Espo\Core\Hook\Hook\BeforeSave;

   class MyHook implements BeforeSave {
       public function beforeSave(Entity $entity, array $options): void {
           // Validation or side effects only
           if ($entity->isAttributeChanged('status')) {
               // React to changes
           }
       }
   }
   ```

5. **Rebuild Cache After Changes**
   ```bash
   bin/command rebuild
   ```

## Hook Types (Interfaces)

EspoCRM provides 7 hook types - ALWAYS use interfaces: `BeforeSave` (validation before save), `AfterSave` (side effects after save), `BeforeRemove` (validation before delete), `AfterRemove` (cleanup after delete), `AfterRelate` (relationship creation), `AfterUnrelate` (relationship removal), `AfterMassRelate` (bulk relationship operations).

## Navigation

### Core Concepts
- **[Architecture](references/architecture.md)**: Metadata system, ORM, DI container, repository pattern, and core architectural patterns
- **[Development Workflow](references/development-workflow.md)**: Module creation, custom entities, fields, APIs, and extension development process
- **[Hooks and Services](references/hooks-and-services.md)**: Service layer implementation, hook types, dependency injection, and business logic patterns

### Advanced Topics
- **[SelectBuilder](references/select-builder.md)**: Advanced querying with SelectBuilder - complex queries, joins, aggregations, and query optimization
- **[API Actions](references/api-actions.md)**: Creating custom API endpoints - action handlers, request/response patterns, and authentication
- **[Custom Field Types](references/custom-field-types.md)**: Building custom field types - backend, frontend, metadata, and integration

### UI and Integration
- **[Frontend Customization](references/frontend-customization.md)**: View system, client-side development, and UI customization
- **[Common Tasks](references/common-tasks.md)**: Scheduled jobs, emails, PDFs, ACL, workflows, and integration patterns
- **[Extension Packages](references/extension-packages.md)**: Packaging and distributing extensions - manifest files, installation, and versioning

### Quality Assurance
- **[Testing and Debugging](references/testing-debugging.md)**: Unit tests, debugging techniques, performance optimization, and common pitfalls
- **[PHP Quality Anti-Patterns](references/php-quality-antipatterns.md)**: Language-level robustness/changeability defects — PHP4 constructor naming, uppercased control keywords, `goto`, and empty `catch` blocks, with compliant examples (derived from CAST Highlight code quality indicators, https://doc.casthighlight.com/)

## Key Patterns

**Correct Pattern:**
```php
✅ Service with injected dependencies
✅ EntityManager for data access
✅ Hooks using interfaces
✅ Type declarations on all methods
✅ Exceptions for error handling
```

**Incorrect Patterns:**
```php
❌ Passing Container as dependency
❌ Direct PDO database access
❌ Business logic in hooks
❌ Hook base classes instead of interfaces
❌ Missing type declarations
```

## Common Mistakes to Avoid

- **Never pass Container** - Inject specific dependencies instead
- **Don't bypass EntityManager** - Use ORM, not raw queries
- **Business logic doesn't belong in hooks** - Use Services
- **Always rebuild cache** - After metadata changes (`bin/command rebuild`)
- **Use interfaces for hooks** - Not base classes
- **Type everything** - PHP 7.4+ requires type declarations
- **Throw exceptions** - Don't return booleans for errors

## Integration with Other Skills

- **systematic-debugging**: Debug EspoCRM issues using logs and step debugging
- **verification-before-completion**: Always test with cache rebuild before claiming complete
- **test-driven-development**: Write unit tests for Services and hooks

## The Bottom Line

**EspoCRM is metadata-driven with a service layer architecture.**

Understand the metadata system. Use EntityManager for data. Implement business logic in Services. Use hooks for lifecycle events only. Rebuild cache after changes.

This is the EspoCRM way.

© Claude MPM Team · MIT · bobmatnyc/claude-mpm-skills

Similar skills

All skills for Backend and APIs →

From the same set143

The whole set →
nextjs Maps Next.js environment variables across .env* files, shows which one wins, and covers Vercel deployment. CX Codex +1 212installs tauri A skill for advanced Tauri event patterns: bidirectional communication, streaming data, and window-to-window messaging. Use it when building desktop apps that need real-time updates between Rust backend and TypeScript frontend. CX Codex +1 210installs react-advanced react-advanced is a Claude Code skill for React 19 development, covering React Compiler adoption, Actions, concurrent rendering, and modern component architecture. CX Codex +1 209installs react-hooks-composition react-hooks-composition — a skill with patterns for composing React hooks around SWR, debounced search, and context providers. Use it when building data-fetching hooks or managing async UI states. CX Codex +1 206installs code-quality-scoring code-quality-scoring scores codebase health, technical debt remediation effort, and cloud readiness. Useful when assessing entire applications before refactoring. CX Codex +1 206installs anthropic Reference material for the official Anthropic SDK: messages, streaming, tool use, image input. Useful when you wire Claude into an app. CX Codex +1 204installs react-state-machine This Claude Code skill helps design React state machines with XState v5. It covers complex async flows, multi-step forms, and interfaces with tangled boolean flags. CX Codex +1 201installs code-production-process The code-production-process skill for Claude Code runs six-stage quality checks on non-trivial changes: over 50 lines of code or multiple source files. CX Codex +1 201installs

Project sponsors

Companies that keep this analytics open