---
title: Skills overview
slug: agent-platform/docs/skills-overview
docTags: 
createdAt: 2026-08-11T20:47:41.000Z
---

Skills let you customize how Agent Platform works for you and your organization. Skills are the foundational context, rules, and behavioral guidelines that shape how Mark creates output and tailors it to your unique needs. Skills were previously called Instructions. The feature works the same way.

A simple skill can include your company's brand guidelines, ensuring Mark generates on-brand content. Other common skills include details about your company's products and services, target personas, user journey funnel, term-bases, and so on.

Mark dynamically selects and applies skills based on their **When to use** criteria. This ensures Mark applies the most relevant guidelines and adapts its responses to the current context and your requirements.

Skills help your team produce on-brand content without manually specifying preferences in every prompt.

Skills capture *how* work gets done, not *who* you are. To store facts about your preferences, context, and working style that Mark applies automatically across conversations, go to [Memory overview](docId\:jbms0mYnOnYWOvObK4OoU).

## Skills

Skills tell Mark how to behave, shaping its tone, output format, and overall approach. Skills are available in the following two types:

- **Organization skills** – Administrators set to enforce organization-wide standards.
- **Personal skills** – Individual users set to match their own preferences and working style.

### Organization skills

Mark administrators can [create](docId\:N3n_NnF8J0Ykujmp2Sg00), [modify](docId\:nsSgCk7YZ5kHj0x6ma75P), and [delete](docId\:nsSgCk7YZ5kHj0x6ma75P) organization skills. These skills enforce organization-wide policies, guidelines, brand standards, or platform behaviors. Examples include brand voice guidelines, approved content templates, compliance rules, or default behaviors for all teams. See [Create an organization-wide skill](docId\:N3n_NnF8J0Ykujmp2Sg00) for information.

Examples of organization-wide skills include the following:

- **Brand voice** – *Always write in Optimizely's tone of voice: professional, direct, and action-oriented*.
- **Writing style rules** – *Always use American English spelling.*
- **Canvas behavior** – *Always use a canvas when creating persistent artifacts like briefs, reports, or blog posts*.
- **Approved tools** – *Use Chart.js for all data visualizations* or *Use Tailwind CSS for all HTML output*.
- **Content templates** – *When creating a campaign brief, follow the standard template*.
- **Compliance rules** – *Never include pricing information in generated content without a disclaimer*.
- **Presentation standards** – *All presentations must use reveal.js with a 16:9 aspect ratio*.
- **Image and media guidelines** – *Always use Optimizely's file server URLs when embedding images*.

For information on administrator functions, see [Get started with Mark for administrators](docId\:pe0pbUJveWrG8ewvZWDRE).

### Personal skills

Mark users can [create](docId\:N3n_NnF8J0Ykujmp2Sg00), [modify](docId\:nsSgCk7YZ5kHj0x6ma75P), and [delete](docId\:nsSgCk7YZ5kHj0x6ma75P) personal skills. Personal skills apply to you (the individual user). Capture your explicit preferences, working style, or custom behaviors you want Mark to follow in your interactions. Examples of personal skills include the following:

- **Response format** – *Always respond in bullet points* or *Keep responses under 200 words*.
- **Tone preferences** – *Use a casual, conversational tone with me* or *Be more concise and skip the pleasantries*.
- **Role context** – *I am a developer, so always include code snippets when relevant*.
- **Language** – *Always respond in French*.
- **Output defaults** – *When creating documents, always use a canvas* or *Default to tables over bullet lists*.
- **Shortcuts** – *When I say 'quick summary,' give me a three-bullet TL;DR*.
- **Expertise level** – *Assume I have advanced knowledge of A/B testing, skip the basics*.
- **Reminders** – *Always remind me to add a meta description when writing blog posts*.

For information on user functions, see [Get started with Mark for users](docId\:L0Ntt9JQmG6fQIJK_Y7C7).

## Skills Directory

Instead of writing a skill from scratch, you can add a ready-made skill from the **Skills Directory**. Optimizely publishes skills for common marketing tasks, such as enforcing brand voice, formatting analytics reports, and documenting your keyword strategy. Most of these skills need information from you, which Mark collects in a chat when you install the skill. To browse the skills, go to **Directory > Skills**.

See [Skills Directory overview](docId:_h-waPhN8ts841qNQnhzl) and [Skills in the Skills Directory](docId\:gNo1P1wMxW6AnbvHlOYRG).

## Skill samples

Copy and customize the following samples to create your own skills from scratch:

- [Sample boilerplate press release skill](docId\:I4D8bJNAXI913ajc77q0T)
- [Sample competitor skill](docId\:RbVWAa4qI5_oh-72ZiDt-)
- [Sample persona skill](docId:7gQ0NBQMELRL-yLBM6Lv2)
- [Sample products and services skill](docId\:vM2HBZeDy26L5KXqz5v1t)
- [Sample tracked keyword skill](docId\:s7pDedyvd0g7PjAAkneIB)

## Components of a skill

![](https://api.archbee.com/api/optimize/BrbvVORKJ5iIeSMZye5kI/l_stRVPc54VVzstPTlMGQ_components-of-a-skill.png)

Each skill contains the following components:

1. **Name** – A short, descriptive identifier for the skill for easy recognition.
2. **Watchers** – A list of users watching the skill with an option to watch it yourself. See the [Watchers](docId:1HTjxW2J-ZOkYEZMwnasU) section.
3. **More** – Additional options including the option to export the skill as JSON or delete it.
4. **View version history** – Version history of the skill.
5. **Active** – Whether the skill is enabled in Mark.
6. **Shortcut** – A keyword you can use to call this skill from Mark chat or in an agent by entering /. Skills without a shortcut do not display in the / menu in Mark chat or in the **Choose skills** picker when creating specialized agents.
7. **Who is this skill for?** – Whether the skill is an organization skill or a personal skill. Mark Administrators can switch a skill between the two types.
8. **When to use** – Specifies when Mark should use the skill. See the [When to use](docId:1HTjxW2J-ZOkYEZMwnasU) section. Leave this blank to only use the skill manually by calling a `/shortcut`. See the [Shortcut](docId:1HTjxW2J-ZOkYEZMwnasU) section.
   - **Keywords or phrases** – Mark uses the skill when it detects a certain keyword or phrase.
   - **Tools** – Mark uses the skill when it uses a certain tool.
9. **Core skill** – The skill's behavior, including objectives, response formats, and constraints. See the [Core skill](docId:1HTjxW2J-ZOkYEZMwnasU) section.
10. **Files** – Upload reference files that Mark can reference when using this skill.
11. **Where to use** – Specifies an Optimizely product and instance where this skill applies. The instance is a specific connected deployment of an Optimizely product (such as Content Marketing Platform (CMP), Content Management System (CMS), Feature Experimentation, and so on) linked to your Mark instance. If you do not select a product, the skill applies to all products.

### Watchers

Watch a skill to receive a notification when another user updates or deletes it. Watching keeps you aware of changes to skills you rely on, such as organization skills that other administrators can edit. You are automatically added as a watcher for skills you create.

To view a list of users watching the skills, click **Watchers**.

![](https://api.archbee.com/api/optimize/BrbvVORKJ5iIeSMZye5kI/AX8EYMQ0ngdjTn9yW_z5Z_watchers-skills.png)

To watch a skill you didn't create, click **Watchers > Start watching**. To stop watching, click **Remove watcher** for your name.

To add a watcher, click **Watchers** and enter their name in the **Add Watcher** field.

When another user updates or deletes a skill you watch, Mark sends you a notification. You do not receive a notification for changes you make yourself. See [Notifications overview](docId\:BA9tH-MbtxzBbY-iz2rRX).

### Shortcut

A shortcut is a `/` keyword you assign to a skill to invoke it on demand from Mark chat. Rather than relying on Mark to automatically detect when a skill applies, a shortcut gives you control.

Shortcuts work well for skill-based skills you want available at any time but do not want Mark to apply automatically, for example, generating content in a specific format, running a defined research workflow, or applying a particular tone.

To run a skill manually, enter / followed by the shortcut name in the Mark chat input field. Mark activates the skill and applies it to your request.

:::hint{type="info"}
**Note**

The [When to use](docId:1HTjxW2J-ZOkYEZMwnasU) setting is optional. It defines the conditions that automatically trigger a skill. If you leave the **When to use** setting blank, skills never run automatically. Instead, Mark runs them only when you manually invoke the shortcut in chat. This gives you precise control over when the skill applies.
:::

### Core skill

Write the **Core Skill** as you would write guidance for a new team member. Use the smart text or markdown editor with clear structure and complete details so Mark can execute tasks effectively. Click **Switch to markdown** or **Switch to rich text** to toggle between the editors.

![](https://api.archbee.com/api/optimize/BrbvVORKJ5iIeSMZye5kI/FmfPTLEdueHxalNaUtjnp_core-skill.png)

Detailed skills reduce ambiguity and keep outputs consistent. To create a well-structured **Core skill** section, include the following:

- **Objective or goal** – Clearly state what the skill achieves.
- **Execution steps or process** – Outline the step-by-step instructions Mark follows, including prompts or questions for the user.
- **Response format guidelines** – Define how Mark formats its responses (for instance, tables or lists).
- **Constraints or safety measures** – List limitations or considerations Mark should observe.

### When to use

Use the **When to use** section to specify the exact conditions that activate your skills. Select [Keywords or phrases](docId:1HTjxW2J-ZOkYEZMwnasU) or [Tool](docId:1HTjxW2J-ZOkYEZMwnasU).

### Keywords or phrases

If you select **Keywords or phrases**, the skill activates based on your intent, keywords, or phrases.

![](https://api.archbee.com/api/optimize/BrbvVORKJ5iIeSMZye5kI/JLGAJ9DHQ3XpwQj5QnT6-_keywords-or-phrases.png)

Apply the following techniques to write the **Keywords or phrases** conditions that activate accurately and consistently:

- **Anchor your condition to a specific action or workflow** – Vague intent-based descriptions give Mark too much room for interpretation and lead to false matches. Reference a specific workflow, tool, or product feature instead.
  - **Before** – *When asked to help with marketing.*
  - **After** – *When asked to configure a marketing promotion campaign in the promotions manager.*
  - **Why it matters** – Without a specific anchor, the skill activates for unrelated prompts. Naming the tool or workflow sets a clear boundary.
- **State keywords explicitly** – If your skill should only activate for a specific concept, name the keyword directly. This turns semantic matching into keyword matching, which is more precise for narrow use cases.
  - **Before** – *When asked to help with creating, planning, or designing a marketing promotion.*
  - **After** – *ONLY use for the keyword "marketing promotion." Do NOT use for other keywords like sale, offer, or discount.*
  - **Why it matters** – Semantic matching can link related concepts unexpectedly. A prompt such as *Email subject for strawberries on sale* can trigger a "marketing promotion" skill because the relevancy model connects "sale" to "promotion." Explicit keywords prevent this.
- **Add negative conditions to block false matches** – Use *Do NOT use for...* to block related-but-wrong prompts. The relevancy model respects explicit exclusions.
  - **Before** – *When asked about customer data.*
  - **After** – *When asked to export, segment, or analyze customer data in the Customer Data Platform (CDP). Do NOT use for questions about individual customer support tickets or account settings.*
  - **Why it matters** – Without exclusions, skills activate for prompts that are topically related but contextually wrong. Exclusions give Mark a clear signal to stand down.
- **List synonyms for narrow concepts** – If users might phrase the same request in different ways, include alternative terms. This prevents the skill from failing to activate because the user chose a different word.
  - **Example** – *When asked about content scoring, content grades, or content quality scores.*
  - **Why it matters** – a skill scoped too narrowly — or written in jargon — fails to activate when it should. Listing synonyms and natural-language variants keeps coverage complete without broadening the scope.
- **Draw clear boundaries between similar skills** – If you have multiple skills covering related topics, make sure their **Keywords or phrases** conditions are distinct. Overlapping conditions cause both skills to trigger at the same time and produce inconsistent or conflicting responses.
  - **Before** – Two skills both use *When the user asks about marketing*, causing both to activate for the same prompts.
  - **After** – Separate the conditions so each skill has a distinct scope:
    - **skill A** – Content creation – *When the user asks to write, draft, or brainstorm marketing content such as email copy, social media posts, or ad text.*
    - **skill B** – Campaign configuration – *When the user asks to create, schedule, or configure a marketing campaign or automation workflow. Do NOT use for writing content or copy.*
  - **Why it matters** – Overlapping **Keywords or phrases** conditions mean both skills trigger on the same prompt. Explicit boundaries and mutual exclusions keep each skill focused.

The following table outlines common scoping goals, the corresponding technique to apply in the **Keywords or phrases**, and a practical example of each.

| Goal                            | Technique for the **Keywords or phrases** | Example                                                                      |
| ------------------------------- | ----------------------------------------- | ---------------------------------------------------------------------------- |
| Activate only for exact topics. | Use "ONLY use for KEYWORD"                | ONLY use when the user mentions "A/B test"                                   |
| Prevent false matches.          | Add "Do NOT use for..."                   | Do NOT use for general analytics questions.                                  |
| Anchor to a product feature.    | Name the specific feature or tool.        | When configuring promotion rules in the promotions manager.                  |
| Handle synonyms.                | List alternative terms.                   | When asked about content scoring, content grades, or content quality scores. |
| Separate related skills.        | Add mutual exclusions.                    | For campaign configuration only, not for writing campaign content.           |

### Tool

If you select **Tool**, the skill activates when the selected tools are called.

![](https://api.archbee.com/api/optimize/BrbvVORKJ5iIeSMZye5kI/pe0Ve4qJMd5M5dXpWor55_tool-skills.png)

## How Mark selects which skills to use

When you send a message, Mark decides which skills are relevant before it generates a response. The following explain the steps Mark takes:

1. **Mark gathers all active skills** – Mark collects all skills available to you and filters out any that are deactivated.
2. **Mark matches tool-based skills first** – When a skill's **When to use** is set to **Tool**, Mark applies it automatically whenever those tools are available. Mark requires no further evaluation.
3. **Mark evaluates remaining skills for relevance** – An AI model evaluates all remaining skills by reading the following:
   - Your latest message.
   - The conversation history.
   - The **Keywords or phrases** field of each skill.

The model then decides which skills are relevant to your conversation. See the following [How the relevancy model works](docId:1HTjxW2J-ZOkYEZMwnasU) section for information.

4. **Mark adds matched skills to context** – Mark adds selected skills to the system prompt so it can follow them when generating a response.

Mark uses the **When to use** setting to decide whether a skill is relevant. Mark does not consider a skill's name or core content during selection. It applies them only after selecting a skill.

### How the relevancy model works

The AI model that evaluates skill relevancy prioritizes inclusion over exclusion. The model includes a potentially relevant skill rather than risk missing one that matters. This means the following:

- Broad or generic **Keywords or phrases** descriptions match frequently. If your purpose is vague, the model includes the skill rather than excludes it.
- The model makes semantic connections. The model understands that "email subject for a sale" is conceptually related to "marketing promotion," even if those exact words do not appear in your prompt.
- Mark does not score or rank skills, it either includes or excludes each one. Mark does not apply partial matches.

This inclusive behavior is intentional. Missing a relevant skill is worse than including an extra one. Write your **Keywords or phrases** carefully to avoid unwanted activations. See [Keywords or phrases](docId:1HTjxW2J-ZOkYEZMwnasU) for best practices and examples.

:::hint{type="info"}
**Note**

If you use Opti ID, administrators can turn off generative AI in the Opti ID Admin Center. See [Turn generative AI off across Optimizely applications](docId\:X5U0kKD2azV5cIdNqwGNj).
:::