Skill Issue: storyblok-build-plugin
Storyblok is the first headless CMS that works for developers & marketers alike.
This is part of a larger Storyblok Skills Series
Is your agent building redundant Storyblok plugins for functionality that is already addressed by an existing plugin or app? Does it pick a plugin name without checking whether it’s taken, and stops at passing tests without ever opening the Visual Editor to check that the plugin actually renders?
cue the spotlight…
Introducing storyblok-build-plugin!
A skill that helps an agent extend what editors can do in Storyblok (field plugins), and decide whether anything needs building at all (hence the name, mostly). Before it writes a single line of code, the agent checks built-in field features and the live apps catalog. If neither covers the request, it picks between a field, tool, or space plugin, builds field plugins with the official CLI and SDK, and deploys only when you ask.
The Storyblok agent skills library is an open-source set of agent skills, plain SKILL.md files that teach an AI coding agent how to work with Storyblok: modeling schemas, reading and writing content through the Storyblok MCP server, and turning a design into a page. It’s built as one foundation skill that drives the MCP server with specialized skills supporting it, this one included.
Tested with:
<aside>
- Claude Code v2.1.319
- Opus 5.5
- Storyblok MCP server
- Field Plugin CLI 1.5.6
- Field Plugin SDK 1.7.2
- Storyblok Skills package 0.1.1
</aside>
Where it gets used
Every Storyblok request starts at the foundation skill, storyblok-use-storyblok, which picks the tool and the skill for the job. Its routing table sends this kind of request to storyblok-build-plugin:
“Something editors cannot do yet: a custom input, editor panel, space page, third-party integration; any plugin task”
That includes advice and plans that build nothing yet. Asking “should this be a tool plugin or a space plugin?” loads the skill too, because the answer depends on facts the skill holds.
How the skill decides what to build
Tasked with extending a Storyblok project's functionality the skill instructs the Agent to use a fixed procedure.. It stops at the first solution that covers the request:
- Use built-in field features. Single and multi-option fields, datasources, references, conditional fields, regex validation, and asset file-type limits.
- Use something from the apps catalog. The agent downloads the live catalog from storyblok.com/docs/apps.md and reads the page of any app it recommends, so setup details come from the docs, not from memory. If an app comes close but falls short, the agent says which and why.
- Build a new plugin of an appropriate type. Only now does anything get built.
The plugin type depends on where the plugin runs and what it can reach:
Type | Runs | Use for |
|---|---|---|
Field plugin | Inside one field of a block | Custom inputs that store a value |
Tool plugin | A panel in the Visual Editor, beside the story | Helpers for the story being edited |
Space plugin | A full page in the space’s sidebar | Dashboards, reports, and bulk work across many stories |
Field plugins get built with the official tooling. The agent scaffolds with @storyblok/field-plugin-cli, implements with the SDK, declares every option in field-plugin.config.json, and styles the plugin with Storyblok’s own CSS variables so it fits a narrow form column next to native fields. Then it runs the tests, builds dist/index.js, and rewrites the template README.
Whether or not to deploy it, is left up to you. A deploy publishes the plugin which is scoped by Storyblok account, not space. Plugin names are unique across all of Storyblok, so the agent adds a personal prefix (acme-price-field) and states the deployed name.
Tool and space plugins are self-hosted apps that authenticate with OAuth. For those, the skill points the agent at the official starters in storyblok/pluginsblok instead of building from scratch.
Why use this skill?
To show the benefits of using this skill, two experiments were run against the same space, each with two runs and identical prompts. The space has one Product content type with two fields, name and description, and 23 product stories. Run 1 used no skills, while run 2 used the Storyblok Skills package. Product was reset to its two original fields before every run.
Experiment 1: A plugin that already exists
The first prompt asks for something Storyblok already covers:
Create a Storyblok plugin so editors can pick a brand color for each product. Use the Product content type in space <space-id>. Decision point | Run 1 | Run 2 |
|---|---|---|
Apps catalog | Never checked | Read the catalog, then the Colorpicker and Palette pages |
Recommendation | Build a custom plugin | Palette (recommended), Colorpicker, or build anyway |
Questions asked | None | Two: which app, and whether to add the field to |
Brand colors | Empty | Asked for the brand hex codes |
Code written | A Vue 3 field plugin with two tests | None |
Deployed |
| Nothing to deploy |
Schema change | Added | Added |
Run 1 built something Storyblok already ships as an app.
Run 2 read the apps catalog and found two matches under Custom fields: Colorpicker and Palette. It read both app pages, then opened with:
“Storyblok already has two installable apps for this, so a custom plugin isn’t needed.”
It recommended Palette, because a fixed set of brand colors keeps every product on-brand, and offered Colorpicker for more freedom or a custom build if neither app covered a requirement. This is where the user picks the app instead of the agent generating one.
Not only that, but Run 2 didn’t make up brand colors. Palette’s colors option is required, so the agent asked for the hex codes, flagged that the Palette app needs to be installed before the field shows up, and only then added the field.
Result of Run 2 with the skill
Run 1 went straight to the field plugin CLI. It scaffolded a Vue 3 plugin, wrote a hex input with a native color swatch, and tried to deploy it as brand-color-picker. That name already belonged to another Storyblok account, so it renamed the plugin to product-brand-color and deployed again. It added the field to Product with an empty swatches option, so editors can type any hex value they like. The result works, but it’s a custom plugin to maintain for a problem two apps already solve, with less brand control than Palette.
Result of Run 1 without the skill
Experiment 2: A plugin that doesn’t exist yet
The second prompt asks for something no existing app covers:
Create a Storyblok plugin so editors can enter a product's dimensions (width, height, depth) and weight, with a cm/in and kg/lb unit toggle. Use the Product content type in space <space-id>. Deploy it and add it to Product. Decision point | Run 1 | Run 2 |
|---|---|---|
Apps catalog | Never checked | Checked, nothing covers it |
Questions asked | None | One: does the schema live in the Storyblok UI or in code |
Scaffolding | Official field plugin CLI | Official field plugin CLI |
Plugin name |
|
|
Options | None |
|
Tests | 4 | 15 |
README | Template README left in place | Rewritten with each option and the stored value |
Empty state | None | A hint under the inputs |
Invalid input | Saved as empty, the input clears with no message | Message under the input, nothing saved until the value is valid |
Visual Editor | Not opened | Opened a |
Although both runs seem to have resulted in plugins that are fairly similar in functionality and style, see that Run 2 checked the catalog first, asked where the schema lives, and confirmed the result in the Visual Editor.
Both runs scaffolded with the official CLI, and both built a working plugin that converts the values already entered when an editor switches units. Run 2 recognized that the request might already be covered. Nothing in the catalog fits, and the agent named the closest built-in option: plain number fields plus a single-option unit field, which store the values but don’t convert them.
Run 2 deployed under a prefixed name, skilltest-product-dimensions, and made the default units field options, so each field on each content type can start in cm or in, kg or lb. It rewrote the README with every option and an example of the stored value. Then it opened a Product story in the Visual Editor and confirmed the plugin renders there, instead of stopping at a passing test.
Result of Run 2 with the skill
Run 1 deployed under the bare package name, product-dimensions. That name happened to be free, but nothing about the run checked for it or avoided it. The plugin has no options, so every field starts in cm and kg. The template README stayed in place. The agent’s own summary said it hadn’t opened a Product story to check the plugin in the editor.
Result of Run 1 without the skill
Under the hood, the two plugins are close to identical: the same stored JSON, the same conversion math and rounding, and neither saves anything until the first edit. However, run 2 reads its default units from the field options, so a store selling in the US can start every field in inches and pounds without touching code. Run 1 hardcodes cm and kg. Invalid input is handled differently too. In Run 1, typing -5 saves an empty value, and the input clears with no message. Run 2 keeps what the editor typed, shows “Must be 0 or more” under the input, and saves nothing until the value is valid.
For the author, Run 2’s field is easier to work with. A store that sells in inches and pounds can make those the default units in the field’s settings, without changing any code. And if an editor types something invalid, Run 2 explains what’s wrong, while Run 1 clears the input without a message.
The result
Run 1 built two working plugins, one of which Storyblok already ships as an app. Run 2 built one plugin and set up an app for the other.
The skill’s own eval shows the same pattern at a larger scale. It runs six scenarios: checking for an existing app, choosing between a tool and a space plugin, and building and deploying a field plugin. Without the skill, Sonnet passed 5 of 18 runs and Opus 11 of 18. With it, both passed 18 of 18. The full breakdown is in the pull request that introduced the skill.
Every judgment call made in Run 2: built-in over app, app over plugin, the right plugin type for the job, a prefixed name over a bare one, the Visual Editor over a passing test, is something an experienced Storyblok developer already does by habit. This skill makes an agent do the same, probabilistically, run after run.
Get the skills
To use the skill library in your projects, install the Storyblok Agent Plugin. It sets up everything your agent needs to work with the skills of an experienced Storyblok Developer.
Click here to see all agent skills.
We want your feedback
We would love to hear back from you on how you use these skills and how they are working for you! Let us know in our Discord.







