Skills

Skills give CKEditor AI knowledge of the markup behind an editor feature, such as footnotes or merge fields, so the HTML it writes is what your editor accepts. Built-in skills are part of the service, and the agent loads a skill only when the request needs that feature. For your own plugins, you can add custom skills. This page covers which features the built-in skills cover, where the agent uses them, and how to write and manage custom skills.

HTML lets you build the same structure in more than one way. Ask a general-purpose model for footnotes, and it picks one shape. If that shape is not the one your editor supports, the editor drops or downgrades the markup when it loads the content. With CKEditor AI, you do not have to describe your markup in every prompt. A skill names the feature, describes its rules, and shows the markup the editor produces.

The agent loads skills where it writes document content: in chat and in Document Processing. Actions and reviews do not load skills. They rely on the model’s own knowledge of HTML.

The built-in skills cover CKEditor 5 features such as text formatting and structure, tables and lists, links and bookmarks, media, merge fields, math equations, and footnotes. The agent does not know the markup of your own plugins: for those, write a custom skill. The agent also reads your editor configuration. It writes markup only for the features your editor enables, and it uses only the option values your configuration allows.

New and improved skills come with service releases. Your integration does not change.

A custom skill teaches the agent the markup of your own editor plugin, such as a product card or a callout widget. You upload it once for the environment and it’s available for all users in that environment. Use a context instead for anything about your content, such as tone of voice or terminology.

1. You upload a SKILL.md file for the environment through the admin API.
2. On every request, the agent sees the name and description of every skill, built-in and custom.
3. The document’s editorConfig decides which skills the document enables. A skill is enabled when editorConfig has a top-level key equal to the skill’s configKey. The value of that key can hold the feature’s options, such as allowed variants, and the skill can tell the agent how to use them.

A skill is one Markdown file named SKILL.md: a frontmatter block followed by the instructions.

---
name: product-card
description: Product card widget with an image, a title, a price and a call to action. Use when asked to add, insert or format a product, product tile, offer or product teaser.
configKey: productCard
---

## Rules

- The card is a block element. Never place it inside a paragraph, a list item or a table cell.
- `data-sku` is required. Ask the user for the SKU when the request does not include one.
- Use only the variants listed in the `variants` option of the editor configuration.

## Examples

A basic card:

<section class="product-card" data-sku="KB-1042" data-variant="default">
	<img
		class="product-card__image"
		src="https://cdn.example.com/kb-1042.png"
		alt="Mechanical keyboard"
	/>
	<h3 class="product-card__title">Mechanical keyboard</h3>
	<p class="product-card__price">$129</p>
	<a class="product-card__cta" href="https://shop.example.com/kb-1042"
		>Buy now</a
	>
</section>

• One file per skill, up to 32 KiB, UTF-8, sent as text/markdown or text/plain.
• Up to 50 custom skills per environment.

Every endpoint requires a token with the ai:admin permission. Call them from your backend only. See Permissions.

See the Skill Admin API reference for request and response schemas and error codes.

A skill is scoped to a feature through editorConfig, a snapshot of the editor configuration sent with the document content part. The document enables the skill when editorConfig carries a top-level key equal to the skill’s configKey.

The editor sends editorConfig for you, but your plugin is not part of it until you register it under the skill’s configKey. See Registering custom features in the CKEditor 5 documentation.

When you call the API directly instead of through the editor, add the key to editorConfig yourself:

{
	"type": "document",
	"id": "doc-1",
	"editorConfig": {
		"editorVersion": "47.0.0",
		"heading": { "options": ["…"] },
		"productCard": {
			"variants": ["default", "compact"]
		}
	}
}

The key enables the skill whatever its value is, including false. To disable a skill for a document, leave the key out of editorConfig. A document without editorConfig, or with an empty one, counts as a full-featured editor and enables every skill.

Add editorVersion to the frontmatter when your plugin’s markup works only from a given editor version. The agent then sees the skill only in requests from that version or newer. A skill without editorVersion applies to every editor version.

The service takes the editor version of a request from the editorVersion key of editorConfig. CKEditor 5 sends it for you. Without that key, the service uses the x-editor-version request header.

If the request has neither the editorVersion key in editorConfig nor the x-editor-version header, the skill’s editorVersion has no effect and the skill is available in every request.

Examples are great way to describe your plugin’s markup, so put the effort there. Each example must be exactly the HTML your editor plugin produces including wrappers, classes and attribute order.

Cover the common cases: the minimal form, the full form, and the feature next to surrounding content.

The agent sees only the name and description until it decides to load the skill. Say what the feature is and list the requests that should trigger it.

• Good: Product card widget with an image, a title, a price and a call to action. Use when asked to add, insert or format a product, product tile, offer or product teaser.
• Avoid: Product plugin. It is too vague to trigger reliably, or it triggers for unrelated requests.

Add a ## Rules section for constraints the examples do not show: required attributes, allowed parents, values that depend on the configuration. Keep the rules short.

When your plugin has options, pass them in its registration and tell the skill which option controls what (for example “use only the variants listed in variants”). One skill then works for every editor that configures the plugin differently.

• One skill per feature. Do not put tone of voice or business rules into a skill: use a context instead.
• Keep the body short. A concise skill is easier for the agent to follow and uses fewer tokens.

1. Upload the skill.
2. Open an editor that registers your plugin under the skill’s configKey.
3. Ask for the feature in chat.
4. Check that the inserted markup matches your examples and survives an editor reload.

If the agent does not use the skill, make the description more specific to the prompts your users write.

• How CKEditor AI works describes what the agent holds in context and how skills fit into a request.
• Context library gives the agent knowledge of your content: style rules and reference files.
• Permissions covers the ai:admin scope you need to manage custom skills.