DEV Community

Javier Eguiluz
Javier Eguiluz

Posted on

New in EasyAdmin 5.6: AI Agent Skills

#easyadmin #symfony #ai #php

EasyAdmin 5.6 is out with a new feature for a very specific audience: people who use AI coding agents to work on their Symfony applications. Before going into the details, two things you should know:

  • If you don't use AI, nothing changes for you. EasyAdmin doesn't install anything, doesn't change your project and doesn't ask you anything. Upgrade as usual.
  • If you use AI coding agents, this can improve the quality of the generated code significantly. Run one command and your agent finally writes EasyAdmin 5 code that works.

The Problem: Agents Learned EasyAdmin 4

Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, JetBrains Junie, Windsurf and the rest are pretty good at writting EasyAdmin code. The problem is that a lot of the EasyAdmin content they learned from describes EasyAdmin 4 (or older). That's why they confidently generate code that throws an exception on EasyAdmin 5. This is a typical example:

// what agents used to generate: linkToCrud() no longer exists in EasyAdmin 5
// and hideOnForms() never existed
yield MenuItem::linkToCrud('Products', 'fa fa-box', Product::class);
yield TextField::new('slug')->hideOnForms();
Enter fullscreen mode Exit fullscreen mode

This is what they should generate:

use App\Controller\Admin\ProductCrudController;
use EasyCorp\Bundle\EasyAdminBundle\Config\MenuItem;
use EasyCorp\Bundle\EasyAdminBundle\Field\TextField;

yield MenuItem::linkTo(ProductCrudController::class, 'Products', 'fa fa-box');
yield TextField::new('slug')->hideOnForm();
Enter fullscreen mode Exit fullscreen mode

You can fix each of these mistakes by hand, but it's tedious and it happens again and again: wrong argument order in linkToRoute(), setRole() instead of setPermission(), #[Route] instead of #[AdminRoute], displayAsButton() instead of renderAsButton(), and so on. I've collected dozens of these.

The Solution: an Agent Skill Inside the Package

EasyAdmin 5.6 ships an agent skill inside the Composer package. A skill is a directory with a SKILL.md file and some reference files that an agent reads when it detects that a task is related to the skill. EasyAdmin uses the Agent Skills open standard, which all the agents understand.

The skill lives in vendor/easycorp/easyadmin-bundle/skills/easyadmin/ and contains four files:

  • SKILL.md explains the mental model of EasyAdmin 5, the workflow to follow (use the makers first, check that a method exists before writing it, clear the cache and check the routes, etc.), and the rules for dashboards, CRUD controllers, fields, actions, filters, security, templates and functional tests. It also lists what changed since EasyAdmin 4 and what to do when you see certain errors.
  • references/api.md is a complete reference of every public method of the config, field, filter, attribute, controller and test classes. It's generated automatically from the source code and a unit test fails when it's outdated. If a method is not listed there, it doesn't exist.
  • references/patterns.md contains copy-ready recipes for the most common tasks.
  • references/traps.md lists method names that look right but are wrong, next to the right ones.

Because the skill is part of the package, it always describes the exact EasyAdmin version installed in your application. No more code generated for a version you don't use. The skill is plain text that you can read and change, it doesn't need network access and it doesn't send any telemetry.

Installing the Skill

Agents only load skills from a few well-known directories of your project, so the skill must be copied there. EasyAdmin provides a command for that:

$ php bin/console easyadmin:ai:install
Enter fullscreen mode Exit fullscreen mode

The command asks two questions. The first one is which agents you want to install the skill for. The agents already used in your project are preselected (the command looks for .claude/, .cursor/, .junie/, CLAUDE.md, etc.) and you can select more than one:

Agents Option value Skill directory Instructions file
Claude Code claude .claude/skills/ CLAUDE.md
Codex, Cursor, Copilot, Gemini, others agents .agents/skills/ AGENTS.md
JetBrains Junie junie .junie/skills/ AGENTS.md
Windsurf windsurf .windsurf/skills/ AGENTS.md

The second question asks if you want to add a short EasyAdmin section to your AI instructions files (CLAUDE.md and AGENTS.md). This section tells agents to read the skill before touching your backend. The answer defaults to yes and I recommend accepting it (more on this below).

In scripts and CI you can skip the questions with options:

# install the skill for one or more agents
$ php bin/console easyadmin:ai:install --agent=claude --agent=agents

# install the skill for all the supported agents
$ php bin/console easyadmin:ai:install --all

# install the skill for the detected agents without asking anything
$ php bin/console easyadmin:ai:install --no-interaction

# leave CLAUDE.md and AGENTS.md untouched
$ php bin/console easyadmin:ai:install --all --skip-guidelines
Enter fullscreen mode Exit fullscreen mode

The copies are real files, not symbolic links, so they work on every operating system, including Windows. Commit them to your repository: your teammates get the same skill without running any command and their agents behave like yours.

Note: The command never overwrites an easyadmin skill that it didn't install. If it finds one, it stops and writes nothing at all. Delete that directory and run the command again, or keep it and don't select that agent.

Keeping the Skill Up to Date

The copies describe the EasyAdmin version installed when you created them. After every EasyAdmin update, run this command to refresh them:

$ php bin/console easyadmin:ai:update
Enter fullscreen mode Exit fullscreen mode

We designed this command to run unattended: it never asks anything, it never creates new files, it only refreshes the copies that are already installed and the instructions blocks that already exist. It's silent when the skill isn't installed anywhere and it's silent in production too. That's why you can add it to your composer.json scripts and forget about it:

{
    "scripts": {
        "post-update-cmd": [
            "@auto-scripts",
            "@php bin/console easyadmin:ai:update"
        ]
    }
}
Enter fullscreen mode Exit fullscreen mode

If you prefer to run the update yourself, use the --check option in your CI workflow. It writes nothing and returns 1 when any installed copy or instructions block doesn't match the EasyAdmin version of the project, so the build fails until someone runs the update:

$ php bin/console easyadmin:ai:update --check
Enter fullscreen mode Exit fullscreen mode

The check compares the contents of the files and not the version numbers, so a copy that you changed by hand also counts as outdated.

Your Own Conventions

When you accept the second question of the install command, EasyAdmin adds a small section to your CLAUDE.md and AGENTS.md files, delimited by two markers:

<easyadmin-guidelines>
This project uses EasyAdmin 5.6.0. Before creating or modifying admin
dashboards, CRUD controllers, fields, actions, filters or their tests,
read and follow the `easyadmin` skill at
`.claude/skills/easyadmin/SKILL.md`.
...
</easyadmin-guidelines>
Enter fullscreen mode Exit fullscreen mode

EasyAdmin owns the text between those markers and nothing else. The rest of the file, including your own instructions, is left exactly as it is. Both commands replace the contents of the block on every run, so don't edit the text inside the markers.

The skill knows how EasyAdmin works, but it knows nothing about the conventions of your project. Write them in a section titled ## EasyAdmin conventions of the same file, outside the markers. The skill tells agents to read that section and apply it on top of the EasyAdmin rules:

<easyadmin-guidelines>
...
</easyadmin-guidelines>

## EasyAdmin conventions

- All CRUD controllers live in `src/Controller/Admin/` and their tests
  in `tests/Admin/Controller/`.
- Prices are stored in cents and displayed with `MoneyField`.
- Never display the `password` property of the `User` entity.
Enter fullscreen mode Exit fullscreen mode

If you want to go further and adapt the skill itself, delete the installed-by line from the metadata section of the copied SKILL.md. From that moment, the file is yours: the update command ignores it and the install command refuses to overwrite it. The drawback is that you no longer get the improvements of new EasyAdmin versions, so consider the conventions section first.

If your agent still generates wrong EasyAdmin code after installing the skill, please open an issue with the generated code.

Summary

EasyAdmin 5.6 ships an agent skill that teaches AI coding agents the real EasyAdmin 5 API, versioned with the package so it always matches the version you have installed. Run easyadmin:ai:install once, add easyadmin:ai:update to your Composer scripts, commit the files, and your agents (and your teammates' agents) stop generating EasyAdmin 4 code. If you don't use AI, nothing changes for you. Read the full documentation for all the details.

✨ If you enjoyed this feature and want to see more like it, consider sponsoring the EasyAdmin project 🙌💡

Top comments (0)