agentleFS
majdghithanmajdghithan/agent-skills/skills/filament-plugin-development/SKILL.md

filament-plugin-development

Skill7 starsChanged 4 months agoMITView on GitHub

Build and publish custom Filament plugins (Filament is the Laravel admin-panel framework). Use when creating a Filament plugin/package, implementing the Plugin contract, scaffolding from the plugin skeleton, registering assets/resources/pages/render-hooks, making a configurable plugin, testing it, or publishing to Packagist and the filamentphp.com/plugins directory. Targets Filament v4 (v5 shares the same plugin API). For USING Filament (resources/forms/tables), use the laravel-filament skill instead.

  • Commits and pushes

The file

We split this skill into the rules it gives an agent

3 rules. About 0 are common, 1 is distinctive, and 2 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈1

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 2

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Only reach for closure config (bool|Closure + the EvaluatesClosures trait's evaluate()) when you actually need closures - don't wrap a …

    line 71
  2. Very specific:

    Never hardcode panel assumptions (id admin, a path, single-panel) - read the passed Panel.

    line 157
  3. Distinctive:

    Keep it plain when one component is all you ship.

    line 159

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Building & publishing Filament plugins (v4 / v5)

A Filament "plugin" is just a Composer package that extends a Filament app. Verified against filamentphp.com/docs/4.x. v5 shares the same plugin API.

Two tiers - pick the smaller one

A. Plain package (components only). Ships resources/pages/widgets/fields/actions and does not implement any contract. The installing app wires them in manually (->resources([...]), ->widgets([...])). If your package is one widget or one field, do this - you do not need the Plugin contract.

B. Panel Plugin. A class implementing Filament\Contracts\Plugin, registered with ->plugin(YourPlugin::make()). Reach for this only when you bundle multiple things behind one registration, need per-panel configuration, or need boot-time logic. Rule of thumb: more than one moving part, or configurable -> Plugin contract; otherwise ship it plain.

The Plugin contract

Three methods:

MethodRunsPurpose
getId(): string-Globally-unique, stable singleton key (e.g. 'blog' - not 'settings', which clashes)
register(Panel $panel): voidwhile the panel is configuredregister resources/pages/widgets/render hooks/assets on the panel
boot(Panel $panel): voidonly for the active panel (via middleware)runtime side effects
namespace Vendor\FilamentBlog;

use Filament\Contracts\Plugin;
use Filament\Panel;

class BlogPlugin implements Plugin
{
    public function getId(): string { return 'blog'; }

    public function register(Panel $panel): void
    {
        $panel->resources([PostResource::class])
              ->pages([Settings::class])
              ->widgets([BlogOverviewWidget::class]);
    }

    public function boot(Panel $panel): void { /* runtime side effects here */ }

    public static function make(): static { return app(static::class); }         // install-side: ->plugin(BlogPlugin::make())
    public static function get(): static { return filament(app(static::class)->getId()); } // read configured instance anywhere
}

Register in the app's PanelProvider: ->plugin(BlogPlugin::make()).

#1 v3 -> v4 migration break: boot-time side effects must be in boot(Panel $panel), NOT the constructor - in v4 the constructor no longer fires them and they silently stop working.

Configurable plugins

Fluent setter returns static; getter reads it; register()/boot() branch on it. Config is per-panel (each ->plugin(Make()->...) call gets its own container-bound instance):

protected bool $hasAuthorResource = false;

public function authorResource(bool $condition = true): static { $this->hasAuthorResource = $condition; return $this; }
public function hasAuthorResource(): bool { return $this->hasAuthorResource; }

public function register(Panel $panel): void
{
    if ($this->hasAuthorResource()) { $panel->resources([AuthorResource::class]); }
}

Install-side: ->plugin(BlogPlugin::make()->authorResource(true)). Read anywhere: filament('blog')->hasAuthorResource().

Only reach for closure config (bool|Closure + the EvaluatesClosures trait's evaluate()) when you actually need closures - don't wrap a plain bool in closure machinery.

Scaffolding: the official skeleton

There is no make:filament-plugin command. Start from filamentphp/plugin-skeleton:

  1. "Use this template" -> your repo, clone it.
  2. php ./configure.php - interactive; rewrites stubs (vendor/namespace/author) and deletes itself.
  3. Delete unused boilerplate (config/, database/, src/Commands/, stubs/) - lazy wins.

Service provider - Spatie Package Tools (v4)

Extend Spatie\LaravelPackageTools\PackageServiceProvider (the v3 PluginServiceProvider is removed; a missing static $name throws):

use Spatie\LaravelPackageTools\{Package, PackageServiceProvider};
use Filament\Support\Facades\FilamentAsset;
use Filament\Support\Assets\AlpineComponent;
use Livewire\Livewire;

class ClockWidgetServiceProvider extends PackageServiceProvider
{
    public static string $name = 'clock-widget';

    public function configurePackage(Package $package): void
    {
        $package->name(static::$name)->hasViews()->hasTranslations();
        // ->hasMigrations([...]), ->hasConfigFile(), ->hasCommands([...]) as needed
    }

    public function packageBooted(): void
    {
        Livewire::component('clock-widget', ClockWidget::class);
        FilamentAsset::register(
            [ AlpineComponent::make('clock-widget', __DIR__ . '/../resources/dist/clock-widget.js') ],
            package: 'vendor/clock-widget',
        );
    }
}

Auto-discovery via composer.json extra.laravel.providers (the skeleton sets this).

Assets

Register in the provider's packageBooted(). Always pass package: to namespace assets into their own /public subdir (prevents filename collisions):

use Filament\Support\Assets\{Css, Js, AlpineComponent};

FilamentAsset::register([
    Css::make('my-styles', __DIR__.'/../resources/dist/plugin.css'),
    Js::make('my-scripts', __DIR__.'/../resources/dist/plugin.js')->loadedOnRequest(),
    AlpineComponent::make('my-widget', __DIR__.'/../resources/dist/my-widget.js'),
], package: 'vendor/package');
  • ->loadedOnRequest() / async Alpine components = loaded only when referenced. Prefer this; don't ship a global CSS/JS that loads on every page for a one-page feature.
  • Truly-global assets: register on the panel via $panel->assets([...]) in register().
  • Retrieve: FilamentAsset::getStyleHref('id', package: 'vendor/pkg'), getScriptSrc(...), getAlpineComponentSrc('id','vendor/pkg') (with x-load/x-load-src in Blade).
  • Commit built assets (resources/dist) so consumers don't need your Node toolchain.

Render hooks

Inject Blade at fixed UI points:

use Filament\View\PanelsRenderHook;
// per-panel, in register():
$panel->renderHook(PanelsRenderHook::BODY_START, fn () => view('blog::banner')->render());
// or globally, in the provider (with optional scopes):
\Filament\Support\Facades\FilamentView::registerRenderHook(
    PanelsRenderHook::USER_MENU_BEFORE, fn () => view('blog::menu-extra')->render(),
    scopes: \App\Filament\Pages\Dashboard::class,
);

PanelsRenderHook has constants for BODY_*, TOPBAR_*, SIDEBAR_*, PAGE_*, USER_MENU_*, etc.

Views, translations, testing

  • ->hasViews() namespaces resources/views/x.blade.php as clock-widget::x (protected static string $view = 'clock-widget::widget';). ->hasTranslations() -> __('clock-widget::file.key'). Consumers publish overrides with --tag=clock-widget-views (-translations, -config, -migrations).
  • Test with Pest + Orchestra Testbench (skeleton ships it). Boot a minimal panel with the plugin registered, then Filament's Livewire helpers:
use function Pest\Livewire\livewire;
livewire(ListPosts::class)->assertOk()->assertCanSeeTableRecords(Post::factory()->count(3)->create());

Publishing

  1. Packagist: valid composer.json (vendor/plugin, PSR-4, extra.laravel.providers, a real "filament/filament": "^4.0" constraint - don't float dev-main); tag SemVer (git tag v1.0.0 && git push --tags); submit to Packagist + enable the GitHub webhook. Consumers composer require vendor/plugin.
  2. Official directory: request author access at filamentphp.com/author (the old GitHub-PR flow is retired - it's the author dashboard now), then submit name/description/docs/repo/categories + support flags (dark mode, i18n, Filament versions). Free or paid listings supported.

Gotchas recap

  • Boot-time side effects -> boot(), not the constructor (v4 break).
  • getId() unique + stable (it's the singleton key).
  • Namespace assets with package:; prefer on-request/async loading.
  • Never hardcode panel assumptions (id admin, a path, single-panel) - read the passed Panel.
  • Extend PackageServiceProvider with a static $name.
  • Keep it plain when one component is all you ship.

Sources

Panel plugins · Building a panel plugin · Assets · plugin-skeleton · Author dashboard

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.