diff --git a/docs b/docs
index 6e7ec78..f48e9d7 160000
--- a/docs
+++ b/docs
@@ -1 +1 @@
-Subproject commit 6e7ec786d0ea048f282240b27a88e485bbd9b1e8
+Subproject commit f48e9d76dab2a02eeef6d50938e69c810fc034cc
diff --git a/web/app/dashboard/skill-definition/_components/edit.tsx b/web/app/dashboard/skill-definition/_components/edit.tsx
index 2a8f614..2cc4175 100644
--- a/web/app/dashboard/skill-definition/_components/edit.tsx
+++ b/web/app/dashboard/skill-definition/_components/edit.tsx
@@ -2,9 +2,10 @@
 
 import { zodResolver } from "@hookform/resolvers/zod";
 import { useEffect, useMemo, useState } from "react";
-import { type Resolver, useForm } from "react-hook-form";
+import { Controller, type Resolver, useForm } from "react-hook-form";
 import { z } from "zod/v4";
 
+import { ContentEditor } from "@/components/content-editor";
 import { OptionCombobox } from "@/components/option-combobox";
 import { ProjectDialog } from "@/components/project-dialog";
 import { Button } from "@/components/ui/button";
@@ -155,6 +156,7 @@ function SkillEditDialogBody({
     handleSubmit,
     reset,
     register,
+    control,
     formState: { errors },
   } = form;
 
@@ -316,14 +318,21 @@ function SkillEditDialogBody({
           </Field>
 
           <Field data-invalid={!!errors.instruction}>
-            <FieldLabel htmlFor="skill-instruction">{t("skillDefinition.instruction")}</FieldLabel>
+            <FieldLabel>{t("skillDefinition.instruction")}</FieldLabel>
             <FieldContent>
-              <Textarea
-                id="skill-instruction"
-                rows={12}
-                placeholder={t("skillDefinition.instructionPlaceholder")}
-                aria-invalid={!!errors.instruction}
-                {...register("instruction")}
+              <Controller
+                control={control}
+                name="instruction"
+                render={({ field }) => (
+                  <ContentEditor
+                    value={{ mode: "markdown", raw: field.value ?? "" }}
+                    onChange={(next) => field.onChange(next.raw)}
+                    placeholder={t("skillDefinition.instructionPlaceholder")}
+                    disabled={saving || loading}
+                    allowedModes={["markdown"]}
+                    height={360}
+                  />
+                )}
               />
               <FieldError errors={[errors.instruction]} />
             </FieldContent>
diff --git a/web/components/content-editor/markdown-editor.tsx b/web/components/content-editor/markdown-editor.tsx
index c98861d..352b90a 100644
--- a/web/components/content-editor/markdown-editor.tsx
+++ b/web/components/content-editor/markdown-editor.tsx
@@ -56,29 +56,67 @@ export const MarkdownEditor = forwardRef<MarkdownEditorRef, MarkdownEditorProps>
     const editorId = useId()
     const editorRef = useRef<ExposeParam>(null)
     const { resolvedTheme } = useTheme()
+    const showModeSwitch = allowedModes.length > 1
     const defToolbars = useMemo(
-      () => [
-        <EditorModeSwitch
-          key="mode-switch"
-          value={mode}
-          allowedModes={allowedModes}
-          disabled={disabled}
-          onChange={onModeChange}
-        />,
-        <NormalToolbar
+      () => {
+        const fullscreenToolbar = (
+          <NormalToolbar
           key="toggle-fullscreen"
           title={fullscreen ? t("editor.exitFullscreen") : t("editor.fullscreen")}
           disabled={disabled}
           onClick={onToggleFullscreen}
-        >
-          {fullscreen ? (
-            <Minimize2Icon className="h-[16px] w-[16px]" />
-          ) : (
-            <Maximize2Icon className="h-[16px] w-[16px]" />
-          )}
-        </NormalToolbar>,
+          >
+            {fullscreen ? (
+              <Minimize2Icon className="h-[16px] w-[16px]" />
+            ) : (
+              <Maximize2Icon className="h-[16px] w-[16px]" />
+            )}
+          </NormalToolbar>
+        )
+
+        if (!showModeSwitch) {
+          return [fullscreenToolbar]
+        }
+
+        return [
+          <EditorModeSwitch
+            key="mode-switch"
+            value={mode}
+            allowedModes={allowedModes}
+            disabled={disabled}
+            onChange={onModeChange}
+          />,
+          fullscreenToolbar,
+        ]
+      },
+      [allowedModes, disabled, fullscreen, mode, onModeChange, onToggleFullscreen, showModeSwitch, t]
+    )
+    const toolbars = useMemo(
+      () => [
+        ...(showModeSwitch ? [0, "-"] : []),
+        "bold",
+        "underline",
+        "italic",
+        "strikeThrough",
+        "-",
+        "title",
+        "quote",
+        "unorderedList",
+        "orderedList",
+        "-",
+        "codeRow",
+        "code",
+        "link",
+        "image",
+        "-",
+        "revoke",
+        "next",
+        showModeSwitch ? 1 : 0,
+        "=",
+        "preview",
+        "previewOnly",
       ],
-      [allowedModes, disabled, fullscreen, mode, onModeChange, onToggleFullscreen, t]
+      [showModeSwitch]
     )
 
     useImperativeHandle(ref, () => ({
@@ -99,31 +137,7 @@ export const MarkdownEditor = forwardRef<MarkdownEditorRef, MarkdownEditorProps>
             onChange={onChange}
             theme={resolvedTheme === "dark" ? "dark" : "light"}
             preview={false}
-            toolbars={[
-              0,
-              "-",
-              "bold",
-              "underline",
-              "italic",
-              "strikeThrough",
-              "-",
-              "title",
-              "quote",
-              "unorderedList",
-              "orderedList",
-              "-",
-              "codeRow",
-              "code",
-              "link",
-              "image",
-              "-",
-              "revoke",
-              "next",
-              1,
-              "=",
-              "preview",
-              "previewOnly",
-            ]}
+            toolbars={toolbars}
             defToolbars={defToolbars}
             footers={[]}
             noMermaid