> For the complete documentation index, see [llms.txt](https://docs.mikopbx.com/mikopbx-development/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.mikopbx.com/mikopbx-development/ai-assisted-development/using-the-skill.md).

# Using the skill

The `/mikopbx-module` skill turns a natural-language description into a complete, convention-correct MikoPBX module. It runs in one of three modes — create a new module, augment an existing one, or optimize one against the reference standards — and it works best when you feed it the *problem* rather than a file list. This page shows how to prompt it, what questions it will ask, and how the words you use map to the code it generates.

For the bigger picture see [What the skill is](/mikopbx-development/ai-assisted-development/ai-assisted-development.md); for the file inventory each recipe produces see [What it generates](/mikopbx-development/ai-assisted-development/what-it-generates.md).

{% hint style="info" %}
The skill is defined in `Core/.claude/skills/mikopbx-module/SKILL.md` and its recipe specifications live in `Core/.claude/skills/mikopbx-module/reference/recipes.md`. Everything on this page traces back to those two files.
{% endhint %}

## How the skill activates

The skill recognizes both an explicit invocation and a set of natural-language triggers. From `SKILL.md` ("Task Activation Patterns"):

* `/mikopbx-module ...` — explicit invocation
* "Create module ..." / "Создай модуль ..."
* "Generate module ..." / "Сгенерируй модуль ..."
* "Add to module ..." / "Добавь в модуль ..."
* "Optimize module ..." / "Оптимизируй модуль ..."
* "How to make module ..." / "Как сделать модуль ..."
* "Improve module ..." / "Доработай модуль ..."

The verb you choose selects the mode: *create/generate* → Mode 1, *add/improve* → Mode 2, *optimize* → Mode 3.

## Good prompting patterns

### State the problem, not the file list

The discovery dialog (Mode 1, Phase 1) parses your description to infer purpose, name, and the set of recipes to apply. Give it the *behavior* you want and let it choose the structure.

{% tabs %}
{% tab title="Good" %}

> Create a module that blocks inbound calls from a configurable list of phone numbers. Admins manage the list on a settings page, and an external system can sync numbers over a REST API.

This tells the skill: it needs a settings model, a web page (`ui`), a REST endpoint (`rest-api`), and call interception (`dialplan` + `agi`). All four recipes flow from one sentence.
{% endtab %}

{% tab title="Weak" %}

> Make me a `BlackListConf.php` and a `BlackListNumbers.php` and a controller.

Naming files by hand bypasses the recipe selection. You lose the auto-discovery, the matching providers, the JS/CSS pair, and the post-generation checks — and you will likely miss a file the recipe would have created for you.
{% endtab %}
{% endtabs %}

### Use trigger vocabulary that maps to recipes

The skill selects recipes from keywords in your description. Use the words on the left and the recipe on the right is added automatically. This table is the recipe-selection trigger table from `SKILL.md` (Mode 1, Phase 1, step 4):

| Recipe          | Trigger words / signals                                                        |
| --------------- | ------------------------------------------------------------------------------ |
| `base` (always) | —                                                                              |
| `ui`            | settings, page, form, interface, UI / настройки, страница, форма, интерфейс    |
| `rest-api`      | API, REST, endpoint, CRUD / эндпоинт                                           |
| `dialplan`      | calls, routing, IVR, incoming, outgoing / звонки, маршрут, входящие, исходящие |
| `agi`           | AGI, script, lookup, CallerID, "before dial" / скрипт, перед набором           |
| `workers`       | background, worker, queue, events / фоновый, воркер, очередь, события          |
| `firewall`      | firewall, port, fail2ban, security / порт, фаервол, безопасность               |
| `acl`           | ACL, permissions, roles, access / доступ, права, роли                          |
| `system`        | cron, nginx, scheduled, periodic / периодический, запуск                       |

`base` is always included — it generates `module.json`, `Setup/PbxExtensionSetup.php`, at least one model under `Models/`, the `Lib/{Feature}Conf.php` config class, and `Messages/ru.php`.

{% hint style="success" %}
**Running example.** "A module that **blocks** inbound **calls** from numbers on a managed **list**, with a **settings page** and a **REST** sync **endpoint**" selects `base + ui + rest-api + dialplan + agi`. That is exactly the recipe set the skill reports for **ModuleBlackList** in the sample run inside `SKILL.md` (Phase 4 report).
{% endhint %}

### Let naming flow from the feature name

Do not hand-name every class. Give the skill a feature concept — "BlackList" — and it derives every identifier from the naming-conventions table in `SKILL.md`:

| Entity             | Pattern                     | ModuleBlackList value         |
| ------------------ | --------------------------- | ----------------------------- |
| Module ID          | `Module{Feature}`           | `ModuleBlackList`             |
| Namespace          | `Modules\{ModuleID}\...`    | `Modules\ModuleBlackList\Lib` |
| Config class       | `{Feature}Conf`             | `BlackListConf`               |
| Main class         | `{Feature}Main`             | `BlackListMain`               |
| Model              | `{Entity}`                  | `BlackListNumbers`            |
| DB table           | `m_{Entity}`                | `m_BlackListNumbers`          |
| Controller         | `Module{Feature}Controller` | `ModuleBlackListController`   |
| Worker             | `Worker{Feature}{Type}`     | `WorkerBlackListAMI`          |
| JS file            | `module-{kebab-case}`       | `module-black-list.js`        |
| CSS file           | `module-{kebab-case}`       | `module-black-list.css`       |
| Translation prefix | `module_{feature}_`         | `module_black_list_`          |

If you supply only "BlackList", the skill proposes `ModuleBlackList` and every dependent name follows. Override a single name only if you have a strong reason — the convention is what keeps the module consistent with the Core and with other modules.

### Answer discovery questions precisely

The skill is instructed to **ask many questions** rather than guess. Short, decisive answers keep the dialog fast. If asked "Will the module have its own settings page in the admin panel?" answer "Yes, one page listing the blocked numbers with add/remove" — not just "yes" — so the skill can shape the form and view correctly.

### Confirm the plan before generation

Mode 1, Phase 1 ends with **plan confirmation**: the skill presents the proposed structure (location, recipes, file list) and waits for your approval before writing anything. Read it. This is the cheap moment to add a missing recipe or correct the location — adjusting now is one sentence, adjusting after generation means editing files.

## Mode 1: the discovery dialog, step by step

Mode 1 ("Create New Module") runs four phases. Phase 1 is the dialog you steer; the rest are mechanical. The dialog order from `SKILL.md` is:

1. **Purpose** — what problem the module solves. Inferred from your description; the skill confirms it back to you.
2. **Name** — the skill suggests `Module{Feature}` (e.g. `ModuleBlackList`) following the conventions above.
3. **Location** — you choose where the module lives:
   * `Extensions/` — production modules.
   * `Extensions/EXAMPLES/{Category}/` — example / learning modules (categories such as `WebInterface`, `REST-API`, `AMI`).
4. **Recipes** — the skill proposes the recipe set using the trigger table, and asks clarifying questions like "Should the module react to call events?" or "Is there data to store in the database?"
5. **Plan confirmation** — the skill prints the location, recipes, and file list and waits for your "go".

```
You: Create a module that blocks inbound calls from a list of numbers,
     with a settings page and a REST API to sync the list.

Skill: Purpose — block inbound calls from a managed deny-list. Correct?
You:   Yes.

Skill: Suggested name: ModuleBlackList. OK?
You:   Yes.

Skill: Location — production (Extensions/) or example (Extensions/EXAMPLES/{Category}/)?
You:   Production.

Skill: Recipes I propose: base, ui, rest-api, dialplan, agi.
       - ui: settings page to manage the list
       - rest-api: external sync endpoint
       - dialplan + agi: intercept inbound calls and look up the number
       Should blocked calls just hang up, or route to an announcement?
You:   Hang up with a busy tone.

Skill: Plan —
       Location: Extensions/ModuleBlackList/
       Recipes:  base, ui, rest-api, dialplan, agi
       Files:    Setup/PbxExtensionSetup.php, Lib/BlackListConf.php,
                 Lib/BlackListMain.php, Models/BlackListNumbers.php,
                 App/Controllers/ModuleBlackListController.php, ...
                 agi-bin/check-blacklist.php, module.json
       Generate?
You:   Go.
```

After you approve, Phase 2 generates files in a fixed order (metadata → setup → models → config → main → web → REST → workers → AGI → translations), Phase 3 runs the post-generation checks (`php -l` on every PHP file, Babel transpilation for JS, `module.json` JSON validation), and Phase 4 prints a report listing the files created and the check results.

{% hint style="info" %}
The skill reads canonical example source before generating each recipe. For the `ui` and `base` recipes it studies the working example in `Extensions/EXAMPLES/WebInterface/ModuleExampleForm/`; for `rest-api` it reads `Extensions/EXAMPLES/REST-API/ModuleExampleRestAPIv3/`; for AMI workers `Extensions/EXAMPLES/AMI/ModuleExampleAmi/`. Pointing it at these directories yourself never hurts.
{% endhint %}

## Mode 2: augment an existing module

Trigger Mode 2 with "Add ... to ModuleBlackList" or "Improve ModuleBlackList". It runs four phases of its own:

1. **Analysis** — the skill reads the module directory, identifies which recipes are already present, **which hooks are used in the `Conf.php` class**, and counts models, controllers, and workers. It also scans for anti-patterns.
2. **Plan changes** — it decides which new files to create and which existing files to modify, and presents the diff plan.
3. **Implementation** — it applies the change using the same patterns as Mode 1.
4. **Optimization** (if you ask) — runs the anti-pattern checker on the touched code.

The critical guarantee, stated in `SKILL.md` Phase 3, is that **when modifying `Conf.php` the skill adds new hook methods without breaking existing ones**. If your `BlackListConf` already implements `extensionGenContexts()` and you ask to add a worker, the skill appends `getModuleWorkers()` and leaves your existing dialplan hook untouched. Prompt accordingly — name the capability you want added, and let the skill weave it into the existing class:

> Add a Beanstalk worker to ModuleBlackList that revalidates the deny-list every minute.

The skill will add a `getModuleWorkers()` method returning the worker registration (with `'type' => WorkerSafeScriptsCore::CHECK_BY_BEANSTALK`) and create `bin/WorkerBlackListMain.php`, without disturbing the dialplan hooks already in `BlackListConf`.

## Mode 3: optimize against anti-patterns

Trigger Mode 3 with "Optimize ModuleBlackList". The skill:

1. **Reads all module files.**
2. **Checks anti-patterns** against the reference standards (`Core/.claude/skills/mikopbx-module/reference/anti-patterns.md`).
3. **Reports findings with severity** and a fix suggestion for each.
4. **Applies fixes** only if you approve.

This is where the modern-baseline rules are enforced: PHP 8.4 idioms (typed properties on non-model classes, constructor promotion, `match`, enums), the Phalcon ORM exception for model column properties (untyped `$id`, nullable string defaults like `public ?string $enabled = '0';`), the import rule (`use Phalcon\Di\Di;`, never `use Phalcon\Di;`), and the file-header rule (`declare(strict_types=1);`, no closing `?>`). Read each finding's severity before approving a bulk fix — apply the high-severity ones first.

{% hint style="warning" %}
Mode 3 changes existing, possibly production code. Always review the proposed diff before approving. The skill will not apply fixes without your explicit go-ahead, but it is your job to confirm the change is safe for the module's release.
{% endhint %}

## Anti-prompts: what slows the skill down

* **Listing files instead of behavior** — you bypass recipe selection and lose generated providers/checks.
* **Skipping the location answer** — the skill must know `Extensions/` vs `Extensions/EXAMPLES/{Category}/` before it can lay down paths.
* **Approving the plan without reading it** — the plan is the last cheap checkpoint before files hit disk.
* **Renaming individual generated classes ad hoc** — breaks the naming-convention chain that ties the module together.

## Where to go next

* [What it generates](/mikopbx-development/ai-assisted-development/what-it-generates.md) — the exact file set each recipe produces.
* [Best practices](/mikopbx-development/module-developement/best-practices.md) — the standards Mode 3 enforces, written out as guidance you can apply by hand.
* [AI-assisted development overview](/mikopbx-development/ai-assisted-development/ai-assisted-development.md) — when to reach for the skill at all.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.mikopbx.com/mikopbx-development/ai-assisted-development/using-the-skill.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.