Skip to content
Skills Library
Programming · Building & coding

create-plugin

/create-plugin

Create a Marko plugin — a class that intercepts methods on another class to modify behavior without subclassing. **Use this skill whenever the user wants to add a plugin, intercept a method, or extend a class's behavior.** Concrete triggers: "add a plugin for the OrderService", "intercept the save method on User", "extend the behavior of X without changing it", "modify Y's return value before it's returned", "I need a plugin", "create a Before/After plugin". Plugins use the #[Plugin], #[Before], #[After] attributes.

Repository
marko ↗
Licence
MIT
Last repository change
09.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
3
Scripts
0
HTML comments
0
URLs in SKILL.md
3
Deprecation

No signals detected. Repository changed on 09.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Create a Marko plugin — a class that intercepts methods on another class to modify behavior without subclassing. **Use this skill whenever the user wants to add a plugin, intercept a method, or extend a class's behavior.** Concrete triggers: "add a plugin for the OrderService", "intercept the save method on User", "extend the behavior of X without changing it", "modify Y's return value before it's returned", "I need a plugin", "create a Before/After plugin". Plugins use the #[Plugin], #[Before], #[After] attributes.

Triggers from the description

s behavior.** Concrete triggers:intercept the save method on Userextend the behavior of X without changing itmodify Ys returnedI need a plugincreate a Before/After plugin
Original author description

Create a Marko plugin — a class that intercepts methods on another class to modify behavior without subclassing. **Use this skill whenever the user wants to add a plugin, intercept a method, or extend a class's behavior.** Concrete triggers: "add a plugin for the OrderService", "intercept the save method on User", "extend the behavior of X without changing it", "modify Y's return value before it's returned", "I need a plugin", "create a Before/After plugin". Plugins use the #[Plugin], #[Before], #[After] attributes.

How it works

  1. When to use
  2. Plugin model — two timings only
  3. Runbook
  4. Constraints
  5. What this skill does not cover
  6. See also
Original SKILL.md headings · 143 lines, 909 words
SKILL.md preview
---
name: create-plugin
description: >
  Create a Marko plugin — a class that intercepts methods on another class to modify
  behavior without subclassing. **Use this skill whenever the user wants to add a
  plugin, intercept a method, or extend a class's behavior.** Concrete triggers:
  "add a plugin for the OrderService", "intercept the save method on User", "extend
  the behavior of X without changing it", "modify Y's return value before it's
  returned", "I need a plugin", "create a Before/After plugin". Plugins use the
  #[Plugin], #[Before], #[After] attributes.
---

# Create a Marko Plugin

> **This skill is the canonical specification for a Marko plugin. Do not inspect existing plugins in this project to infer structure — siblings may have drifted from spec. Copy the templates from `assets/` verbatim, substitute placeholders, and stop.**

A plugin is a class that intercepts the input or output of a public method on any
other class — without replacing that class. Plugins are Marko's fine-grained
extensibility primitive. They are auto-discovered from any module's `src/`
directory; **no manual registration is needed**.

## When to use

Use a plugin when the user wants to modify arguments to, or the result from, a
public method on a class without rewriting or subclassing it. Common cases:

- Enrich a return value
- Validate or transform inputs before the method runs
- Short-circuit (cache hit, guard, redirect)
- Log or observe calls
- Chain transformations across modules

For **total replacement** of a class, use a Preference instead — that is a separate
skill (`marko-create-preference`). Plugins and Preferences are complementary; only
Preferences swap entire implementations.

## Plugin model — two timings only

Marko supports exactly **two** plugin types. A third type that wraps the call is
**intentionally absent** — anything it could do is expressed as a Before
(short-circuit) or After (result transformation), keeping the call stack
debuggable.

| Attribute   | When                       | What it does                                  |
|-------------|----------------------------|-----------------------------------------------|
| `#[Before]` | Before the target method   | Modify args, short-circuit, or pass through   |
| `#[After]`  | After the target method    | Receive and modify the return value           |

### Before return semantics

| Return value            | Effect                                                    |
|-------------------------|-----------------------------------------------------------|
| `null`                  | Pass-through — original method runs with original args    |
| `array`                 | Replace arguments — original method runs with these args  |
| Any other non-null value| Short-circuit — original method is NOT called             |

### After return semantics

After plugins receive `$result` (the return value of the original method or a
prior After plugin) as their first parameter, followed by the (possibly modified)
original arguments. Each After plugin's return value feeds the next After plugin
in sort order — always return the (possibly modified) result.

### sortOrder

`sortOrder` is defined on the method-level attribute, **not** the class. Lower
numbers run first; negatives are valid; default is `0`.

```php
#[Before(sortOrder: -10)]   // runs before plugins at default 0
#[After(sortOrder: 100)]    // runs after lower-priority Afters
```

## Runbook

### Step 1 — Identify the target

Determine which class and public method to intercept. Plugins cannot intercept
`protected` or `private` methods, and the target class must not be `final`.

### Step 2 — Copy the plugin class template

Copy `assets/PluginClass.php.tmpl` verbatim. Substitute:

| Placeholder       | Value                                  |
|-------------------|----------------------------------------|
| `{{Vendor}}`      | The host module's namespace vendor segment, StudlyCase (e.g. `App`, `Acme`) |
| `{{Name}}`        | The host module's name segment, StudlyCase (e.g., `Blog`) |
| `{{TargetClass}}` | Unqualified class name (e.g., `PostRepository`) |

**`{{Vendor}}\{{Name}}` is inherited from the module that hosts the plugin — read it, do not re-derive it.** A plugin lives inside an existing module, so its namespace must match that module exactly. Read the host module's `composer.json` `autoload.psr-4` key and use its prefix verbatim:

- **App-local module** (`app/{name}/`) → namespace `App\{Name}` (the vendor segment is always the literal `App`, never the project directory name).
- **Distributable module** (`modules/{vendor}/{name}/`) → namespace `{Vendor}\{Name}` from that module's psr-4.
- **Framework monorepo package** (`packages/{name}/`, root contains `packages/core/`) → namespace `Marko\{Name}`.

**Never use `Marko` as the vendor outside the framework monorepo.** Do **not** infer the vendor from the project's root `composer.json` `name`: a skeleton-derived project still carries `marko/skeleton` there. The host module's own psr-4 mapping is the source of truth.

Place the file at `src/Plugins/{{TargetClass}}Plugin.php` inside the module.

Add the correct `use` statement for the fully-qualified target class.

Remove any `#[Before]` or `#[After]` methods that are not needed for this plugin —
the template shows both for illustration.

### Step 3 — Implement the interceptor methods

Name each plugin method identically to the target method it intercepts (or use the
`method:` argument on the attribute to override when names would collide).

Apply the correct return semantics from the table above.

### Step 4 — Copy the test template

Copy `assets/PluginTest.php.tmpl` verbatim. Substitute the same placeholders.

Adjust test cases to reflect the actual behavior being intercepted (pass-through,
argument modification, short-circuit, result enrichment).

### Step 5 — Verify placement

- The plugin class lives anywhere under `src/` — `src/Plugins/` is conventional.
- Do **not** register it in `module.php` — discovery is automatic.

### Step 6 — LSP and MCP verification gate

After writing files, expect LSP diagnostics from `marko-lsp`. Resolve all
diagnostics before declaring the plugin complete — diagnostics are the verification
gate. Then call the `find_plugins_targeting` MCP tool with the target class to
confirm the new plugin is discovered.

## Constraints

- Targeted methods must be `public` on the target class
- Target class must not be `final` (Marko avoids `final` for this reason)
- Plugin classes should be `readonly` when they have no mutable state
- Constructor property promotion always
- `declare(strict_types=1)` always
- No magic methods
- No traits

## What this skill does not cover

- Creating a new module to host the plugin — see `marko-create-module`
- Replacing an entire class — that is a Preference, not a Plugin (use
  `marko-create-preference`)
- Listening to events — that is `#[Observer]`, a different mechanism

## See also

- [Marko docs: plugins](https://marko.build/docs/concepts/plugins/)
- [Marko docs: preferences](https://marko.build/docs/concepts/preferences/)
- [`marko/core` README](https://github.com/markshust/marko/tree/develop/packages/core)
Files in this package (3)
  • SKILL.md 7 KB
  • assets/PluginClass.php.tmpl 1 KB
  • assets/PluginTest.php.tmpl 2 KB

Versions

RepositoryScoreLicence
This page · marko-php/marko100MIT
Neko1313/agent-compositor100MIT
different-ai/openwork100MIT
asgeirtj/system_prompts_leaks100CC0-1.0
asgeirtj/system_prompts_leaks100CC0-1.0
Devin-AXIS/iPolloWork100MIT
marcus/sidecar100MIT
alexsmedile/hormozi-skills100MIT
oneworks-ai/app100MIT

Database snapshot: 13.11.2026 · package version 26bb3f8e7c64 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100create-module
    Scaffold a new Marko module — a self-contained Composer package with composer.json, namespaced src/, and Pest tests. **Use this skill whenever the user asks to create, add, or scaffold a new Marko module or package.** Concrete triggers: 'create a module named payment', 'scaffold…
  • 100neko-plugin
    Work on N.E.K.O plugins end to end. Use when the user asks to create, modify, review, run, debug, inspect, document, validate, package, or reason about N.E.K.O plugins, plugin.toml, plugin SDK usage, plugin UI surfaces, plugin CLI tooling, plugin runtime behavior, or plugin system contracts.
  • 100marko
    Marko is an HTML-based UI language and framework from eBay with streaming server rendering, fine-grained reactivity and automatic partial hydration. Use when a user asks to build or migrate a Marko app, write .marko components with <let>, <const>, <for> and <try>/<await>, stream…
  • 90graft
    Create a graftpunk site plugin from a browser recording, or add commands to an existing one. Use when asked to build, scaffold, or extend a graftpunk plugin for a site, or to add a command to a plugin.
  • 100extension-point
    Wire behaviour onto an *existing* Magento 2 class without editing it — a **plugin** (before/after/around interceptor + di.xml), an **observer** (events.xml + Observer), or a **preference**. Use when the user wants to intercept a core/3rd-party method, react to an event, or swap…
  • 100apollo-router-plugin-creator
    Guide for writing Apollo Router native Rust plugins. Use this skill when: (1) users want to create a new router plugin, (2) users want to add service hooks (router_service, supergraph_service, execution_service, subgraph_service), (3) users want to modify an existing router…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.