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:

  1. Use built-in field features. Single and multi-option fields, datasources, references, conditional fields, regex validation, and asset file-type limits.
  2. 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.
  3. 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 Product

Brand colors

Empty swatches option, editors type any hex value

Asked for the brand hex codes

Code written

A Vue 3 field plugin with two tests

None

Deployed

product-brand-color, after brand-color-picker was taken

Nothing to deploy

Schema change

Added brand_color

Added brand_color after the app was installed

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

product-dimensions

skilltest-product-dimensions

Options

None

defaultLengthUnit, defaultWeightUnit

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 Product story to confirm the plugin renders

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.