Python
import { useRef, useState } from "react";
import { Trans, useTranslation } from "react-i18next";
import {
createSkill,
deleteSkill,
listSkills,
revealSkill,
stageSkillUpload,
confirmSkillUpload,
updateSkill,
type Machine,
type SkillRow,
type SkillUploadPreview,
} from "../api";
import { useMachineData } from "../useMachineData";
import { CachedNote, LoadingRow, UnreachableRow } from "./ScopedStatus";
import { Icon } from "./Icon";
// Settings ▸ Skills (SKILLS-SPEC §5/§6) — the management home: the LIST is the page; every
// add-surface appears only when summoned from the single "Add skill" menu (the three doors:
// write form / import / start-a-conversation). Everything a user creates here is GLOBAL —
// "skills are things your worker knows everywhere". Creation-by-AI is a CONVERSATION (the
// menu's third door starts one; the worker proposes via save_skill) — there is no
// in-Settings drafting and no description box: the composer is where you describe it.
// Persona-bundled skills arrive with personas (§10), managed on the persona page, not here.
const CARD = "rounded-xl2 border border-line bg-panel";
const FIELD_LABEL = "text-ui font-medium text-ink";
const INPUT =
"w-full min-w-0 px-3 py-2 rounded-lg border border-line bg-paper text-ui text-ink outline-none focus:border-accent";
const BTN_ACCENT =
"text-ui px-3 py-2 rounded-lg bg-accent text-white shrink-0 disabled:opacity-40";
const BTN_BORDERED =
"text-ui px-3 py-2 rounded-lg border border-line bg-paper hover:border-lineStrong shrink-0";
const BADGE =
"text-label px-2 py-0.5 rounded-full border border-line bg-paper text-muted shrink-0";
type Editor = {
mode: "new" | "edit";
name: string;
description: string;
instructions: string;
};
const emptyEditor = (): Editor => ({
mode: "new",
name: "",
description: "",
instructions: "",
});
async function fileToB64(file: File): Promise<string> {
// FileReader fallback: File.arrayBuffer is missing in some webviews (and jsdom).
const buf =
typeof file.arrayBuffer === "function"
? await file.arrayBuffer()
: await new Promise<ArrayBuffer>((resolve, reject) => {
const r = new FileReader();
r.onload = () => resolve(r.result as ArrayBuffer);
r.onerror = () => reject(r.error);
r.readAsArrayBuffer(file);
});
const bytes = new Uint8Array(buf);
let bin = "";
const CHUNK = 0x8000;
for (let i = 0; i < bytes.length; i += CHUNK) {
bin += String.fromCharCode(...bytes.subarray(i, i + CHUNK));
}
return btoa(bin);
}
export function SkillsTab({
onCreateSkill,
machine,
}: {
// The doorway (SKILLS-SPEC §5.2): starts a new conversation with the description
// prefilled in the composer — the worker builds the skill and proposes it via save_skill.
// With a machine scope, that conversation runs ON the machine.
onCreateSkill?: (description: string) => void;
// UX-046 machine scope: manage THIS machine's skills through the proxy.
machine?: Machine | null;
}) {
const { t } = useTranslation();
const mid = machine?.id ?? null;
const [editor, setEditor] = useState<Editor | null>(null);
const [upload, setUpload] = useState<SkillUploadPreview | null>(null);
const [addOpen, setAddOpen] = useState(false);
const [armedDelete, setArmedDelete] = useState<string | null>(null);
const [error, setError] = useState("");
// The state-change callout (SKILLS-SPEC §4.1 #2): name-first so the user knows WHICH
// skill, and visually distinct so it can't be skimmed past (tester ask 2026-07-27).
const [notice, setNotice] = useState<{ name: string; text: string; tone: "ok" | "warn" } | null>(
null,
);
const fileInput = useRef<HTMLInputElement>(null);
// Confirmation copy (SKILLS-SPEC §4.1 #2): name-first, outcome + remedy only, in words a
// person already owns — now / everywhere / off / start a new one. Never mechanism ("the
// model will be told…") or engineering timing ("from the next message") — owner-driver
// review rounds, 2026-07-27. The engine countermands disabled-but-loaded skills silently;
// the copy promises only the guaranteed part.
const CONFIRMATION = t("skills.confirmation");
const OFF_NOTE = t("skills.off_note");
const DELETE_NOTE = t("skills.delete_note");
const skills = useMachineData<SkillRow[]>(`skills:${mid ?? "local"}`, () =>
listSkills(undefined, mid),
);
const rows = skills.data ?? [];
const refresh = skills.refresh;
const fail = (res: { ok?: boolean; error?: string }) => {
setNotice(null);
if (res.ok === false) {
setError(res.error || t("skills.error_generic"));
return true;
}
setError("");
return false;
};
const save = async () => {
if (!editor) return;
const res =
editor.mode === "new"
? await createSkill(
{
name: editor.name.trim(),
description: editor.description.trim(),
instructions: editor.instructions,
},
mid,
)
: await updateSkill(
editor.name,
{
description: editor.description.trim(),
instructions: editor.instructions,
},
mid,
);
if (fail(res)) return;
setEditor(null);
if (editor.mode === "new")
setNotice({ name: editor.name.trim(), text: CONFIRMATION, tone: "ok" });
refresh();
};
const onPickFile = async (file: File | undefined) => {
if (!file) return;
const res = await stageSkillUpload(await fileToB64(file), file.name, mid);
if (fail(res)) return;
setUpload(res);
};
const confirmUpload = async () => {
if (!upload?.token) return;
const res = await confirmSkillUpload(upload.token, "global", undefined, mid);
if (fail(res)) return;
setUpload(null);
setNotice({ name: upload.name || t("skills.fallback_name"), text: CONFIRMATION, tone: "ok" });
refresh();
};
const remove = async (row: SkillRow) => {
if (armedDelete !== row.name) {
setArmedDelete(row.name);
return;
}
setArmedDelete(null);
const res = await deleteSkill(row.name, undefined, mid);
if (fail(res)) return;
setNotice({ name: row.name, text: DELETE_NOTE, tone: "warn" });
refresh();
};
return (
<section>
<div className="flex items-start justify-between gap-3 mb-4">
<div>
<h2 className="text-body font-semibold">{t("settings.tab.skills")}</h2>
<p className="text-ui text-muted mt-1 leading-relaxed">
{machine
? t("settingsx.skills.machine_subtitle", { name: machine.name })
: t("skills.subtitle")}
</p>
</div>
{/* One add-action, three doors behind it (SKILLS-SPEC §5): the list is the page. */}
<div className="relative shrink-0">
<button
className={BTN_ACCENT}
aria-haspopup="menu"
aria-expanded={addOpen}
onClick={() => setAddOpen((v) => !v)}
>
<span className="inline-flex items-center gap-1.5">
<Icon name="plus" size={13} /> {t("skills.add_skill")}
</span>
</button>
{addOpen ? (
<>
<div className="fixed inset-0 z-10" onClick={() => setAddOpen(false)} />
<div
role="menu"
className="absolute right-0 top-full mt-1.5 w-80 rounded-xl2 border border-line bg-panel shadow-xl z-20 p-1.5"
onKeyDown={(e) => e.key === "Escape" && setAddOpen(false)}
>
<button
role="menuitem"
className="w-full text-left px-3 py-2 rounded-lg hover:bg-paper"
onClick={() => {
setAddOpen(false);
setEditor(emptyEditor());
}}
>
<div className="text-ui font-medium">{t("skills.door_write")}</div>
<div className="text-meta text-muted">{t("skills.door_write_sub")}</div>
</button>
<button
role="menuitem"
className="w-full text-left px-3 py-2 rounded-lg hover:bg-paper"
onClick={() => {
setAddOpen(false);
fileInput.current?.click();
}}
>
<div className="text-ui font-medium">{t("skills.door_import")}</div>
<div className="text-meta text-muted">{t("skills.door_import_sub")}</div>
</button>
<button
role="menuitem"
className="w-full text-left px-3 py-2 rounded-lg hover:bg-paper disabled:opacity-40"
disabled={!onCreateSkill}
onClick={() => {
setAddOpen(false);
onCreateSkill?.("");
}}
>
<div className="text-ui font-medium">{t("skills.door_ai")}</div>
<div className="text-meta text-muted">{t("skills.door_ai_sub")}</div>
</button>
</div>
</>
) : null}
</div>
</div>
<input
ref={fileInput}
type="file"
accept=".zip,.md"
className="hidden"
aria-label={t("skills.upload_aria")}
onChange={(e) => {
onPickFile(e.target.files?.[0]);
e.target.value = "";
}}
/>
{error ? (
<div className="text-ui text-red-500 mb-3" role="alert">
{error}
</div>
) : null}
{notice ? (
<div
role="status"
className={
"mb-3 flex items-start gap-2 rounded-lg border px-3 py-2 text-ui " +
(notice.tone === "ok"
? "bg-tealSoft/70 text-tealInk border-tealInk/20"
: "bg-warnSoft/70 text-warnInk border-warnInk/20")
}
>
<span className="min-w-0">
<b>{notice.name}</b> {notice.text}
</span>
<button
className="ml-auto shrink-0 opacity-60 hover:opacity-100"
aria-label={t("common.dismiss")}
onClick={() => setNotice(null)}
>
✕
</button>
</div>
) : null}
{upload ? (
<div className={`${CARD} p-4 mb-4`}>
<div className="text-ui font-medium mb-1">{t("skills.review_title")}</div>
<p className="text-ui text-muted mb-3">{t("skills.review_sub")}</p>
<div className="text-ui mb-1">
<span className="font-medium">{upload.name}</span>
<span className="text-muted"> — {upload.description || t("skills.no_description")}</span>
</div>
<pre className="text-meta bg-paper border border-line rounded-lg p-3 whitespace-pre-wrap max-h-64 overflow-y-auto mb-2">
{upload.instructions}
</pre>
{upload.files?.length ? (
<div className="text-meta text-muted mb-2">
{t("skills.bundled_files", { files: upload.files.join(", ") })}
</div>
) : null}
<div className="flex gap-2 mt-3">
<button className={BTN_ACCENT} onClick={confirmUpload}>
{t("skills.install_skill")}
</button>
<button className={BTN_BORDERED} onClick={() => setUpload(null)}>
{t("folder_gate.cancel")}
</button>
</div>
</div>
) : null}
{editor ? (
<div className={`${CARD} p-4 mb-4`}>
<div className="text-ui font-medium mb-3">
{editor.mode === "new"
? t("skills.editor_new")
: t("skills.editor_edit", { name: editor.name })}
</div>
<label className={FIELD_LABEL} htmlFor="skill-name">
{t("skills.name_label")}
</label>
<input
id="skill-name"
className={`${INPUT} mt-1 mb-3`}
value={editor.name}
disabled={editor.mode === "edit"}
placeholder={t("skills.name_placeholder")}
onChange={(e) => setEditor({ ...editor, name: e.target.value })}
/>
<label className={FIELD_LABEL} htmlFor="skill-desc">
{t("skills.desc_label")}
</label>
<input
id="skill-desc"
className={`${INPUT} mt-1 mb-3`}
value={editor.description}
placeholder={t("skills.desc_placeholder")}
onChange={(e) => setEditor({ ...editor, description: e.target.value })}
/>
<label className={FIELD_LABEL} htmlFor="skill-instructions">
{t("skills.instructions_label")}
</label>
<textarea
id="skill-instructions"
className={`${INPUT} mt-1 mb-3 min-h-[140px] font-mono`}
value={editor.instructions}
placeholder={t("skills.instructions_placeholder")}
onChange={(e) => setEditor({ ...editor, instructions: e.target.value })}
/>
<div className="flex gap-2 mt-3">
<button
className={BTN_ACCENT}
disabled={!editor.name.trim() || !editor.instructions.trim()}
onClick={save}
>
{t("skills.save_skill")}
</button>
<button className={BTN_BORDERED} onClick={() => setEditor(null)}>
{t("folder_gate.cancel")}
</button>
</div>
</div>
) : null}
{skills.cachedAt ? <CachedNote at={skills.cachedAt} /> : null}
<div className={`${CARD} divide-y divide-line`}>
{skills.loading && !skills.data ? (
<LoadingRow
what={
machine
? t("settingsx.skills.loading_what_on", { name: machine.name })
: t("settingsx.skills.loading_what")
}
/>
) : skills.error && !skills.data && machine ? (
<UnreachableRow machineName={machine.name} />
) : rows.length === 0 && !editor ? (
<div className="p-5 text-ui text-muted">
<Trans i18nKey="skills.empty" components={{ b: <b /> }} />
</div>
) : null}
{rows.map((row) => (
<div key={row.name} className="flex items-center gap-3 px-4 py-3">
<div className="flex-1 min-w-0">
<div className="flex items-center gap-2">
<span className={`text-ui font-medium ${row.enabled ? "" : "text-muted"}`}>
{row.name}
</span>
{row.source !== "local" ? <span className={BADGE}>{row.source}</span> : null}
{/* §6: a rich skill must not look identical to a one-file one. Styled as a
chip with a folder icon so it READS as clickable (live drive: plain
text hid the affordance). */}
{row.files ? (
machine ? (
<span
className="inline-flex items-center gap-1 text-label px-1.5 py-0.5 rounded-md border border-line bg-paper text-muted shrink-0"
title={t("settingsx.skills.files_live_on", { name: machine.name })}
>
<Icon name="folder" size={11} /> {t("skills.file_count", { count: row.files })}
</span>
) : (
<button
className="inline-flex items-center gap-1 text-label px-1.5 py-0.5 rounded-md border border-line bg-paper text-muted hover:text-ink hover:border-lineStrong shrink-0"
title={t("skills.show_folder")}
onClick={() => revealSkill(row.name)}
>
<Icon name="folder" size={11} /> {t("skills.file_count", { count: row.files })}
</button>
)
) : null}
</div>
{/* Full description, wrapping — a skill's one-liner is its menu entry; cutting
it mid-word hid what the skill does (live drive). */}
<div className="text-meta text-muted leading-relaxed">{row.description}</div>
</div>
<button
className={BTN_BORDERED}
title={t("skills.edit_tip")}
onClick={() =>
setEditor({
mode: "edit",
name: row.name,
description: row.description,
instructions: row.instructions,
})
}
>
<Icon name="pencil" size={13} />
</button>
<button
className={BTN_BORDERED}
aria-label={t("skills.delete_aria", { name: row.name })}
onClick={() => remove(row)}
onBlur={() => setArmedDelete(null)}
>
{armedDelete === row.name ? (
t("skills.confirm_delete")
) : (
<Icon name="trash" size={13} />
)}
</button>
<label className="inline-flex items-center gap-1.5 text-meta text-muted">
<input
type="checkbox"
role="switch"
aria-label={t("skills.enabled_aria", { name: row.name })}
checked={row.enabled}
onChange={(e) => {
const on = e.target.checked;
updateSkill(row.name, { enabled: on }, mid).then((res) => {
if (!fail(res))
setNotice({
name: row.name,
text: on ? CONFIRMATION : OFF_NOTE,
tone: on ? "ok" : "warn",
});
refresh();
});
}}
/>
{t("skills.on")}
</label>
</div>
))}
</div>
</section>
);
}