marko-php avatar

marko-skills

Marko-specific skills (create-module, create-plugin) for Claude Code.

GitHub stars
414

Install

/plugin install marko-skills@marko

Run it inside Claude Code after adding the marketplace with /plugin marketplace add marko-php/marko.

Contents

Discovered from source

Skills 2

Create a Marko module

A Marko module is a Composer package that the framework auto-discovers via the extra.marko.module flag. Modules can live anywhere — app/{name}/ for application code, modules/{vendor}/{name}/ for a distributable package dropped into a host project, packages/{name}/ in the framework monorepo, or vendor/{vendor}/{name}/ once installed from Packagist. The layout is identical in every case. Directory and Composer-name segments are always lowercase; only the PHP namespace is StudlyCase.

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

Step 1 — Confirm the name, then pick a location

If the user did not give the module a name, ask for one before scaffolding anything. Do not invent a name, reuse a vendor as the name, or proceed with a placeholder.

Casing rule — read this before creating any directory

A module's identity has two forms that must stay in sync:

  • Directory and Composer name → always lowercase. They are identical segment-for-segment, so a module can move between tiers (e.g. modules/ → vendor/) or be symlinked with zero path rewrites.
  • PHP namespace → always StudlyCase. blog → Blog, my-payment → MyPayment.

So the name blog yields directory blog/, Composer name …/blog, and namespace …\Blog. Lowercase module directories are correct — do not capitalize them. The casing only flips to StudlyCase in the PHP namespace and the psr-4 autoload key. (If you have seen "lowercase module names" before and assumed it was a bug, it was not: the directory is supposed to be lowercase; only the namespace is StudlyCase.)

Pick the tier by where the module lives

TierDirectoryComposer nameNamespaceWhen
App-localapp/{name}/app/{name}App\{Name}Application code, not distributed. The vendor segment is always the literal app — there is no project-derived vendor.
Distributablemodules/{vendor}/{name}/{vendor}/{name}{Vendor}\{Name}A package you intend to publish or share, dropped into a host project. Two-segment, vendor-scoped.
Framework monorepopackages/{name}/marko/{name}Marko\{Name}Only when working inside the Marko monorepo itself (root contains packages/core/).

Never author into vendor/ — it is ephemeral and populated by Composer. The modules/ tier is the manual-install mirror of vendor/: same two-segment {vendor}/{name} shape, so a module can later move to vendor/ (or be symlinked) without changes.

Default tier: if the user does not specify, assume an app-local module (app/{name}/, namespace App\{Name}). Only use modules/{vendor}/{name}/ when the user signals the module is meant to be distributed/shared.

Choosing {vendor} (distributable modules only — app-local modules have no vendor): derive it from the host project's root directory name (a project in ~/Sites/acme → vendor acme). Do not read it from the project's composer.json name: a project scaffolded from marko/skeleton still carries marko/skeleton there, so the directory name is the reliable signal. Never use marko as the vendor for an application or third-party module — that vendor is reserved for packages inside the framework monorepo.

Step 2 — Write composer.json

Copy the appropriate template to <module-root>/composer.json and substitute all placeholders.

Required keys: name, type: marko-module, require.marko/core, psr-4 autoload, and extra.marko.module: true to flag it for the code indexer. Never set a version field — let Composer infer it from the branch.

Deterministic constraint selection rule

Resolve {{marko_constraint}} and choose the template using this ordered decision tree:

  1. Inside the Marko monorepo (root directory contains packages/core/) → use assets/composer.json.monorepo.tmpl. Set {{marko_constraint}} to self.version. This ensures all packages in the monorepo resolve against each other at the same version without manual pinning.

  2. Otherwise (host project / standalone module) → use assets/composer.json.tmpl. Determine {{marko_constraint}} by reading the host project's root composer.json:

    • Find the first marko/* constraint that is already declared (e.g. "marko/framework": "*" → constraint is *; "marko/framework": "dev-develop" → constraint is dev-develop; "marko/framework": "^1.2" → constraint is ^1.2).
    • If no marko/* constraint is present in the host composer.json, default to *.

    Using * (or matching the host's existing constraint) ensures the scaffolded module resolves against whatever version of Marko the host project is consuming — whether that is a tagged release, a dev-develop branch alias, or a Composer path symlink. Never default to ^1.0: that constraint is incompatible with any host consuming dev-develop or *, which is the most common case during active development (e.g. marko/skeleton requires marko/framework: *).

Step 3 — Create the directory layout

{module-root}/
  composer.json
  src/                      # PSR-4 source
  tests/
    Pest.php                # Pest bootstrap
    Unit/
    Feature/
  README.md                 # Slim pointer per docs/DOCS-STANDARDS.md

Copy assets/Pest.php.tmpl to tests/Pest.php. No placeholder substitution needed.

Step 4 — Decide whether you need module.php

module.php is optional. Only create it if the module needs explicit DI bindings (interface → concrete class wiring), arguments (substitute individual constructor arguments by parameter name while the rest autowire; prefer it over a closure binding), singleton declarations, or boot callbacks for lifecycle hooks.

If the module is just classes that auto-resolve, omit module.php entirely. Do not create an empty manifest.

When you do need it, copy assets/module.php.tmpl to <module-root>/module.php and substitute {{Vendor}} and {{Name}} placeholders.

Step 5 — Add a slim README

Copy assets/README.md.tmpl to <module-root>/README.md and substitute {{vendor}} and {{name}} placeholders.

Per docs/DOCS-STANDARDS.md, package READMEs are slim pointers — title, install command, one quick example, and a link to the full docs page. Substantive documentation belongs in docs/src/content/docs/packages/{name}.md, not the README.

Step 6 — Verify the module is discovered

The module exists because you wrote it. The runtime discovers and autoloads it live on the next request — no composer dump-autoload, no index rebuild, no extra registration step. The MCP/LSP index self-refreshes (scoped to app/ and modules/), so list_modules and validate_module will reflect freshly created code automatically.

If you want to double-check structure, confirm:

  • composer.json has extra.marko.module: true
  • The module's psr-4 namespace resolves correctly

You may call list_modules or validate_module as an optional cross-check, but these are not gates — the module is live as soon as the files are in place.

Verification

After writing files, expect LSP diagnostics from marko-lsp to surface in the same turn. Resolve all diagnostics before declaring the module complete — diagnostics are the verification gate, not optional warnings. Calling list_modules is an optional cross-check to confirm the MCP index reflects the new module; it is not required for the module to be active.

Conventions to enforce

  • Every PHP file: declare(strict_types=1);
  • Constructor property promotion always
  • Type declarations on every parameter, return, and property
  • No final classes (blocks Preferences extensibility)
  • No magic methods — be explicit
  • Use readonly where immutability is appropriate, not as a blanket rule

Driver modules

If the module implements a driver for an interface package, a method the driver cannot support must throw UnsupportedFeatureException::forDriver() (or the interface package's Unsupported{Thing}FeatureException subclass), naming the feature and driver with a suggestion. Return a no-op only when the method's promise still holds, and document it in the docblock and docs page.

What this skill does not cover

  • Authoring plugins for the new module — see the marko-create-plugin skill
  • Adding routes, observers, commands — see the relevant Marko docs pages
  • Database migrations — see the marko/database package docs

See also

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.

AttributeWhenWhat it does
#[Before]Before the target methodModify args, short-circuit, or pass through
#[After]After the target methodReceive and modify the return value

Before return semantics

Return valueEffect
nullPass-through — original method runs with original args
arrayReplace arguments — original method runs with these args
Any other non-null valueShort-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.

#[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:

PlaceholderValue
{{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

Sponsors

Details

Marketplace
marko-php/marko
Source
packages/claude-plugins/plugins/marko-skills
Author
Mark Shust
Category
Development

More from marko-php/marko

All 3