---
title: "Skills"
description: "Codify your team's voice and house rules once – editors invoke them with @skill:// mentions to layer instructions onto any prompt."
canonical_url: "https://kirby.tools/docs/copilot/prompt-dialog/skills"
---

# Skills

> Codify your team's voice and house rules once – editors invoke them with @skill:// mentions to layer instructions onto any prompt.

Each `@skill://<id>` mention is replaced at submit time with a `<skill name="...">...</skill>` block in the system prompt. Skills are defined in `config.php` with `id`, `label`, and `instructions`.

![Prompt editor showing a green @skill://brand-voice token and the open skill typeahead dropdown](/img/kirby-copilot-skills.png)

Editors reach skills from the [view button](/docs/copilot/usage/view-button) or [toolbar buttons](/docs/copilot/usage/toolbar-buttons). Use them to codify the voice and rules your team reuses across the Panel.

<note>

**Not the "Skills" you may know from agent frameworks.** Many AI ecosystems use the term for dynamically loadable, often executable agent capabilities. Copilot Skills are plain text presets concatenated into the system prompt: no agentic loop, no filesystem access, no code execution.

</note>

## Defining Skills <u-badge className="align-middle,mb-1,ml-2,rounded-full" label="since v3.7.0" variant="subtle"></u-badge>

Each skill has an `id`, a human `label`, and an `instructions` string that gets injected into the system prompt when the skill is active.

<tabs>
<tabs-item label="Basic">

```php [config.php]
return [
    'johannschopplich.copilot' => [
        'skills' => [
            [
                'id' => 'brand-voice',
                'label' => 'Brand Voice',
                'instructions' => 'Write in a warm, conversational tone. Avoid corporate jargon. Prefer short sentences.'
            ],
            [
                'id' => 'concise',
                'label' => 'Concise',
                'instructions' => 'Cut every unnecessary word. Prefer active voice. No filler phrases.'
            ]
        ]
    ]
];
```

</tabs-item>

<tabs-item label="Multilingual">

```php [config.php]
return [
    'johannschopplich.copilot' => [
        'skills' => [
            [
                'id' => 'brand-voice',
                'label' => [
                    'en' => 'Brand Voice',
                    'de' => 'Markenstimme'
                ],
                'instructions' => [
                    'en' => 'Write in a warm, conversational tone. Avoid corporate jargon. Prefer short sentences.',
                    'de' => 'Schreibe in einem warmen, gesprächigen Ton. Vermeide Fachjargon. Bevorzuge kurze Sätze.'
                ]
            ]
        ]
    ]
];
```

</tabs-item>
</tabs>

<note>

Skill IDs must be URL-safe and unique – use lowercase letters, digits, hyphens, or underscores; no spaces, accents, or umlauts. `label` and `instructions` can each be localized independently. Missing translations fall back to English, then to the first defined language.

</note>

## Using Skills in Prompts

### Syntax

A skill mention uses the `@skill://` prefix followed by the skill's `id`:

```text
@skill://skill-id
```

For example, `@skill://brand-voice` or `@skill://concise`. The prompt editor highlights valid skill mentions in green; unknown IDs appear in red.

<tip>

A mention must not start inside a word – `im@skill://concise` stays plain text. Punctuation around it is fine, so `"@skill://concise"` resolves.

</tip>

### Typeahead

Start typing `@skill://` in the prompt editor to open a dropdown of available skills. Keep typing to filter by `id` or `label`. Select with the arrow keys and <kbd value="Enter">



</kbd>

 or <kbd value="Tab">



</kbd>

, or click to insert. Press <kbd value="Escape">



</kbd>

 to dismiss without inserting. The full `@skill://<id>` token is inserted at the cursor position.

### How It Works

When the prompt is submitted, referenced skill IDs are extracted from the prompt text and their instructions are added to the [system prompt](/docs/copilot/configuration/system-prompt) as `<skill>` XML blocks. The `@skill://` tokens are then **stripped from the user prompt** before the request is sent.

This differs from [page references](/docs/copilot/prompt-dialog/page-references), where `@page://` tokens remain visible and the referenced content is appended to the user prompt. Skill tokens are a control surface for the system prompt – the AI never sees them as user input.

Skill mentions resolve in every generation run, including prompts passed programmatically through the plugin API. The typeahead and token highlighting exist only in the prompt dialog editor.

<note>

Unknown skill IDs are dropped; a browser console warning names them. If the editor shows a token in red, the skill is unregistered and will not be injected.

</note>

### Example

Given a prompt typed by the editor:

```text
Write a product tagline for our new mixer.
@skill://brand-voice
@skill://concise
```

The AI receives:

- **System prompt**: the default system prompt, followed by:```xml
<skill name="Brand Voice">
Write in a warm, conversational tone. Avoid corporate jargon. Prefer short sentences.
</skill>

<skill name="Concise">
Cut every unnecessary word. Prefer active voice. No filler phrases.
</skill>
```
- **User prompt**: `Write a product tagline for our new mixer.`

---

<card-group>
<card icon="i-ri-bookmark-line" title="Prompt Templates" to="/docs/copilot/prompt-dialog/templates">

Skills compose with any prompt. For complete, reusable prompts you invoke as a single unit, see Prompt Templates.

</card>

<card icon="i-ri-settings-3-line" title="System Prompt" to="/docs/copilot/configuration/system-prompt">

For instructions that must shape every request without editor opt-in – house formatting, safety, compliance – customize the admin-controlled system prompt instead.

</card>
</card-group>

---

Every page of this site as Markdown: <https://kirby.tools/sitemap.md>