From 3081e4bbe5a124a6b06d07dcf112bf2f23a13d3e Mon Sep 17 00:00:00 2001
From: Matthew Printz <matt@jataware.com>
Date: Tue, 21 Jul 2026 09:31:49 -0600
Subject: [PATCH 1/7] Integration editor page updates

- Remove AdHoc/Specialist Agent from creation list
- Add Skills in its place
- Ability to upload skils as a zip or .md file
  - Zip unpacking handled in browser with results populating local
    interface until save
- Backend changes for saving/updating/deleting skills
---
 beaker-vue/package.json                       |   3 +-
 .../integrations/IntegrationPanel.vue         |  94 ++-
 .../integrations/MCPIntegrationEditor.vue     |   2 +
 .../integrations/MCPIntegrationViewer.vue     |   2 +
 .../integrations/SkillIntegrationEditor.vue   | 534 ++++++++++++++++++
 .../integrations/SkillIntegrationViewer.vue   |   2 +
 .../integrations/SkillResourcePanel.vue       | 451 +++++++++++++++
 .../src/components/integrations/index.ts      |   2 +
 .../src/pages/IntegrationsInterface.vue       | 170 ++++--
 beaker-vue/src/util/integration.ts            |  33 ++
 beaker-vue/src/util/skillArchive.ts           | 150 +++++
 src/beaker_notebook/app/api/integrations.py   |  16 +
 src/beaker_notebook/kernel.py                 |   3 +
 src/beaker_notebook/lib/context.py            |  42 ++
 src/beaker_notebook/lib/integrations/skill.py | 531 ++++++++++++++++-
 15 files changed, 1957 insertions(+), 78 deletions(-)
 create mode 100644 beaker-vue/src/components/integrations/SkillIntegrationEditor.vue
 create mode 100644 beaker-vue/src/components/integrations/SkillResourcePanel.vue
 create mode 100644 beaker-vue/src/util/skillArchive.ts

diff --git a/beaker-vue/package.json b/beaker-vue/package.json
index c05c34ca..3ef00603 100644
--- a/beaker-vue/package.json
+++ b/beaker-vue/package.json
@@ -50,6 +50,7 @@
     "@codemirror/lang-markdown": "^6.3.2",
     "@codemirror/lang-python": "^6.1.7",
     "@codemirror/theme-one-dark": "^6.1.2",
+    "@jataware/beaker-client": "^2.0.9",
     "@jupyterlab/coreutils": "^6.4.1",
     "@jupyterlab/mathjax-extension": "^4.4.1",
     "@jupyterlab/rendermime": "^4.4.1",
@@ -57,7 +58,6 @@
     "@primevue/icons": "^4.3.4",
     "@primevue/themes": "^4.3.4",
     "ansi-html-community": "^0.0.8",
-    "@jataware/beaker-client": "^2.0.9",
     "buffer": "^6.0.3",
     "codemirror": "^6.0.1",
     "codemirror-lang-r": "^0.1.1",
@@ -65,6 +65,7 @@
     "cookie": "^1.0.2",
     "cytoscape": "^3.31.2",
     "escape-html": "^1.0.3",
+    "fflate": "^0.8.3",
     "filesize": "^10.1.6",
     "hash-sum": "^2.0.0",
     "isomorphic-fetch": "^3.0.0",
diff --git a/beaker-vue/src/components/integrations/IntegrationPanel.vue b/beaker-vue/src/components/integrations/IntegrationPanel.vue
index 305c0223..26c1f62c 100644
--- a/beaker-vue/src/components/integrations/IntegrationPanel.vue
+++ b/beaker-vue/src/components/integrations/IntegrationPanel.vue
@@ -1,5 +1,11 @@
 <template>
-    <div class="integrations-panel">
+    <div
+        class="integrations-panel"
+        :class="{ 'drag-over': isDragOver }"
+        @dragover.prevent="onDragOver"
+        @dragleave="onDragLeave"
+        @drop.prevent="onDrop"
+    >
         <div class="integration-header">
             <InputGroup>
                 <InputGroupAddon>
@@ -17,24 +23,35 @@
             </InputGroup>
             <div
                 v-if="!readOnly"
+                class="integration-actions"
                 style="
-                    display: flex;
-                    flex-direction: column;
                     padding-top: 0.25rem;
-                    padding-bottom: 0.25rem;
-                    gap: 0.5rem;
                     width: 100%;
             ">
+                <span style="flex: 1"></span>
                 <RouterLink
                     :to="`/integrations?selected=new${sessionIdParam}`"
-                    aria-label="Edit {{ integration?.name }} "
+                    aria-label="New Integration"
                 >
                     <Button
-                        style="height: 32px"
                         icon="pi pi-plus"
                         label="New Integration"
                     />
                 </RouterLink>
+                <Button
+                    icon="pi pi-upload"
+                    label="Upload"
+                    severity="secondary"
+                    @click="triggerUpload"
+                    v-tooltip.bottom="'Import a skill from a SKILL.md or .zip (or drop a file on this panel)'"
+                />
+                <input
+                    ref="fileInputRef"
+                    type="file"
+                    accept=".zip,.md,text/markdown,application/zip"
+                    style="display: none;"
+                    @change="onFileSelected"
+                />
             </div>
             <div
                 style="
@@ -157,8 +174,49 @@ const props = withDefaults(defineProps<PropTypes>(), {
     readOnly: false,
 });
 
+const emit = defineEmits<{
+    (e: 'upload', file: File): void;
+}>();
+
 const integrations = defineModel<IntegrationMap>()
 
+// --- Skill upload (button + drag-and-drop) ---
+const fileInputRef = ref<HTMLInputElement>();
+const isDragOver = ref(false);
+
+const triggerUpload = () => fileInputRef.value?.click();
+
+const onFileSelected = (event: Event) => {
+    const input = event.target as HTMLInputElement;
+    const file = input.files?.[0];
+    if (file) {
+        emit('upload', file);
+    }
+    // Reset so selecting the same file again re-triggers change.
+    input.value = '';
+};
+
+const onDragOver = () => {
+    if (!props.readOnly) {
+        isDragOver.value = true;
+    }
+};
+
+const onDragLeave = () => {
+    isDragOver.value = false;
+};
+
+const onDrop = (event: DragEvent) => {
+    isDragOver.value = false;
+    if (props.readOnly) {
+        return;
+    }
+    const file = event.dataTransfer?.files?.[0];
+    if (file) {
+        emit('upload', file);
+    }
+};
+
 const urlParams = new URLSearchParams(window.location.search);
 const sessionIdParam = urlParams.has("session") ? `&session=${urlParams.get("session")}` : "";
 
@@ -185,15 +243,14 @@ const processIntegrations = (integrations: Integration[]) =>
 //         .reduce((result, key) => (result[key] = providers[key], result), {})
 
 // Whether a card opens into an editor ("Edit") rather than a read-only viewer
-// ("View"). MCP servers are editable unless provided by a context (see
-// isContextProvidedIntegration); adhoc integrations are always editable; every
-// other type is view-only.
+// ("View"). MCP servers and skills are editable unless provided by a context
+// (see isContextProvidedIntegration); every other type is view-only.
 const isEditableType = (integration: Integration): boolean => {
     const type = getIntegrationProviderType(integration);
-    if (type === 'mcp') {
+    if (type === 'mcp' || type === 'agent-skill') {
         return !isContextProvidedIntegration(integration);
     }
-    return type === 'adhoc';
+    return false;
 };
 
 const allIntegrations = computed<Integration[]>(() => Object.values(integrations.value))
@@ -221,6 +278,19 @@ watch(searchText, () => {
     padding-left: 0.25rem;
     padding-right: 0.25rem;
     gap: 0.5rem;
+
+    &.drag-over {
+        outline: 2px dashed var(--p-primary-color);
+        outline-offset: -4px;
+        border-radius: 4px;
+    }
+
+    .integration-actions {
+        display: flex;
+        flex-direction: row;
+        gap: 0.5rem;
+        align-items: center;
+    }
     div.p-card .p-card-content {
         padding: 0;
     }
diff --git a/beaker-vue/src/components/integrations/MCPIntegrationEditor.vue b/beaker-vue/src/components/integrations/MCPIntegrationEditor.vue
index 5095a22b..6172cb2b 100644
--- a/beaker-vue/src/components/integrations/MCPIntegrationEditor.vue
+++ b/beaker-vue/src/components/integrations/MCPIntegrationEditor.vue
@@ -505,6 +505,8 @@ const save = async () => {
     height: 100%;
 
     .mcp-editor-content {
+        flex: 1 1 auto;
+        min-height: 0;
         overflow: auto;
         display: flex;
         flex-direction: column;
diff --git a/beaker-vue/src/components/integrations/MCPIntegrationViewer.vue b/beaker-vue/src/components/integrations/MCPIntegrationViewer.vue
index b1ff9826..941345ca 100644
--- a/beaker-vue/src/components/integrations/MCPIntegrationViewer.vue
+++ b/beaker-vue/src/components/integrations/MCPIntegrationViewer.vue
@@ -259,6 +259,8 @@ const catalogEmpty = computed<boolean>(() =>
     height: 100%;
 
     .mcp-viewer-content {
+        flex: 1 1 auto;
+        min-height: 0;
         overflow: auto;
         display: flex;
         flex-direction: column;
diff --git a/beaker-vue/src/components/integrations/SkillIntegrationEditor.vue b/beaker-vue/src/components/integrations/SkillIntegrationEditor.vue
new file mode 100644
index 00000000..915b6066
--- /dev/null
+++ b/beaker-vue/src/components/integrations/SkillIntegrationEditor.vue
@@ -0,0 +1,534 @@
+<template>
+    <div class="skill-integration-editor">
+        <div class="skill-editor-content">
+            <div v-if="isNew && pendingResourceCount" class="skill-import-note">
+                <i class="pi pi-inbox"></i>
+                <span>
+                    {{ pendingResourceCount }} resource file{{ pendingResourceCount === 1 ? '' : 's' }} will be
+                    imported when you save.<template v-if="pendingSkippedCount"> {{ pendingSkippedCount }} non-text
+                    file{{ pendingSkippedCount === 1 ? '' : 's' }} skipped.</template>
+                </span>
+            </div>
+
+            <Fieldset legend="Source">
+                <p>
+                    A <code>local</code> skill lives on disk and is fully editable here. A
+                    <code>remote</code> skill is fetched from a URL; only its location is editable and the
+                    fetched content is read-only.
+                </p>
+                <div class="skill-form-row">
+                    <label>Type</label>
+                    <Select
+                        :model-value="sourceType"
+                        @update:model-value="onSourceTypeChange"
+                        :options="sourceTypeOptions"
+                        option-label="label"
+                        option-value="value"
+                        :disabled="!isNew"
+                    />
+                </div>
+                <div class="skill-form-row" v-if="sourceType === 'remote'">
+                    <label>URL</label>
+                    <div class="skill-url-row">
+                        <InputText
+                            :model-value="url"
+                            @update:model-value="(value) => { url = value ?? ''; remotePreviewed = false; markDirty(); }"
+                            :disabled="!isNew"
+                            placeholder="https://example.com/my-skill/ (containing SKILL.md)"
+                            style="font-family: monospace; flex: 1 1 auto;"
+                        />
+                        <Button
+                            v-if="isNew"
+                            label="Fetch"
+                            icon="pi pi-download"
+                            :loading="fetching"
+                            :disabled="!url.trim()"
+                            @click="fetchFromUrl"
+                            v-tooltip.bottom="'Fetch the skill from this URL to preview it before saving'"
+                        />
+                    </div>
+                    <small>URL of the skill directory or its <code>SKILL.md</code>. Fetch to preview before saving.</small>
+                </div>
+            </Fieldset>
+
+            <template v-if="sourceType === 'local' || !isNew || remotePreviewed">
+                <Fieldset legend="Name">
+                    <InputText
+                        :model-value="name"
+                        @update:model-value="(value) => { name = value ?? ''; markDirty(); }"
+                        :disabled="!editable"
+                        placeholder="Skill name"
+                    />
+                    <small v-if="!isNew && editable">The folder name (slug) is fixed after creation; renaming updates only the display name.</small>
+                </Fieldset>
+
+                <Fieldset legend="Description">
+                    <p>A short summary the agent uses to decide when this skill is relevant.</p>
+                    <InputText
+                        :model-value="description"
+                        @update:model-value="(value) => { description = value ?? ''; markDirty(); }"
+                        :disabled="!editable"
+                        placeholder="One-line description"
+                    />
+                </Fieldset>
+
+                <Fieldset legend="Metadata">
+                    <div class="skill-form-grid">
+                        <div class="skill-form-row">
+                            <label>License</label>
+                            <InputText :model-value="license" @update:model-value="(v) => { license = v ?? ''; markDirty(); }" :disabled="!editable" placeholder="e.g. MIT" />
+                        </div>
+                        <div class="skill-form-row">
+                            <label>Compatibility</label>
+                            <InputText :model-value="compatibility" @update:model-value="(v) => { compatibility = v ?? ''; markDirty(); }" :disabled="!editable" placeholder="e.g. python>=3.11" />
+                        </div>
+                        <div class="skill-form-row">
+                            <label>Allowed tools</label>
+                            <InputChips
+                                v-model="allowedToolsList"
+                                @update:model-value="markDirty"
+                                :disabled="!editable"
+                                separator=","
+                                :add-on-blur="true"
+                                placeholder="Type a tool and press Enter"
+                                class="skill-tools-chips"
+                            />
+                            <small v-if="editable">Press Enter (or comma) after each tool.</small>
+                        </div>
+                        <div class="skill-form-row">
+                            <label>Custom metadata</label>
+                            <div class="skill-kv-editor">
+                                <div class="skill-kv-item" v-for="(row, index) in metadataRows" :key="index">
+                                    <InputText v-model="row.key" @update:model-value="markDirty" :disabled="!editable" placeholder="key" style="font-family: monospace;" />
+                                    <InputText v-model="row.value" @update:model-value="markDirty" :disabled="!editable" placeholder="value" />
+                                    <Button v-if="editable" icon="pi pi-trash" severity="danger" text @click="() => { metadataRows.splice(index, 1); markDirty(); }" v-tooltip="'Remove'" />
+                                </div>
+                                <Button v-if="editable" class="skill-add-button" icon="pi pi-plus" label="Add metadata" text @click="() => { metadataRows.push({ key: '', value: '' }); markDirty(); }" />
+                            </div>
+                        </div>
+                    </div>
+                </Fieldset>
+
+                <Fieldset legend="Instructions (SKILL.md)">
+                    <p>The skill's full instructions, disclosed to the agent when it loads the skill.</p>
+                    <div class="skill-editor-height" v-if="editable">
+                        <CodeEditor
+                            language="markdown"
+                            :autocomplete-enabled="false"
+                            :model-value="instructions"
+                            @update:model-value="(v) => { instructions = v ?? ''; markDirty(); }"
+                        />
+                    </div>
+                    <div v-else class="skill-description" v-html="renderedInstructions"></div>
+                </Fieldset>
+            </template>
+
+            <p v-if="!editable && sourceType === 'remote' && !isNew" class="skill-readonly-note">
+                <i class="pi pi-info-circle"></i>
+                <span>This is a remote skill; its content is fetched from the URL above and is read-only.</span>
+            </p>
+        </div>
+
+        <div class="skill-editor-actions">
+            <Button
+                v-if="deletable"
+                @click="remove"
+                icon="pi pi-trash"
+                label="Delete"
+                severity="danger"
+                outlined
+            />
+            <Button
+                v-if="canSave"
+                @click="save"
+                icon="pi pi-save"
+                label="Save Changes"
+                severity="success"
+                :disabled="!model.unsavedChanges"
+            />
+        </div>
+    </div>
+</template>
+
+
+<script setup lang="ts">
+
+import { computed, ref, watch, inject } from 'vue';
+import {
+    type IntegrationInterfaceState,
+    type SkillIntegration,
+    type SkillMetadataResource,
+    type SkillInstructionsResource,
+    isContextProvidedIntegration,
+    filterByResourceType,
+    previewRemoteSkill,
+} from '../../util/integration';
+
+import Fieldset from 'primevue/fieldset';
+import InputText from 'primevue/inputtext';
+import InputChips from 'primevue/inputchips';
+import Select from 'primevue/select';
+import Button from 'primevue/button';
+
+import { marked } from 'marked';
+
+import CodeEditor from '../misc/CodeEditor.vue';
+
+const showToast = inject<any>('show_toast');
+
+const props = defineProps<{
+    sessionId: string,
+    fetchResources: () => Promise<void>,
+    deleteResource: (resourceId: string) => Promise<void>,
+    modifyResource: (body: object, resourceId?: string) => Promise<void>,
+    modifyIntegration: (body: object, integrationId?: string) => Promise<void>,
+    deleteIntegration: (integrationId: string) => Promise<void>,
+}>();
+
+const model = defineModel<IntegrationInterfaceState>();
+
+const selectedIntegration = computed<SkillIntegration>(() =>
+    model.value.integrations[model.value.selected] as SkillIntegration);
+
+const isNew = computed<boolean>(() => model.value.selected === "new");
+
+// A skill is editable here when it is local and not provided by a context
+// (context-bundled skills render through the read-only viewer instead).
+const editable = computed<boolean>(() =>
+    sourceType.value === 'local' && !isContextProvidedIntegration(selectedIntegration.value));
+
+// A saved, non-context skill (local or remote) can be deleted.
+const deletable = computed<boolean>(() =>
+    !isNew.value && !isContextProvidedIntegration(selectedIntegration.value));
+
+// The editor can persist changes for editable (local) skills, and for a new
+// remote skill (whose URL is still editable). An existing remote skill has no
+// editable fields, so it shows no Save button.
+const canSave = computed<boolean>(() =>
+    editable.value || (sourceType.value === 'remote' && isNew.value));
+
+// Resources enumerated from an uploaded archive, awaiting the initial save.
+const pendingResourceCount = computed<number>(() =>
+    ((selectedIntegration.value as any)?.pendingResources ?? []).length);
+const pendingSkippedCount = computed<number>(() =>
+    ((selectedIntegration.value as any)?.pendingSkipped ?? []).length);
+
+const sourceTypeOptions = [
+    { label: "Local (on disk)", value: "local" },
+    { label: "Remote (URL)", value: "remote" },
+];
+
+// --- Editable form state, synced from the selected integration ---
+const sourceType = ref<'local' | 'remote'>('local');
+const url = ref<string>('');
+const name = ref<string>('');
+const description = ref<string>('');
+const instructions = ref<string>('');
+const license = ref<string>('');
+const compatibility = ref<string>('');
+const allowedToolsList = ref<string[]>([]);
+const metadataRows = ref<{ key: string, value: string }[]>([]);
+
+// Whether a new remote skill's SKILL.md has been fetched to populate the form.
+const remotePreviewed = ref<boolean>(false);
+const fetching = ref<boolean>(false);
+
+const metadataResource = computed<SkillMetadataResource | undefined>(() =>
+    Object.values(filterByResourceType<SkillMetadataResource>(
+        selectedIntegration.value?.resources, "skill_metadata"))[0]);
+
+const instructionsResource = computed<SkillInstructionsResource | undefined>(() =>
+    Object.values(filterByResourceType<SkillInstructionsResource>(
+        selectedIntegration.value?.resources, "skill_instructions"))[0]);
+
+const syncFromIntegration = () => {
+    const integration = selectedIntegration.value;
+    if (!integration) return;
+    sourceType.value = integration.source_type ?? 'local';
+    url.value = integration.url ?? '';
+    name.value = integration.name ?? '';
+    description.value = integration.description ?? '';
+    instructions.value = instructionsResource.value?.content ?? '';
+    const metadata = metadataResource.value;
+    license.value = metadata?.license ?? '';
+    compatibility.value = metadata?.compatibility ?? '';
+    allowedToolsList.value = (metadata?.allowed_tools ?? '')
+        .split(',').map((tool) => tool.trim()).filter((tool) => tool !== '');
+    metadataRows.value = Object.entries(metadata?.skill_metadata ?? {})
+        .map(([key, value]) => ({ key, value: String(value) }));
+};
+
+const markDirty = () => {
+    model.value.unsavedChanges = true;
+};
+
+const onSourceTypeChange = (value: 'local' | 'remote') => {
+    sourceType.value = value;
+    remotePreviewed.value = false;
+    markDirty();
+};
+
+// Fetch and parse the remote SKILL.md so the form shows the skill's actual
+// content before the user commits. The fetched values are merged into the
+// working "new" integration (which keeps its uuid "new" so save still adds).
+const fetchFromUrl = async () => {
+    if (!url.value.trim()) return;
+    fetching.value = true;
+    try {
+        const preview = await previewRemoteSkill(props.sessionId, {
+            provider: selectedIntegration.value.provider,
+            url: url.value,
+        });
+        const working = selectedIntegration.value;
+        working.name = preview.name;
+        working.description = preview.description;
+        working.resources = preview.resources ?? {};
+        syncFromIntegration();
+        // syncFromIntegration resets url from the (urless) working copy; restore it.
+        url.value = (preview.url || url.value);
+        remotePreviewed.value = true;
+    } catch (e) {
+        console.error('Failed to fetch remote skill:', e);
+        showToast({
+            title: 'Fetch failed',
+            detail: `Could not load a skill from that URL. ${(e as Error)?.message ?? ''}`.trim(),
+            severity: 'error',
+            life: 5000,
+        });
+    } finally {
+        fetching.value = false;
+    }
+};
+
+const renderedInstructions = computed<string>(() =>
+    instructions.value ? marked.parse(instructions.value) as string : "");
+
+watch(() => model.value.selected, () => {
+    remotePreviewed.value = false;
+    syncFromIntegration();
+    // A freshly created skill arrives pre-dirtied so its Save button shows
+    // immediately; only clear the flag when landing on an existing one.
+    if (!isNew.value) {
+        model.value.unsavedChanges = false;
+    }
+}, { immediate: true });
+
+// Re-sync when an existing integration's resources arrive/refresh (e.g. after a
+// save re-fetches the authoritative copy), unless the user has edits pending.
+watch(() => selectedIntegration.value?.resources, () => {
+    if (!model.value.unsavedChanges) {
+        syncFromIntegration();
+    }
+});
+
+watch(model, ({ unsavedChanges }) => {
+    onbeforeunload = unsavedChanges ? () => true : undefined;
+}, { deep: true });
+
+const save = async () => {
+    const integration = selectedIntegration.value;
+    if (!integration) return;
+
+    // Capture before the save flips the selection from "new" to the saved id.
+    const wasNew = isNew.value;
+    const pending = wasNew ? ((integration as any).pendingResources ?? []) as object[] : [];
+
+    const payload: Record<string, any> = {
+        ...integration,
+        source_type: sourceType.value,
+        url: url.value,
+    };
+    // Resources are persisted through their own CRUD path; drop the (possibly
+    // large) resource payloads from the integration body.
+    delete payload.resources;
+    delete payload.pendingResources;
+    delete payload.pendingSkipped;
+
+    if (sourceType.value === 'remote') {
+        if (!url.value.trim()) {
+            showToast({ title: 'URL required', detail: 'Enter the URL of the remote skill.', severity: 'warn', life: 4000 });
+            return;
+        }
+    } else {
+        if (!name.value.trim()) {
+            showToast({ title: 'Name required', detail: 'Enter a name for the skill.', severity: 'warn', life: 4000 });
+            return;
+        }
+        payload.name = name.value;
+        payload.description = description.value;
+        payload.instructions = instructions.value;
+        payload.license = license.value;
+        payload.compatibility = compatibility.value;
+        payload.allowed_tools = allowedToolsList.value.join(", ");
+        payload.skill_metadata = Object.fromEntries(
+            metadataRows.value.filter((row) => row.key.trim() !== "").map((row) => [row.key, row.value]));
+    }
+
+    await props.modifyIntegration(payload, wasNew ? undefined : model.value.selected);
+
+    // For a newly-created skill, upload any resources enumerated from an
+    // uploaded archive now that the skill exists on disk. modifyResource targets
+    // the just-saved integration (selection was updated by modifyIntegration).
+    let failed = 0;
+    for (const resource of pending) {
+        try {
+            await props.modifyResource(resource);
+        } catch (e) {
+            failed += 1;
+            console.error('Failed to add uploaded resource', resource, e);
+        }
+    }
+
+    showToast({
+        title: failed ? 'Saved with errors' : 'Saved!',
+        detail: pending.length
+            ? `Saved with ${pending.length - failed} of ${pending.length} resource(s) imported${failed ? `; ${failed} failed (see console).` : '.'}`
+            : 'The skill has been saved and will be available to the agent.',
+        severity: failed ? 'warn' : 'success',
+        life: 4000,
+    });
+
+    if (wasNew) {
+        delete model.value.integrations["new"];
+    }
+    model.value.unsavedChanges = false;
+};
+
+const remove = async () => {
+    const integration = selectedIntegration.value;
+    if (!integration || isNew.value) return;
+    const detail = sourceType.value === 'local'
+        ? ' and its files from disk'
+        : ' from your skills list';
+    if (!confirm(`Delete skill "${integration.name}"? This permanently removes it${detail}.`)) {
+        return;
+    }
+    await props.deleteIntegration(model.value.selected);
+    model.value.unsavedChanges = false;
+    showToast({
+        title: 'Deleted',
+        detail: `Removed "${integration.name}".`,
+        severity: 'success',
+        life: 4000,
+    });
+};
+
+</script>
+
+<style lang="scss">
+.skill-integration-editor {
+    display: flex;
+    flex-direction: column;
+    height: 100%;
+
+    .skill-editor-content {
+        flex: 1 1 auto;
+        min-height: 0;
+        overflow: auto;
+        display: flex;
+        flex-direction: column;
+    }
+}
+
+.skill-editor-actions {
+    flex: 1 0;
+    margin: 0.2rem;
+    display: flex;
+    justify-content: flex-end;
+    gap: 0.5rem;
+
+    > * {
+        flex-shrink: 0;
+    }
+}
+
+.skill-form-grid {
+    display: flex;
+    flex-direction: column;
+    gap: 0.75rem;
+}
+
+.skill-form-row {
+    display: flex;
+    flex-direction: column;
+    gap: 0.25rem;
+
+    > label {
+        font-weight: 600;
+    }
+    > small {
+        color: var(--p-text-muted-color);
+    }
+}
+
+.skill-kv-editor {
+    display: flex;
+    flex-direction: column;
+    gap: 0.35rem;
+}
+
+.skill-kv-item {
+    display: flex;
+    flex-direction: row;
+    gap: 0.35rem;
+    align-items: center;
+
+    > .p-inputtext:first-of-type {
+        flex: 1 1 30%;
+    }
+    > .p-inputtext:nth-of-type(2) {
+        flex: 2 1 60%;
+    }
+}
+
+.skill-add-button {
+    width: fit-content;
+}
+
+.skill-url-row {
+    display: flex;
+    flex-direction: row;
+    gap: 0.35rem;
+    align-items: center;
+}
+
+.skill-tools-chips {
+    width: 100%;
+}
+
+.skill-editor-height {
+    height: 20rem;
+    display: flex;
+    flex-direction: column;
+}
+
+.skill-description {
+    h1 { font-size: 1.25rem; margin-bottom: 1rem; }
+    h2 { font-size: 1.2rem; margin-bottom: 0.8rem; }
+    h3 { font-size: 1.15rem; margin-bottom: 0.8rem; }
+    p, ul, li { margin-bottom: 0.8rem; margin-top: 0rem; }
+    > *:first-child { margin-top: 0rem; }
+}
+
+.skill-readonly-note {
+    display: flex;
+    align-items: center;
+    gap: 0.5rem;
+    color: var(--p-text-muted-color);
+}
+
+.skill-import-note {
+    display: flex;
+    align-items: center;
+    gap: 0.5rem;
+    padding: 0.6rem 0.75rem;
+    margin-bottom: 1rem;
+    border-radius: 4px;
+    background: var(--p-surface-100);
+    color: var(--p-text-color);
+
+    > i {
+        color: var(--p-primary-color);
+    }
+}
+</style>
diff --git a/beaker-vue/src/components/integrations/SkillIntegrationViewer.vue b/beaker-vue/src/components/integrations/SkillIntegrationViewer.vue
index bc661b63..493787e5 100644
--- a/beaker-vue/src/components/integrations/SkillIntegrationViewer.vue
+++ b/beaker-vue/src/components/integrations/SkillIntegrationViewer.vue
@@ -142,6 +142,8 @@ const exampleResources = computed<SkillExampleResource[]>(() => {
     height: 100%;
 
     .skill-viewer-content {
+        flex: 1 1 auto;
+        min-height: 0;
         overflow: auto;
         display: flex;
         flex-direction: column;
diff --git a/beaker-vue/src/components/integrations/SkillResourcePanel.vue b/beaker-vue/src/components/integrations/SkillResourcePanel.vue
new file mode 100644
index 00000000..9bfc137b
--- /dev/null
+++ b/beaker-vue/src/components/integrations/SkillResourcePanel.vue
@@ -0,0 +1,451 @@
+<template>
+    <div class="skill-resource-panel">
+        <!-- List view -->
+        <template v-if="viewState.view === 'list'">
+            <div class="skill-resource-header">
+                <i>{{ allResources.length }} resource{{ allResources.length === 1 ? '' : 's' }}</i>
+                <div v-if="editable" class="skill-resource-add-buttons">
+                    <Button icon="pi pi-plus" label="File" size="small" text @click="startNew('skill_file')" v-tooltip.bottom="'Add a reference/script/asset file'" />
+                    <Button icon="pi pi-plus" label="Example" size="small" text @click="startNew('skill_example')" v-tooltip.bottom="'Add a code example'" />
+                </div>
+            </div>
+
+            <p v-if="disabled && !isContext" class="skill-resource-hint">
+                <i class="pi pi-info-circle"></i>
+                <span>Save the skill before adding resources.</span>
+            </p>
+            <p v-else-if="!editable && !disabled" class="skill-resource-hint">
+                <i class="pi pi-info-circle"></i>
+                <span>This skill's resources are read-only.</span>
+            </p>
+
+            <div v-if="pendingResources.length" class="skill-resource-pending">
+                <i class="skill-resource-pending-title">
+                    {{ pendingResources.length }} file{{ pendingResources.length === 1 ? '' : 's' }} to import on save:
+                </i>
+                <div
+                    class="skill-resource-card"
+                    v-for="(resource, index) in pendingResources"
+                    :key="`pending-${index}`"
+                >
+                    <Card>
+                        <template #title>
+                            <div class="skill-resource-card-title">
+                                <i :class="resource.resource_type === 'skill_example' ? 'pi pi-code' : 'pi pi-file'"></i>
+                                <span class="skill-resource-card-label">{{ pendingLabel(resource) }}</span>
+                                <span class="skill-resource-pending-badge">pending</span>
+                            </div>
+                        </template>
+                    </Card>
+                </div>
+            </div>
+
+            <div class="skill-resource-list">
+                <div
+                    class="skill-resource-card"
+                    v-for="resource in allResources"
+                    :key="resource.resource_id"
+                    @mouseenter="hoveredResource = resource.resource_id"
+                    @mouseleave="hoveredResource = undefined"
+                >
+                    <Card
+                        @click="openResource(resource)"
+                        :pt="{ root: { style: 'transition: background-color 150ms linear;' + (hoveredResource === resource.resource_id ? 'background-color: var(--p-surface-100); cursor: pointer;' : '') } }"
+                    >
+                        <template #title>
+                            <div class="skill-resource-card-title">
+                                <i :class="resourceIcon(resource)"></i>
+                                <span class="skill-resource-card-label">{{ resourceLabel(resource) }}</span>
+                                <Button
+                                    v-if="editable"
+                                    icon="pi pi-trash"
+                                    severity="danger"
+                                    text
+                                    size="small"
+                                    @click.stop="removeResource(resource)"
+                                    v-tooltip.left="'Delete'"
+                                />
+                                <i v-else class="pi pi-chevron-right skill-resource-arrow" :style="hoveredResource === resource.resource_id ? 'opacity: 1;' : 'opacity: 0;'" />
+                            </div>
+                        </template>
+                    </Card>
+                </div>
+                <div v-if="allResources.length === 0 && pendingResources.length === 0" class="skill-resource-empty">
+                    <i>No resource files yet.</i>
+                </div>
+            </div>
+        </template>
+
+        <!-- Focused / new view -->
+        <template v-else>
+            <div class="skill-resource-focused-header">
+                <Button severity="secondary" icon="pi pi-arrow-left" label="Back" size="small" @click="backToList" style="width: fit-content;" />
+                <span class="skill-resource-focused-title">{{ focusedLabel }}</span>
+            </div>
+
+            <div class="skill-resource-focused-form" v-if="viewState.view === 'new'">
+                <div class="skill-resource-path-fields" v-if="viewState.resourceType === 'skill_file'">
+                    <Select v-model="draftDir" :options="resourceDirs" placeholder="Directory" />
+                    <InputText v-model="draftFilename" placeholder="filename.md" style="font-family: monospace; flex: 1 1 auto;" />
+                </div>
+                <div class="skill-resource-path-fields" v-else>
+                    <span class="skill-resource-fixed-prefix">examples/</span>
+                    <InputText v-model="draftFilename" placeholder="example.md" style="font-family: monospace; flex: 1 1 auto;" />
+                </div>
+            </div>
+
+            <div class="skill-resource-focused-content">
+                <div v-if="loadingContent" class="skill-resource-loading">
+                    <ProgressSpinner style="width: 2rem; height: 2rem;" />
+                    Loading resource...
+                </div>
+                <CodeEditor
+                    v-else
+                    :language="focusedLanguage"
+                    :autocomplete-enabled="false"
+                    :model-value="draftContent"
+                    :disabled="!editable"
+                    @update:model-value="(v) => { draftContent = v ?? ''; }"
+                />
+            </div>
+
+            <div class="skill-resource-focused-actions" v-if="editable">
+                <Button icon="pi pi-save" label="Save" severity="success" size="small" :disabled="!canSave" @click="saveFocused" />
+            </div>
+        </template>
+    </div>
+</template>
+
+
+<script setup lang="ts">
+
+import { ref, computed } from 'vue';
+import Button from "primevue/button";
+import Card from 'primevue/card';
+import Select from "primevue/select";
+import InputText from "primevue/inputtext";
+import ProgressSpinner from 'primevue/progressspinner';
+import CodeEditor from '../misc/CodeEditor.vue';
+import {
+    type IntegrationInterfaceState,
+    type IntegrationResource,
+    type SkillFileResource,
+    type SkillExampleResource,
+    isContextProvidedIntegration,
+    getResource,
+} from '../../util/integration';
+
+const props = defineProps<{
+    sessionId: string;
+    disabled?: boolean;
+    deleteResource: (resourceId: string) => Promise<void>,
+    modifyResource: (body: object, resourceId?: string) => Promise<void>,
+}>();
+
+const model = defineModel<IntegrationInterfaceState>();
+
+const resourceDirs = ["references", "scripts", "assets"];
+
+type ViewState =
+    | { view: "list" }
+    | { view: "focused"; resourceId: string }
+    | { view: "new"; resourceType: "skill_file" | "skill_example" };
+
+const viewState = ref<ViewState>({ view: 'list' });
+const hoveredResource = ref<string | undefined>(undefined);
+const loadingContent = ref<boolean>(false);
+
+// Draft state for the focused editor (both new and existing resources).
+const draftDir = ref<string>("references");
+const draftFilename = ref<string>("");
+const draftContent = ref<string>("");
+
+const selectedIntegration = computed(() => model.value.integrations[model.value.selected]);
+
+const isContext = computed<boolean>(() => isContextProvidedIntegration(selectedIntegration.value));
+
+const editable = computed<boolean>(() =>
+    (selectedIntegration.value as any)?.source_type === 'local'
+    && !isContext.value
+    && !props.disabled);
+
+const allResources = computed<IntegrationResource[]>(() => {
+    const resources = selectedIntegration.value?.resources ?? {};
+    return Object.values(resources).filter(
+        (r) => r.resource_type === 'skill_file' || r.resource_type === 'skill_example');
+});
+
+// Resources enumerated from an uploaded archive, shown read-only until the new
+// skill is saved (at which point they are created and appear in allResources).
+const pendingResources = computed<any[]>(() =>
+    (selectedIntegration.value as any)?.pendingResources ?? []);
+
+const pendingLabel = (resource: any): string =>
+    resource.resource_type === 'skill_example'
+        ? `examples/${resource.filename}`
+        : resource.relative_path;
+
+const resourceLabel = (resource: IntegrationResource): string => {
+    if (resource.resource_type === 'skill_file') {
+        return (resource as SkillFileResource).relative_path;
+    }
+    if (resource.resource_type === 'skill_example') {
+        return `examples/${(resource as SkillExampleResource).filename}`;
+    }
+    return resource.resource_id;
+};
+
+const resourceIcon = (resource: IntegrationResource): string =>
+    resource.resource_type === 'skill_example' ? 'pi pi-code' : 'pi pi-file';
+
+const languageForPath = (path: string): string => {
+    if (path.endsWith('.py')) return 'python';
+    if (path.endsWith('.js') || path.endsWith('.ts')) return 'javascript';
+    if (path.endsWith('.sh') || path.endsWith('.bash')) return 'shell';
+    if (path.endsWith('.json')) return 'json';
+    if (path.endsWith('.yaml') || path.endsWith('.yml')) return 'yaml';
+    return 'markdown';
+};
+
+const focusedResource = computed<IntegrationResource | undefined>(() => {
+    if (viewState.value.view !== 'focused') return undefined;
+    return selectedIntegration.value?.resources?.[viewState.value.resourceId];
+});
+
+const focusedLabel = computed<string>(() => {
+    if (viewState.value.view === 'new') {
+        return viewState.value.resourceType === 'skill_file' ? 'New file' : 'New example';
+    }
+    return focusedResource.value ? resourceLabel(focusedResource.value) : '';
+});
+
+const focusedLanguage = computed<string>(() => {
+    if (viewState.value.view === 'new') {
+        return viewState.value.resourceType === 'skill_file'
+            ? languageForPath(draftFilename.value)
+            : 'markdown';
+    }
+    return focusedResource.value ? languageForPath(resourceLabel(focusedResource.value)) : 'markdown';
+});
+
+const canSave = computed<boolean>(() => {
+    if (viewState.value.view === 'new') {
+        return draftFilename.value.trim() !== "";
+    }
+    return true;
+});
+
+const backToList = () => {
+    viewState.value = { view: 'list' };
+    draftFilename.value = "";
+    draftContent.value = "";
+    draftDir.value = "references";
+};
+
+const startNew = (resourceType: "skill_file" | "skill_example") => {
+    draftFilename.value = "";
+    draftContent.value = "";
+    draftDir.value = "references";
+    viewState.value = { view: 'new', resourceType };
+};
+
+const openResource = async (resource: IntegrationResource) => {
+    viewState.value = { view: 'focused', resourceId: resource.resource_id };
+    const cached = (resource as SkillFileResource | SkillExampleResource).content;
+    if (cached !== undefined && cached !== null) {
+        draftContent.value = cached;
+        return;
+    }
+    draftContent.value = "";
+    loadingContent.value = true;
+    try {
+        const fetched = await getResource(props.sessionId, model.value.selected, resource.resource_type, resource.resource_id);
+        const content = (fetched as any).content ?? "";
+        (resource as any).content = content;
+        draftContent.value = content;
+    } catch (e) {
+        console.error('Failed to load resource content:', e);
+    } finally {
+        loadingContent.value = false;
+    }
+};
+
+const saveFocused = async () => {
+    if (viewState.value.view === 'new') {
+        const filename = draftFilename.value.trim();
+        if (!filename) return;
+        const body = viewState.value.resourceType === 'skill_file'
+            ? {
+                resource_type: 'skill_file',
+                relative_path: `${draftDir.value}/${filename}`,
+                name: filename,
+                content: draftContent.value,
+            }
+            : {
+                resource_type: 'skill_example',
+                filename,
+                content: draftContent.value,
+            };
+        await props.modifyResource(body);
+    } else if (viewState.value.view === 'focused' && focusedResource.value) {
+        await props.modifyResource(
+            { ...focusedResource.value, content: draftContent.value },
+            focusedResource.value.resource_id,
+        );
+    }
+    backToList();
+};
+
+const removeResource = async (resource: IntegrationResource) => {
+    if (!confirm(`Delete ${resourceLabel(resource)}?`)) return;
+    await props.deleteResource(resource.resource_id);
+    delete selectedIntegration.value.resources[resource.resource_id];
+};
+
+</script>
+
+<style lang="scss">
+.skill-resource-panel {
+    display: flex;
+    flex-direction: column;
+    gap: 0.75rem;
+    padding-right: 0.5rem;
+    height: 100%;
+}
+
+.skill-resource-header {
+    display: flex;
+    flex-direction: row;
+    align-items: center;
+    justify-content: space-between;
+    gap: 0.5rem;
+}
+
+.skill-resource-add-buttons {
+    display: flex;
+    gap: 0.25rem;
+}
+
+.skill-resource-hint {
+    display: flex;
+    align-items: center;
+    gap: 0.5rem;
+    color: var(--p-text-muted-color);
+    margin: 0;
+}
+
+.skill-resource-list {
+    display: flex;
+    flex-direction: column;
+    overflow: auto;
+    padding: 0.2rem;
+
+    div.p-card .p-card-content { padding: 0; }
+    div.p-card-body { padding: 0.6rem; }
+    div.p-card .p-card-title { margin-bottom: 0; }
+
+    .skill-resource-card > div { margin-bottom: 0.5rem; }
+}
+
+.skill-resource-card-title {
+    display: flex;
+    flex-direction: row;
+    align-items: center;
+    gap: 0.5rem;
+
+    .skill-resource-card-label {
+        flex: 1 1;
+        font-size: 0.9rem;
+        font-weight: 500;
+        font-family: monospace;
+        word-break: break-all;
+    }
+}
+
+.skill-resource-arrow {
+    transition: opacity 150ms linear;
+}
+
+.skill-resource-empty {
+    padding: 1rem 0.2rem;
+    color: var(--p-text-muted-color);
+}
+
+.skill-resource-pending {
+    display: flex;
+    flex-direction: column;
+    padding: 0.2rem;
+
+    .skill-resource-pending-title {
+        color: var(--p-text-muted-color);
+        margin-bottom: 0.25rem;
+    }
+
+    .skill-resource-card > div {
+        margin-bottom: 0.5rem;
+    }
+
+    div.p-card .p-card-content { padding: 0; }
+    div.p-card-body { padding: 0.6rem; }
+    div.p-card .p-card-title { margin-bottom: 0; }
+}
+
+.skill-resource-pending-badge {
+    font-size: 0.7rem;
+    text-transform: uppercase;
+    letter-spacing: 0.03em;
+    padding: 0.1rem 0.4rem;
+    border-radius: 3px;
+    background: var(--p-surface-200);
+    color: var(--p-text-muted-color);
+    flex-shrink: 0;
+}
+
+.skill-resource-focused-header {
+    display: flex;
+    flex-direction: row;
+    align-items: center;
+    gap: 0.75rem;
+
+    .skill-resource-focused-title {
+        font-weight: 600;
+        font-family: monospace;
+        font-size: 0.9rem;
+        word-break: break-all;
+    }
+}
+
+.skill-resource-path-fields {
+    display: flex;
+    flex-direction: row;
+    align-items: center;
+    gap: 0.35rem;
+
+    .skill-resource-fixed-prefix {
+        font-family: monospace;
+        color: var(--p-text-muted-color);
+    }
+}
+
+.skill-resource-focused-content {
+    flex: 1 1;
+    overflow: auto;
+    min-height: 16rem;
+    display: flex;
+    flex-direction: column;
+}
+
+.skill-resource-focused-actions {
+    display: flex;
+    justify-content: flex-end;
+}
+
+.skill-resource-loading {
+    display: flex;
+    flex-direction: column;
+    align-items: center;
+    gap: 0.5rem;
+    padding: 2rem;
+    color: var(--p-text-muted-color);
+}
+</style>
diff --git a/beaker-vue/src/components/integrations/index.ts b/beaker-vue/src/components/integrations/index.ts
index d867c73a..74ec3d9a 100644
--- a/beaker-vue/src/components/integrations/index.ts
+++ b/beaker-vue/src/components/integrations/index.ts
@@ -7,3 +7,5 @@ export { default as MCPIntegrationViewer } from './MCPIntegrationViewer.vue';
 export { default as MCPToolsPanel } from './MCPToolsPanel.vue';
 export { default as ResourceViewer } from './ResourceViewer.vue';
 export { default as SkillIntegrationViewer } from './SkillIntegrationViewer.vue';
+export { default as SkillIntegrationEditor } from './SkillIntegrationEditor.vue';
+export { default as SkillResourcePanel } from './SkillResourcePanel.vue';
diff --git a/beaker-vue/src/pages/IntegrationsInterface.vue b/beaker-vue/src/pages/IntegrationsInterface.vue
index e3f1edc5..86fbbe4c 100644
--- a/beaker-vue/src/pages/IntegrationsInterface.vue
+++ b/beaker-vue/src/pages/IntegrationsInterface.vue
@@ -15,7 +15,7 @@
         @session-status-changed="statusChanged"
     >
         <div class="integration-container">
-            <div class="beaker-notebook">
+            <div class="integration-main">
                 <div class="integration-loading" v-if="beakerSession?.status === 'connecting'">
                     <ProgressSpinner></ProgressSpinner>
                     Loading integrations...
@@ -46,7 +46,7 @@
                             :model="newIntegrationItems"
                             @click="() => {
                                 if (confirmUnsavedChanges()) {
-                                    newIntegration('adhoc');
+                                    newIntegration('skill');
                                 }
                             }"
                         />
@@ -57,15 +57,18 @@
                         <p>Select an integration to view or edit, or create a new one to get started.</p>
                     </div>
 
-                    <component
-                        v-else
-                        :is="centerComponent"
-                        v-model="integrations"
-                        :deleteResource="deleteResourceOnSelectedIntegration"
-                        :modifyResource="modifyResourceForSelectedIntegration"
-                        :modifyIntegration="modifySelectedIntegration"
-                        :fetchResources="fetchResourcesForSelectedIntegration"
-                    />
+                    <div v-else class="integration-center">
+                        <component
+                            :is="centerComponent"
+                            v-model="integrations"
+                            :sessionId="sessionId"
+                            :deleteResource="deleteResourceOnSelectedIntegration"
+                            :modifyResource="modifyResourceForSelectedIntegration"
+                            :modifyIntegration="modifySelectedIntegration"
+                            :deleteIntegration="deleteIntegrationById"
+                            :fetchResources="fetchResourcesForSelectedIntegration"
+                        />
+                    </div>
                 </div>
             </div>
         </div>
@@ -95,6 +98,7 @@
                     <IntegrationPanel
                         v-model="integrations.integrations"
                         :read-only="readOnly"
+                        @upload="handleSkillUpload"
                     ></IntegrationPanel>
                 </SideMenuPanel>
                 <SideMenuPanel
@@ -183,14 +187,13 @@ import Select from 'primevue/select';
 import SplitButton from "primevue/splitbutton";
 import ProgressSpinner from 'primevue/progressspinner';
 
-import AdhocIntegrationEditor from '../components/integrations/AdhocIntegrationEditor.vue';
 import SkillIntegrationViewer from '../components/integrations/SkillIntegrationViewer.vue';
+import SkillIntegrationEditor from '../components/integrations/SkillIntegrationEditor.vue';
+import SkillResourcePanel from '../components/integrations/SkillResourcePanel.vue';
 import MCPIntegrationViewer from '../components/integrations/MCPIntegrationViewer.vue';
 import MCPIntegrationEditor from '../components/integrations/MCPIntegrationEditor.vue';
 import MCPToolsPanel from '../components/integrations/MCPToolsPanel.vue';
 import IntegrationPanel from '../components/integrations/IntegrationPanel.vue';
-import ExamplesPanel from '../components/integrations/ExamplesPanel.vue';
-import ResourceViewer from '../components/integrations/ResourceViewer.vue';
 import {
     listResources,
     listIntegrations,
@@ -204,8 +207,11 @@ import {
     updateIntegration,
     addIntegration,
     getIntegration,
+    deleteIntegration,
     deleteResource,
+    previewSkillFromContent,
 } from '@/util/integration';
+import { parseSkillUpload } from '@/util/skillArchive';
 import { useRoute } from 'vue-router';
 
 const beakerNotebookRef = ref<BeakerNotebookComponentType>();
@@ -246,6 +252,7 @@ const saveAsFilename = ref<string>(null);
 const isMaximized = ref(false);
 const { theme, toggleDarkMode } = inject<IBeakerTheme>('theme');
 const beakerApp = inject<any>("beakerAppConfig");
+const showToast = inject<any>('show_toast');
 
 beakerApp.setPage("integrations");
 
@@ -276,19 +283,12 @@ const beakerSession = computed<BeakerSessionComponentType>(() => {
 
 const integrationMapping: {[integrationType: string]: any} = {
     'agent-skill': {
-        readOnly: true,
-        centerComponent: SkillIntegrationViewer,
-        rightPanelComponent: ResourceViewer,
+        readOnly: false,
+        centerComponent: SkillIntegrationEditor,
+        rightPanelComponent: SkillResourcePanel,
         rightPanelLabel: 'Resources',
         rightPanelIcon: 'pi pi-folder-open',
     },
-    adhoc: {
-        readOnly: false,
-        centerComponent: AdhocIntegrationEditor,
-        rightPanelComponent: ExamplesPanel,
-        rightPanelLabel: 'Example Editor',
-        rightPanelIcon: 'pi pi-list-check',
-    },
     mcp: {
         readOnly: false,
         centerComponent: MCPIntegrationViewer,
@@ -325,13 +325,19 @@ const selectedIntegrationType = computed<string | undefined>(() => {
 // --- Dynamic component switching ---
 
 const centerComponent = computed<Component>(() => {
-    // MCP servers get a read-only viewer when provided by a context, and the
-    // full editor otherwise; all other types use their fixed mapping entry.
+    // MCP servers and skills get a read-only viewer when provided by a context
+    // (context-bundled integrations are not editable) and the full editor
+    // otherwise; all other types use their fixed mapping entry.
     if (selectedIntegrationType.value === 'mcp') {
         return isContextProvidedIntegration(selectedIntegration.value)
             ? MCPIntegrationViewer
             : MCPIntegrationEditor;
     }
+    if (selectedIntegrationType.value === 'agent-skill') {
+        return isContextProvidedIntegration(selectedIntegration.value)
+            ? SkillIntegrationViewer
+            : SkillIntegrationEditor;
+    }
     return integrationMapping[selectedIntegrationType.value]?.centerComponent || integrationMapping.default?.centerComponent;
 });
 
@@ -373,7 +379,7 @@ const providerForType = (providerType: string, fallback: string): string =>
     Object.values(integrations.value?.integrations ?? {})
         .find(i => getIntegrationProviderType(i) === providerType)?.provider ?? fallback;
 
-const newIntegration = (providerType: string = 'adhoc') => {
+const newIntegration = (providerType: string = 'skill') => {
     let integration: Integration;
     if (providerType === 'mcp') {
         integration = {
@@ -397,27 +403,76 @@ const newIntegration = (providerType: string = 'adhoc') => {
         } as Integration;
     } else {
         integration = {
-            name: "New Integration",
-            source: "This is the prompt information that the agent will consult when using the integration. Include API details or how to find datasets here.",
-            description: "This is the description that the agent will use to determine when this integration should be used.",
-            provider: providerForType('adhoc', "adhoc:specialist_agents"),
-            slug: "new_integration",
+            name: "New Skill",
+            source: "",
+            description: "A short description the agent uses to decide when this skill is relevant.",
+            provider: providerForType('agent-skill', "agent-skill:agent-skill"),
+            datatype: "skill",
+            slug: "new_skill",
             uuid: "new",
-            url: ""
-        };
+            url: "",
+            source_type: "local",
+            resources: {},
+        } as Integration;
     }
     integrations.value.integrations["new"] = integration;
     integrations.value.selected = "new";
     integrations.value.unsavedChanges = true;
 };
 
+// Import a skill from an uploaded SKILL.md or .zip: parse it in the browser,
+// prefill a new (unsaved) skill from the SKILL.md via the backend parser, and
+// stash the enumerated resource files so Save can upload them.
+const handleSkillUpload = async (file: File) => {
+    if (!confirmUnsavedChanges()) {
+        return;
+    }
+    const provider = providerForType('agent-skill', 'agent-skill:agent-skill');
+    try {
+        const parsed = await parseSkillUpload(file);
+        const preview = await previewSkillFromContent(sessionId, {
+            provider,
+            content: parsed.skillMd,
+        });
+        integrations.value.integrations["new"] = {
+            ...preview,
+            uuid: "new",
+            provider,
+            datatype: "skill",
+            source_type: "local",
+            url: "",
+            pendingResources: parsed.resources,
+            pendingSkipped: parsed.skipped,
+        } as Integration;
+        integrations.value.selected = "new";
+        integrations.value.unsavedChanges = true;
+
+        const skippedNote = parsed.skipped.length
+            ? ` ${parsed.skipped.length} non-text file(s) skipped.`
+            : '';
+        showToast?.({
+            title: 'Skill loaded',
+            detail: `Loaded "${preview.name}" with ${parsed.resources.length} resource(s).${skippedNote} Review and Save to import.`,
+            severity: 'success',
+            life: 5000,
+        });
+    } catch (e) {
+        showToast?.({
+            title: 'Upload failed',
+            detail: (e as Error)?.message ?? 'Could not read the uploaded skill.',
+            severity: 'error',
+            life: 6000,
+        });
+    }
+};
+
 // Menu items for the "New Integration" split button; each guards unsaved
 // changes before starting a fresh integration of the chosen type.
 const newIntegrationItems = computed(() => [
     {
-        label: "Specialist Agent",
-        icon: "pi pi-user",
-        command: () => { if (confirmUnsavedChanges()) { newIntegration('adhoc'); } },
+        label: "Skill",
+        icon: "pi pi-book",
+        command: () => { if (confirmUnsavedChanges()) { newIntegration('skill'); } },
     },
     {
         label: "MCP Server",
@@ -440,7 +495,7 @@ const delayUntil = (condition, retryInterval) => {
 const route = useRoute();
 watch(() => route, (newRoute) => {
     if (newRoute.query?.selected === "new") {
-        const providerType = (newRoute.query?.type as string | undefined) ?? 'adhoc';
+        const providerType = (newRoute.query?.type as string | undefined) ?? 'skill';
         if (integrations.value.finishedInitialLoad) {
             newIntegration(providerType);
         } else {
@@ -531,6 +586,15 @@ const deleteResourceOnSelectedIntegration = async (resourceId: string) => {
     await deleteResource(sessionId, integrations.value.selected, resourceId);
 }
 
+const deleteIntegrationById = async (integrationId: string) => {
+    await deleteIntegration(sessionId, integrationId);
+    delete integrations.value.integrations[integrationId];
+    if (integrations.value.selected === integrationId) {
+        integrations.value.selected = undefined;
+    }
+    integrations.value.unsavedChanges = false;
+}
+
 watch(beakerSession, async () => fetchIntegrations());
 
 // --- Header nav ---
@@ -652,14 +716,24 @@ const restartSession = async () => {
     max-width: 100%;
 }
 
-.beaker-notebook {
+.integration-main {
+    // Self-contained: previously relied on the notebook's global `.beaker-notebook`
+    // rule leaking in these three properties, which is exactly the kind of
+    // cross-page overlap that breaks once this page is nested in a router-view.
+    display: flex;
+    flex-direction: column;
+    height: 100%;
+
     flex: 2 0 calc(50vw - 2px);
     border: 2px solid var(--p-surface-border);
     border-radius: 0;
     border-top: 0;
     max-width: 100%;
     padding-top: 1rem;
-    overflow: auto;
+    // The header and each center component's action bar stay pinned; only the
+    // content between them scrolls (see .integration-center and the per-editor
+    // *-content rules). So this outer box must not scroll as a whole.
+    overflow: hidden;
 
     .p-fieldset {
         input {
@@ -711,9 +785,25 @@ const restartSession = async () => {
     display: flex;
     flex-direction: column;
     height: 100%;
+    min-height: 0;
     padding: 0 0.4rem;
 }
 
+// Fills the space between the pinned header and the box edge, and gives the
+// center component a bounded height so it can scroll its own content while
+// keeping its action bar pinned.
+.integration-center {
+    flex: 1 1 auto;
+    min-height: 0;
+    display: flex;
+    flex-direction: column;
+
+    > * {
+        flex: 1 1 auto;
+        min-height: 0;
+    }
+}
+
 .integration-content-header {
     display: flex;
     flex-direction: row;
diff --git a/beaker-vue/src/util/integration.ts b/beaker-vue/src/util/integration.ts
index 5c420669..f95e32f7 100644
--- a/beaker-vue/src/util/integration.ts
+++ b/beaker-vue/src/util/integration.ts
@@ -113,6 +113,21 @@ export interface MCPServerConfig {
     metadata?: Record<string, any>
 }
 
+export interface SkillIntegration extends Integration {
+    datatype: "skill";
+    // "local" skills are fully editable; "remote" skills are defined by a URL
+    // and their fetched content is read-only.
+    source_type: "local" | "remote";
+    base_path?: string
+    base_url?: string
+    extra_instructions?: string
+    // Client-only, transient: resources enumerated from an uploaded SKILL.md/zip
+    // that will be created (via resource CRUD) once the new skill is saved.
+    pendingResources?: object[]
+    // Client-only: paths skipped during upload (e.g. binary assets).
+    pendingSkipped?: string[]
+}
+
 export interface MCPIntegration extends Integration {
     datatype: "mcp";
     server_config?: MCPServerConfig
@@ -238,10 +253,28 @@ export const updateIntegration = async (sessionId: string, integrationId: string
     return await integrationApiWrapper<Integration>("POST", {sessionId, integrationId}, body);
 }
 
+// Fetch and parse a remote skill (SKILL.md at `url`) without persisting it, so
+// the editor can populate its form before the user commits. Uses the same add
+// route; the `preview` flag tells the provider to build-and-return only.
+export const previewRemoteSkill = async (sessionId: string, body: { provider: string, url: string }): Promise<SkillIntegration> => {
+    return await integrationApiWrapper<SkillIntegration>("POST", {sessionId}, { ...body, source_type: "remote", preview: true });
+}
+
+// Parse raw SKILL.md text (from an uploaded file/archive) into a built,
+// unsaved skill so the editor can prefill its form. Same route/flag as the
+// remote preview, but the SKILL.md is supplied directly rather than fetched.
+export const previewSkillFromContent = async (sessionId: string, body: { provider: string, content: string }): Promise<SkillIntegration> => {
+    return await integrationApiWrapper<SkillIntegration>("POST", {sessionId}, { ...body, source_type: "local", preview: true });
+}
+
 export const getIntegration = async (sessionId: string, integrationId: string): Promise<Integration> => {
     return await integrationApiWrapper<Integration>("GET", {sessionId, integrationId});
 }
 
+export const deleteIntegration = async (sessionId: string, integrationId: string): Promise<{}> => {
+    return await integrationApiWrapper<{}>("DELETE", {sessionId, integrationId});
+}
+
 export const getResource = async (sessionId: string, integrationId: string, resourceType: string, resourceId: string): Promise<IntegrationResource> => {
     return await integrationApiWrapper<IntegrationResource>("GET", {sessionId, integrationId, resourceType, resourceId});
 }
diff --git a/beaker-vue/src/util/skillArchive.ts b/beaker-vue/src/util/skillArchive.ts
new file mode 100644
index 00000000..ed522c4e
--- /dev/null
+++ b/beaker-vue/src/util/skillArchive.ts
@@ -0,0 +1,150 @@
+import { unzipSync, strFromU8 } from 'fflate';
+
+// Client-side parsing of an uploaded skill (a bare SKILL.md or a .zip). The zip
+// is unpacked in the browser (no temp files); we locate SKILL.md, enumerate the
+// valid resource files, and return everything as text so the caller can preview
+// (via the backend SKILL.md parser) and upload on save through the normal
+// add-integration + resource CRUD paths. The real security boundary stays
+// server-side: every resource write is re-validated there. These caps only
+// protect the user's own tab from a pathological archive.
+const MAX_FILE_BYTES = 50 * 1024 * 1024;
+const MAX_ENTRIES = 2000;
+const MAX_TOTAL_BYTES = 100 * 1024 * 1024;
+
+// Subtrees whose files become skill resources (mirrors the backend
+// SKILL_RESOURCE_DIRS). Both "references" and the singular "reference" are
+// recognized because real skills use the singular form. Anything outside these
+// (and SKILL.md / examples) is ignored.
+const RESOURCE_DIRS = ['references', 'reference', 'scripts', 'assets'];
+
+export interface EnumeratedResource {
+    resource_type: 'skill_file' | 'skill_example';
+    // skill_file
+    relative_path?: string;
+    name?: string;
+    // skill_example
+    filename?: string;
+    content: string;
+}
+
+export interface ParsedSkillUpload {
+    skillMd: string;
+    resources: EnumeratedResource[];
+    // Paths that were skipped because they were not valid UTF-8 text (binary
+    // assets are not yet supported); surfaced to the user, not silently dropped.
+    skipped: string[];
+}
+
+const isZipFile = (file: File): boolean =>
+    file.name.toLowerCase().endsWith('.zip')
+    || file.type === 'application/zip'
+    || file.type === 'application/x-zip-compressed';
+
+// Heuristic text check: reject on NUL bytes, otherwise require a strict UTF-8
+// decode. Keeps binary assets out of the text-only resource pipeline.
+const isProbablyText = (bytes: Uint8Array): boolean => {
+    const sample = bytes.subarray(0, 8192);
+    if (sample.includes(0)) {
+        return false;
+    }
+    try {
+        new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+        return true;
+    } catch {
+        return false;
+    }
+};
+
+export async function parseSkillUpload(file: File): Promise<ParsedSkillUpload> {
+    if (file.size > MAX_FILE_BYTES) {
+        throw new Error(`File is too large (${Math.round(file.size / 1024 / 1024)} MB); the limit is ${MAX_FILE_BYTES / 1024 / 1024} MB.`);
+    }
+    const buffer = new Uint8Array(await file.arrayBuffer());
+
+    if (!isZipFile(file)) {
+        // A bare SKILL.md (any single text file is treated as the SKILL.md body).
+        return { skillMd: new TextDecoder('utf-8').decode(buffer), resources: [], skipped: [] };
+    }
+
+    let entries: Record<string, Uint8Array>;
+    try {
+        entries = unzipSync(buffer);
+    } catch (e) {
+        throw new Error(`Could not read the ZIP archive: ${(e as Error)?.message ?? 'unknown error'}`);
+    }
+
+    const paths = Object.keys(entries).filter((p) => !p.endsWith('/'));
+    if (paths.length > MAX_ENTRIES) {
+        throw new Error(`Archive has ${paths.length} files; the limit is ${MAX_ENTRIES}.`);
+    }
+    let total = 0;
+    for (const p of paths) {
+        total += entries[p].length;
+        if (total > MAX_TOTAL_BYTES) {
+            throw new Error('Archive contents are too large to import in the browser.');
+        }
+    }
+
+    // Locate SKILL.md at the archive root or exactly one directory deep.
+    const skillMdPaths = paths.filter((p) => {
+        const parts = p.split('/');
+        return (parts.length === 1 && parts[0] === 'SKILL.md')
+            || (parts.length === 2 && parts[1] === 'SKILL.md');
+    });
+    if (skillMdPaths.length === 0) {
+        throw new Error('No SKILL.md found at the archive root or one directory deep.');
+    }
+    if (skillMdPaths.length > 1) {
+        throw new Error('The archive contains more than one SKILL.md; it must contain exactly one.');
+    }
+
+    const skillMdPath = skillMdPaths[0];
+    const rootPrefix = skillMdPath.includes('/')
+        ? skillMdPath.slice(0, skillMdPath.lastIndexOf('/') + 1)
+        : '';
+    const skillMd = new TextDecoder('utf-8').decode(entries[skillMdPath]);
+
+    const resources: EnumeratedResource[] = [];
+    const skipped: string[] = [];
+
+    for (const p of paths) {
+        if (p === skillMdPath) {
+            continue;
+        }
+        // Ignore anything outside the located skill directory.
+        if (rootPrefix && !p.startsWith(rootPrefix)) {
+            continue;
+        }
+        const rel = rootPrefix ? p.slice(rootPrefix.length) : p;
+        const parts = rel.split('/');
+        const top = parts[0];
+
+        if (top === 'examples') {
+            // Examples are flat (examples/<file>); ignore nested paths.
+            if (parts.length !== 2) {
+                continue;
+            }
+            const bytes = entries[p];
+            if (!isProbablyText(bytes)) {
+                skipped.push(rel);
+                continue;
+            }
+            resources.push({ resource_type: 'skill_example', filename: parts[1], content: strFromU8(bytes) });
+        } else if (RESOURCE_DIRS.includes(top)) {
+            const bytes = entries[p];
+            if (!isProbablyText(bytes)) {
+                skipped.push(rel);
+                continue;
+            }
+            resources.push({
+                resource_type: 'skill_file',
+                relative_path: rel,
+                name: parts[parts.length - 1],
+                content: strFromU8(bytes),
+            });
+        }
+        // Everything else (stray top-level files, other directories) is ignored.
+    }
+
+    return { skillMd, resources, skipped };
+}
diff --git a/src/beaker_notebook/app/api/integrations.py b/src/beaker_notebook/app/api/integrations.py
index 0f8c1f29..5d1d4cc5 100644
--- a/src/beaker_notebook/app/api/integrations.py
+++ b/src/beaker_notebook/app/api/integrations.py
@@ -242,6 +242,22 @@ async def post(self, session_id=None, integration_id=None):
         except Exception as e:
             raise tornado.web.HTTPError(status_code=500, log_message=str(e))
 
+    async def delete(self, session_id=None, integration_id=None):
+        if integration_id is None:
+            raise tornado.web.HTTPError(status_code=400, log_message="An integration id is required to delete an integration.")
+        try:
+            await self.call_in_context(
+                session_id=session_id,
+                target=f"integration:{integration_id}",
+                function="remove_integration",
+                kwargs={"integration_id": integration_id},
+            )
+            self.write({})
+        except TimeoutError as e:
+            raise tornado.web.HTTPError(status_code=504, log_message="Kernel took too long to repond to request")
+        except Exception as e:
+            raise tornado.web.HTTPError(status_code=500, log_message=str(e))
+
 
 class IntegrationResourceHandler(BeakerAPIMixin, JupyterHandler):
     """
diff --git a/src/beaker_notebook/kernel.py b/src/beaker_notebook/kernel.py
index e84ffd51..0407043d 100644
--- a/src/beaker_notebook/kernel.py
+++ b/src/beaker_notebook/kernel.py
@@ -676,6 +676,9 @@ async def llm_request(self, message: JupyterMessage):
                         self.handle_tool_call_update, parent_header=message.header
                     )
                 self.debug("llm_query", request, parent_header=message.header)
+                # Rebuild the system_preamble if a mid-session mutation (e.g. an
+                # edited skill) marked it dirty, so this turn sees current state.
+                await self.context.ensure_system_preamble_fresh()
                 task = asyncio.create_task(self.context.agent.react_async(request, react_context={"message": message}))
                 self.running_actions[request_key] = task
                 result = await task
diff --git a/src/beaker_notebook/lib/context.py b/src/beaker_notebook/lib/context.py
index 4462c3f5..e265ed7b 100644
--- a/src/beaker_notebook/lib/context.py
+++ b/src/beaker_notebook/lib/context.py
@@ -131,6 +131,13 @@ def __init__(
         self.current_llm_query = None
         self.session_attachments: list[dict[str, Any]] = []
         self._notebook_state = None
+        # Lazy invalidation flag for the cacheable system_preamble layer. Set by
+        # `mark_system_preamble_dirty()` when a mutation is known to change a
+        # contributor's output (e.g. an integration is edited mid-session), and
+        # cleared by a rebuild. Deferring the rebuild to next use (see
+        # `ensure_system_preamble_fresh()`) coalesces multiple mutations into a
+        # single reassembly rather than doing discarded work between each.
+        self._system_preamble_dirty = False
 
         self.disable_tools()
 
@@ -391,6 +398,25 @@ async def refresh_system_preamble(self) -> None:
         setter = getattr(chat_history, "set_system_preamble_text", None) if chat_history else None
         if setter is not None:
             setter(text or "")
+        self._system_preamble_dirty = False
+
+    def mark_system_preamble_dirty(self) -> None:
+        """Flag the system_preamble for rebuild on next use.
+
+        Cheaper than rebuilding eagerly: several mutations in a row (e.g. saving
+        a skill's body plus a handful of its resource files) collapse into one
+        reassembly the next time a turn actually needs the preamble.
+        """
+        self._system_preamble_dirty = True
+
+    async def ensure_system_preamble_fresh(self) -> None:
+        """Rebuild the system_preamble if a mutation marked it dirty.
+
+        Called at the start of a turn (before the ReAct loop) so an edit made
+        between turns is reflected without an eager rebuild at mutation time.
+        """
+        if self._system_preamble_dirty:
+            await self.refresh_system_preamble()
 
     def disable_tools(self):
         # TODO: Identical toolnames don't work
@@ -662,6 +688,18 @@ async def list_integrations(self):
             )
         }
 
+    # Provider/integration functions whose effect changes what the integration
+    # layer contributes to the system_preamble; calling any of them via
+    # `call_in_context` marks the preamble dirty for a lazy rebuild next turn.
+    _PREAMBLE_MUTATING_FUNCTIONS = frozenset({
+        "add_integration",
+        "update_integration",
+        "remove_integration",
+        "add_resource",
+        "update_resource",
+        "remove_resource",
+    })
+
     @action(scope="internal")
     async def call_in_context(self, message):
         content = message.content
@@ -717,6 +755,10 @@ async def call_in_context(self, message):
                 result = await self._call_in_context(ensure_async(function(*args, **kwargs)))
             case _:
                 raise NotImplementedError
+        # Integration/provider mutations change what the integration layer
+        # contributes to the system_preamble; flag it for a lazy rebuild.
+        if target_type in ("provider", "integration") and content.get("function") in self._PREAMBLE_MUTATING_FUNCTIONS:
+            self.mark_system_preamble_dirty()
         return result
 
     async def _call_in_context(self, coro):
diff --git a/src/beaker_notebook/lib/integrations/skill.py b/src/beaker_notebook/lib/integrations/skill.py
index 254a71be..835efcb3 100644
--- a/src/beaker_notebook/lib/integrations/skill.py
+++ b/src/beaker_notebook/lib/integrations/skill.py
@@ -3,6 +3,7 @@
 import logging
 import os
 import re
+import shutil
 from pathlib import Path
 from typing import TYPE_CHECKING, Any, ClassVar, Optional, Mapping, cast
 from typing_extensions import Self
@@ -22,7 +23,13 @@
     SkillIntegration,
     SkillMetadataResource,
 )
-from .base import BaseIntegrationProvider
+from .base import MutableBaseIntegrationProvider
+
+# Subdirectories under a local skill directory that hold progressively-disclosed
+# resource files (mirrors the Agent Skills layout). Order is the display order.
+# Both "references" and the singular "reference" are recognized because real
+# skills (e.g. Anthropic's own) use the singular form.
+SKILL_RESOURCE_DIRS = ("references", "reference", "scripts", "assets")
 if TYPE_CHECKING:
     from beaker_notebook.lib.agent import BeakerAgent
     from beaker_notebook.lib.context import BeakerContext
@@ -153,6 +160,11 @@ def extract_file_references(body: str) -> list[str]:
     link_pattern = re.compile(r'\[(?:[^\]]*)\]\(([^)]+)\)')
     for match in link_pattern.finditer(body):
         path = match.group(1)
+        # Normalize a leading "./" so a body reference like ./reference/x.md
+        # matches the on-disk / enumerated path (reference/x.md) and dedupes
+        # rather than appearing as a separate, phantom resource.
+        if path.startswith("./"):
+            path = path[2:]
         if not path.startswith(("http://", "https://", "#", "mailto:")):
             # Skip examples/ paths — they are handled as SkillExampleResources
             if not path.startswith("examples/") and path != "examples/":
@@ -160,7 +172,7 @@ def extract_file_references(body: str) -> list[str]:
 
     # Backtick-quoted file paths: `some/path.ext`
     # Match paths that contain a / and end with a file extension
-    backtick_pattern = re.compile(r'`((?:references|scripts|assets)/[^`]+)`')
+    backtick_pattern = re.compile(r'`((?:references|reference|scripts|assets)/[^`]+)`')
     for match in backtick_pattern.finditer(body):
         references.append(match.group(1))
 
@@ -198,22 +210,29 @@ def parse_example_md(content: str) -> tuple[str, str]:
     return title, description
 
 
-class SkillIntegrationProvider(BaseIntegrationProvider):
+class SkillIntegrationProvider(MutableBaseIntegrationProvider):
     """Provides Agent Skills as Beaker integrations with progressive disclosure.
 
     Skills are discovered from a skills.json config file containing a list of
     local paths and/or remote URLs pointing to SKILL.md files.
+
+    Local skills are editable: their ``SKILL.md`` (name/description/frontmatter
+    metadata + instructions body) is written through ``update_integration`` and
+    their resource files (under ``references/``/``scripts/``/``assets/`` and
+    ``examples/``) through the resource-mutation methods. Remote skills are
+    defined by a URL only; their fetched content is read-only.
     """
 
     provider_type: ClassVar[str] = "agent-skill"
     display_name: ClassVar[str] = "Agent Skills"
     slug: ClassVar[str] = "agent-skill"
-    mutable: ClassVar[bool] = False
 
     def __init__(self, id: Optional[str] = None, skill_paths: Optional[list[str|os.PathLike]] = None):
         super().__init__(id=id)
         logger.debug(f"Initializing SkillIntegrationProvider {self.display_name} ({self.id})")
-        self._skills: list[SkillIntegration] = list(self.discover_integrations(paths=skill_paths).values())
+        self._skills: list[SkillIntegration] = list(
+            self.discover_integrations(paths=skill_paths, corpus=self.id).values()
+        )
         self._loaded: dict[str, set[tuple[str, str]]] = {}
 
     @classmethod
@@ -266,7 +285,10 @@ def from_context(cls, context: "BeakerContext") -> list[Self]:
         context_dir_path = Path(inspect.getabsfile(context.__class__)).parent
         integration_paths = cls.discover_integration_paths(root_paths=[context_dir_path])
         if integration_paths:
-            return [cls(skill_paths=integration_paths)]
+            # Namespace context-bundled skills under a `context-<slug>` id so the
+            # front-end (isContextProvidedIntegration) renders them read-only,
+            # mirroring MCPIntegrationProvider.from_context.
+            return [cls(id=f"context-{context.slug}", skill_paths=integration_paths)]
         else:
             return []
 
@@ -305,20 +327,21 @@ def discover_integration_paths(
         return config_files
 
     @classmethod
-    def discover_integrations(cls, *, paths: Optional[list[str|os.PathLike]] = None, **kwargs) -> Mapping[str, SkillIntegration]:
+    def discover_integrations(cls, *, paths: Optional[list[str|os.PathLike]] = None, corpus: Optional[str] = None, **kwargs) -> Mapping[str, SkillIntegration]:
         """Discover and load skills from ``skills.json`` files and ``skills/``
         directories under each search root.
 
         Each root is checked for both a ``skills.json`` manifest and a
         ``skills/`` subdirectory; roots earlier in the list take precedence
-        on slug conflicts.
+        on slug conflicts. ``corpus`` namespaces the built integrations (and
+        their deterministic uuids); it is the owning provider's id.
         """
         skills: dict[str, SkillIntegration] = {}
         loaded_slugs: set[str] = set()
 
-        def _load_deduped(source: str, base_path: Optional[str]=None):
+        def _load_deduped(source: str, base_path: Optional[str]=None, manifest_path: Optional[str]=None):
             try:
-                skill = cls._load_skill(source, base_path=base_path)
+                skill = cls._load_skill(source, base_path=base_path, corpus=corpus, manifest_path=manifest_path)
                 if skill.slug in loaded_slugs:
                     logger.debug("Skipping duplicate skill '%s' from %s", skill.name, source)
                 else:
@@ -342,7 +365,7 @@ def _load_deduped(source: str, base_path: Optional[str]=None):
                     logger.warning("skills.json must be a JSON list, got %s", type(data).__name__)
                     continue
                 for source in data:
-                    _load_deduped(source, base_path=str(config_path.parent))
+                    _load_deduped(source, base_path=str(config_path.parent), manifest_path=str(config_path))
             elif config_path.is_dir():
                 logger.debug("Scanning skills directory: %s", config_path)
                 for skill_md in config_path.glob("*/SKILL.md"):
@@ -359,18 +382,18 @@ def _merge(cls, a: Self, b: Self) -> Self:
         return a
 
     @classmethod
-    def _load_skill(cls, source: str, base_path: Optional[str]=None) -> SkillIntegration:
+    def _load_skill(cls, source: str, base_path: Optional[str]=None, corpus: Optional[str]=None, manifest_path: Optional[str]=None) -> SkillIntegration:
         """Load a single skill from a local path or remote URL."""
         if source.startswith(("http://", "https://")):
-            return cls._load_remote_skill(source)
+            return cls._load_remote_skill(source, corpus=corpus, manifest_path=manifest_path)
         else:
             # If the source reference is relative, convert it to an absolute path relative to the folder the json file is in.
             if not Path(source).is_absolute() and base_path is not None:
                 source = str((Path(base_path) / source).absolute())
-            return cls._load_local_skill(source)
+            return cls._load_local_skill(source, corpus=corpus)
 
     @classmethod
-    def _load_local_skill(cls, path: str) -> SkillIntegration:
+    def _load_local_skill(cls, path: str, corpus: Optional[str]=None) -> SkillIntegration:
         """Load a skill from a local directory or SKILL.md path."""
         skill_path = Path(path)
         if skill_path.is_file() and skill_path.name == "SKILL.md":
@@ -396,10 +419,11 @@ def _load_local_skill(cls, path: str) -> SkillIntegration:
             body=body,
             source_type="local",
             base_path=str(skill_dir),
+            corpus=corpus,
         )
 
     @classmethod
-    def _load_remote_skill(cls, url: str) -> SkillIntegration:
+    def _load_remote_skill(cls, url: str, corpus: Optional[str]=None, manifest_path: Optional[str]=None) -> SkillIntegration:
         """Load a skill from a remote URL."""
         if url.rstrip("/").endswith("SKILL.md"):
             skill_url = url
@@ -418,6 +442,11 @@ def _load_remote_skill(cls, url: str) -> SkillIntegration:
             body=body,
             source_type="remote",
             base_url=base_url,
+            corpus=corpus,
+            # Retain where this remote skill was declared, and under what source
+            # string, so update_integration can rewrite the manifest entry.
+            source_url=url,
+            manifest_path=manifest_path,
         )
 
     @classmethod
@@ -429,20 +458,35 @@ def _build_skill_integration(
         slug: Optional[str] = None,
         base_path: Optional[str] = None,
         base_url: Optional[str] = None,
+        corpus: Optional[str] = None,
+        source_url: Optional[str] = None,
+        manifest_path: Optional[str] = None,
     ) -> SkillIntegration:
         """Build a SkillIntegration with resources from parsed SKILL.md."""
         name = frontmatter["name"]
         description = frontmatter["description"]
 
+        if slug is None:
+            slug = Integration.slugify(name)
+
         skill = SkillIntegration(
+            uuid=cls._skill_uuid(slug, corpus),
             name=name,
-            slug=cast(str, slug),
+            slug=slug,
             description=description,
             provider=f"{cls.provider_type}:{cls.slug}",
             source_type=source_type,
             base_path=base_path,
             base_url=base_url,
+            corpus=corpus,
         )
+        if source_url:
+            # Surface the source URL as the integration's url so the editor can
+            # display it; also retained in extra_metadata for manifest rewrites.
+            skill.url = source_url
+            skill.extra_metadata["source_url"] = source_url
+        if manifest_path:
+            skill.extra_metadata["manifest_path"] = manifest_path
 
         metadata_resource = SkillMetadataResource(
             integration=skill.uuid,
@@ -460,19 +504,75 @@ def _build_skill_integration(
             content=body,
         )
 
-        file_resources = []
-        for ref_path in extract_file_references(body):
-            file_resources.append(SkillFileResource(
-                integration=skill.uuid,
-                name=Path(ref_path).name,
-                relative_path=ref_path,
-            ))
-
+        file_resources = cls._discover_file_resources(skill, body, source_type, base_path)
         example_resources = cls._discover_examples(skill, source_type, base_path, base_url)
 
         skill.add_resources([metadata_resource, instructions_resource] + file_resources + example_resources)
         return skill
 
+    @classmethod
+    def _skill_uuid(cls, slug: str, corpus: Optional[str]) -> str:
+        """Deterministic uuid for a skill: ``agent-skill:<corpus>:<slug>``.
+
+        Stable across reloads within a provider's lifetime (``corpus`` is the
+        provider id), so an edit -> save -> re-fetch round-trip keeps the same
+        identity, mirroring the MCP provider's scheme.
+        """
+        return f"{cls.slug}:{corpus}:{slug}"
+
+    # Resource ids are left as auto-generated uuid4s (see Resource.__post_init__)
+    # rather than derived from the skill uuid / path: the resource routes carry
+    # the id as a URL path segment (regex `[\w\d-]+`), so it must not contain
+    # ':', '.', or '/'. The front-end always uses the ids from the freshly
+    # fetched integration, so stability across reloads is not required.
+
+    @classmethod
+    def _discover_file_resources(
+        cls,
+        skill: SkillIntegration,
+        body: str,
+        source_type: str,
+        base_path: Optional[str] = None,
+    ) -> list[SkillFileResource]:
+        """Build the skill's ``skill_file`` resources.
+
+        For a local skill the on-disk contents of the resource dirs
+        (``references``/``reference``/``scripts``/``assets``) are the sole source
+        of truth. Body references are deliberately NOT used for local skills:
+        they would create phantom or duplicate resources — a referenced-but-
+        absent path, a different spelling (``./x`` vs ``x``), or a copy of a file
+        that is also uploaded separately. For a remote skill (which cannot be
+        scanned) the body references are the only signal available.
+        """
+        seen: dict[str, SkillFileResource] = {}
+
+        def _add(relative_path: str):
+            if relative_path in seen:
+                return
+            seen[relative_path] = SkillFileResource(
+                integration=skill.uuid,
+                name=Path(relative_path).name,
+                relative_path=relative_path,
+            )
+
+        if source_type == "local":
+            if base_path:
+                root = Path(base_path)
+                for subdir in SKILL_RESOURCE_DIRS:
+                    dir_path = root / subdir
+                    if not dir_path.is_dir():
+                        continue
+                    for file_path in sorted(dir_path.rglob("*")):
+                        if file_path.is_file():
+                            _add(str(file_path.relative_to(root)))
+            # A local skill with no base_path (e.g. an upload preview) has no
+            # files to enumerate yet; the client provides them on save.
+        else:
+            for ref_path in extract_file_references(body):
+                _add(ref_path)
+
+        return list(seen.values())
+
     @classmethod
     def _discover_examples(
         cls,
@@ -536,6 +636,387 @@ def get_resource(self, integration_id: str, resource_id: str) -> Resource:
             resource.content = self._fetch_file_content(skill, f"examples/{resource.filename}")
         return resource
 
+    # --- Mutation: write-location resolution -----------------------------
+
+    @classmethod
+    def _candidate_write_roots(cls) -> list[Path]:
+        """Ordered base dirs a user's skills may be written to, most preferred
+        first. Mirrors the discovery search roots but keeps locations that do
+        not yet exist so a first-run install still has somewhere to land.
+        """
+        roots: list[Path] = []
+        cwd = Path.cwd()
+        for name in (".agents", ".beaker"):
+            roots.append(cwd / name)
+        home = Path.home()
+        for name in (".agents", ".beaker"):
+            roots.append(home / name)
+        for data_dir in find_resource_dirs("data"):
+            roots.append(Path(data_dir))
+        return roots
+
+    @classmethod
+    def _resolve_writable_base(cls) -> Path:
+        """Pick a base dir for new skills/manifests.
+
+        Uses the first candidate root that already exists and is writable; if
+        none exist, the first candidate we can create. Raises if nothing is
+        writable.
+        """
+        candidates = cls._candidate_write_roots()
+        for root in candidates:
+            if root.is_dir() and os.access(root, os.W_OK):
+                return root
+        for root in candidates:
+            try:
+                root.mkdir(parents=True, exist_ok=True)
+                return root
+            except OSError:
+                continue
+        raise OSError("No writable location available to store skills.")
+
+    def _resolve_writable_manifest(self) -> Path:
+        """Resolve a ``skills.json`` to record remote-skill URLs in.
+
+        Prefers a manifest this provider already reads from and can write to, so
+        a user's remote skills stay collected together; otherwise scaffolds one
+        under the first writable base.
+        """
+        for skill in self._skills:
+            manifest_path = skill.extra_metadata.get("manifest_path")
+            if manifest_path and Path(manifest_path).is_file() and os.access(manifest_path, os.W_OK):
+                return Path(manifest_path)
+        manifest = self._resolve_writable_base() / "skills.json"
+        if not manifest.exists():
+            manifest.write_text("[]\n", encoding="utf-8")
+        return manifest
+
+    @staticmethod
+    def _read_manifest(path: Path) -> list:
+        try:
+            data = json.loads(path.read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError):
+            return []
+        return data if isinstance(data, list) else []
+
+    @classmethod
+    def _write_manifest(cls, path: Path, data: list) -> None:
+        path.write_text(json.dumps(data, indent=2) + "\n", encoding="utf-8")
+
+    @staticmethod
+    def _manifest_entry_matches(entry: Any, url: str) -> bool:
+        return entry == url or (isinstance(entry, dict) and entry.get("source") == url)
+
+    # --- Mutation: SKILL.md serialization --------------------------------
+
+    @staticmethod
+    def _frontmatter_from_payload(payload: dict, defaults: Optional[dict] = None) -> dict:
+        """Assemble ordered SKILL.md frontmatter from an editor payload.
+
+        Only ``name``/``description`` are required; optional keys are omitted
+        when empty so the written file stays clean. ``defaults`` (an existing
+        skill's values) backs fields the payload omits on update.
+        """
+        defaults = defaults or {}
+        fm: dict[str, Any] = {
+            "name": payload.get("name") or defaults.get("name"),
+            "description": payload.get("description")
+                if payload.get("description") is not None else defaults.get("description"),
+        }
+        license_val = payload.get("license", defaults.get("license"))
+        if license_val:
+            fm["license"] = license_val
+        compatibility = payload.get("compatibility", defaults.get("compatibility"))
+        if compatibility:
+            fm["compatibility"] = compatibility
+        allowed_tools = payload.get("allowed_tools", defaults.get("allowed_tools"))
+        if allowed_tools:
+            fm["allowed-tools"] = allowed_tools
+        metadata = payload.get("skill_metadata", defaults.get("skill_metadata"))
+        if metadata:
+            fm["metadata"] = metadata
+        return fm
+
+    @staticmethod
+    def _render_skill_md(frontmatter: dict, body: str) -> str:
+        clean = {k: v for k, v in frontmatter.items() if v not in (None, "", {}, [])}
+        yaml_text = yaml.safe_dump(clean, sort_keys=False, default_flow_style=False).strip()
+        return f"---\n{yaml_text}\n---\n\n{(body or '').strip()}\n"
+
+    def _existing_frontmatter_defaults(self, skill: SkillIntegration) -> dict:
+        """Current frontmatter-relevant values for a skill, from its metadata
+        resource, used to back fields an update payload does not include.
+        """
+        metadata = next(
+            (r for r in skill.resources.values() if isinstance(r, SkillMetadataResource)),
+            None,
+        )
+        return {
+            "name": skill.name,
+            "description": skill.description,
+            "license": getattr(metadata, "license", None),
+            "compatibility": getattr(metadata, "compatibility", None),
+            "allowed_tools": getattr(metadata, "allowed_tools", None),
+            "skill_metadata": getattr(metadata, "skill_metadata", None),
+        }
+
+    def _existing_body(self, skill: SkillIntegration) -> str:
+        instructions = next(
+            (r for r in skill.resources.values() if isinstance(r, SkillInstructionsResource)),
+            None,
+        )
+        return instructions.content if instructions else ""
+
+    def _replace_skill(self, uuid: str, new_skill: SkillIntegration) -> None:
+        for i, skill in enumerate(self._skills):
+            if skill.uuid == uuid:
+                self._skills[i] = new_skill
+                return
+        self._skills.append(new_skill)
+
+    # --- Mutation: integrations ------------------------------------------
+
+    def add_integration(self, **payload) -> Integration:
+        # Preview: build and return the (unsaved) skill so the editor can
+        # populate its form before the user commits. Nothing is written to disk
+        # or added to the catalog. A remote preview fetches the SKILL.md from a
+        # URL; a local/upload preview parses SKILL.md text supplied directly.
+        if payload.get("preview"):
+            return self._preview_integration(**payload)
+        if payload.get("source_type") == "remote":
+            return self._add_remote_integration(**payload)
+        return self._add_local_integration(**payload)
+
+    def _preview_integration(self, **payload) -> SkillIntegration:
+        if payload.get("source_type") == "remote":
+            url = (payload.get("url") or "").strip()
+            if not url:
+                raise ValueError("Cannot preview remote skill: a URL is required.")
+            return self._load_remote_skill(url, corpus=self.id)
+        content = payload.get("content")
+        if not content:
+            raise ValueError("Cannot preview skill: SKILL.md content is required.")
+        frontmatter, body = parse_skill_md(content)
+        # base_path is intentionally omitted: the client enumerates the uploaded
+        # skill's resource files itself and uploads them on save. This preview
+        # only supplies name/description/metadata/instructions for the form.
+        return self._build_skill_integration(
+            frontmatter=frontmatter,
+            body=body,
+            source_type="local",
+            corpus=self.id,
+        )
+
+    def _add_local_integration(self, **payload) -> SkillIntegration:
+        name = payload.get("name")
+        if not name:
+            raise ValueError("Cannot add skill: a name is required.")
+        slug = Integration.slugify(name)
+        if any(skill.slug == slug for skill in self._skills):
+            raise ValueError(f"A skill named '{name}' (slug '{slug}') already exists.")
+        skill_dir = self._resolve_writable_base() / "skills" / slug
+        if skill_dir.exists():
+            raise ValueError(f"Skill directory already exists: {skill_dir}")
+        skill_dir.mkdir(parents=True)
+        frontmatter = self._frontmatter_from_payload(payload)
+        (skill_dir / "SKILL.md").write_text(
+            self._render_skill_md(frontmatter, payload.get("instructions") or ""),
+            encoding="utf-8",
+        )
+        skill = self._load_local_skill(str(skill_dir), corpus=self.id)
+        self._skills.append(skill)
+        return skill
+
+    def _add_remote_integration(self, **payload) -> SkillIntegration:
+        url = (payload.get("url") or "").strip()
+        if not url:
+            raise ValueError("Cannot add remote skill: a URL is required.")
+        manifest = self._resolve_writable_manifest()
+        data = self._read_manifest(manifest)
+        if not any(self._manifest_entry_matches(entry, url) for entry in data):
+            data.append(url)
+            self._write_manifest(manifest, data)
+        try:
+            skill = self._load_remote_skill(url, corpus=self.id, manifest_path=str(manifest))
+        except Exception:
+            # Roll back the manifest entry so a failed fetch leaves no dangling row.
+            self._remove_manifest_url(manifest, url)
+            raise
+        if any(existing.slug == skill.slug for existing in self._skills):
+            self._remove_manifest_url(manifest, url)
+            raise ValueError(f"A skill with slug '{skill.slug}' already exists.")
+        self._skills.append(skill)
+        return skill
+
+    def update_integration(self, integration_id: str, **payload) -> Integration:
+        skill = self.get_integration(integration_id)
+        if skill.source_type == "remote":
+            return self._update_remote_integration(skill, **payload)
+        return self._update_local_integration(skill, **payload)
+
+    def _update_local_integration(self, skill: SkillIntegration, **payload) -> SkillIntegration:
+        if not skill.base_path:
+            raise ValueError(f"Skill '{skill.slug}' has no local path to write to.")
+        # The directory name (and thus slug/uuid) is fixed at creation; only the
+        # SKILL.md content changes here.
+        defaults = self._existing_frontmatter_defaults(skill)
+        frontmatter = self._frontmatter_from_payload(payload, defaults=defaults)
+        body = payload.get("instructions")
+        if body is None:
+            body = self._existing_body(skill)
+        (Path(skill.base_path) / "SKILL.md").write_text(
+            self._render_skill_md(frontmatter, body), encoding="utf-8",
+        )
+        refreshed = self._load_local_skill(skill.base_path, corpus=skill.corpus)
+        self._replace_skill(skill.uuid, refreshed)
+        return refreshed
+
+    def _update_remote_integration(self, skill: SkillIntegration, **payload) -> SkillIntegration:
+        new_url = (payload.get("url") or "").strip()
+        if not new_url:
+            raise ValueError("A URL is required for a remote skill.")
+        old_url = skill.extra_metadata.get("source_url")
+        manifest = skill.extra_metadata.get("manifest_path")
+        if not manifest:
+            raise ValueError("Cannot locate the manifest for this remote skill.")
+        manifest_path = Path(manifest)
+        if new_url != old_url:
+            data = self._read_manifest(manifest_path)
+            for i, entry in enumerate(data):
+                if entry == old_url:
+                    data[i] = new_url
+                elif isinstance(entry, dict) and entry.get("source") == old_url:
+                    entry["source"] = new_url
+            self._write_manifest(manifest_path, data)
+        refreshed = self._load_remote_skill(new_url, corpus=skill.corpus, manifest_path=manifest)
+        self._replace_skill(skill.uuid, refreshed)
+        return refreshed
+
+    def remove_integration(self, integration_id: str, **payload) -> None:
+        skill = self.get_integration(integration_id)
+        if skill.source_type == "remote":
+            manifest = skill.extra_metadata.get("manifest_path")
+            url = skill.extra_metadata.get("source_url")
+            if manifest and url:
+                self._remove_manifest_url(Path(manifest), url)
+        elif skill.base_path and Path(skill.base_path).is_dir():
+            shutil.rmtree(skill.base_path)
+        self._skills = [existing for existing in self._skills if existing.uuid != integration_id]
+
+    def _remove_manifest_url(self, manifest: Path, url: str) -> None:
+        data = self._read_manifest(manifest)
+        remaining = [entry for entry in data if not self._manifest_entry_matches(entry, url)]
+        if len(remaining) != len(data):
+            self._write_manifest(manifest, remaining)
+
+    # --- Mutation: resources (local skills only) -------------------------
+
+    @staticmethod
+    def _require_local_editable(skill: SkillIntegration) -> None:
+        if skill.source_type != "local" or not skill.base_path:
+            raise ValueError(f"Skill '{skill.slug}' is not a local skill and its resources cannot be edited.")
+
+    @staticmethod
+    def _validate_resource_path(relative_path: str) -> None:
+        path = Path(relative_path)
+        if path.is_absolute() or ".." in path.parts:
+            raise ValueError(f"Invalid resource path: {relative_path}")
+        if not path.parts or path.parts[0] not in SKILL_RESOURCE_DIRS:
+            raise ValueError(
+                f"Resource path must be under one of {SKILL_RESOURCE_DIRS}: {relative_path}"
+            )
+
+    def _write_skill_file(self, skill: SkillIntegration, relative_path: str, content: str) -> None:
+        base = Path(skill.base_path).resolve()
+        target = (base / relative_path).resolve()
+        if target != base and base not in target.parents:
+            raise ValueError(f"Refusing to write outside the skill directory: {relative_path}")
+        target.parent.mkdir(parents=True, exist_ok=True)
+        target.write_text(content, encoding="utf-8")
+
+    def _delete_skill_file(self, skill: SkillIntegration, relative_path: str) -> None:
+        target = Path(skill.base_path) / relative_path
+        if target.is_file():
+            target.unlink()
+
+    def add_resource(self, integration_id: str, **payload) -> Resource:
+        skill = self.get_integration(integration_id)
+        self._require_local_editable(skill)
+        resource_type = payload.get("resource_type")
+        content = payload.get("content") or ""
+        if resource_type == "skill_file":
+            relative_path = payload.get("relative_path")
+            if not relative_path:
+                raise ValueError("A skill_file resource requires a relative_path.")
+            self._validate_resource_path(relative_path)
+            self._write_skill_file(skill, relative_path, content)
+            resource: Resource = SkillFileResource(
+                integration=skill.uuid,
+                name=payload.get("name") or Path(relative_path).name,
+                relative_path=relative_path,
+                content=content,
+            )
+        elif resource_type == "skill_example":
+            filename = payload.get("filename")
+            if not filename:
+                raise ValueError("A skill_example resource requires a filename.")
+            self._write_skill_file(skill, f"examples/{filename}", content)
+            parsed_title, parsed_description = parse_example_md(content)
+            resource = SkillExampleResource(
+                integration=skill.uuid,
+                filename=filename,
+                title=payload.get("title") or parsed_title or Path(filename).stem,
+                description=payload.get("description") or parsed_description,
+                content=content,
+            )
+        else:
+            raise ValueError(
+                f"Cannot add a resource of type '{resource_type}' to a skill. "
+                "Editable resource types are 'skill_file' and 'skill_example'; "
+                "the instructions body and metadata are edited via the integration itself."
+            )
+        skill.resources[resource.resource_id] = resource
+        return resource
+
+    def update_resource(self, integration_id: str, resource_id: str, **payload) -> Resource:
+        skill = self.get_integration(integration_id)
+        self._require_local_editable(skill)
+        resource = skill.resources.get(resource_id)
+        if resource is None:
+            raise KeyError(f"Resource not found: {resource_id}")
+        content = payload.get("content")
+        if isinstance(resource, SkillFileResource):
+            if content is not None:
+                self._write_skill_file(skill, resource.relative_path, content)
+                resource.content = content
+        elif isinstance(resource, SkillExampleResource):
+            if content is not None:
+                self._write_skill_file(skill, f"examples/{resource.filename}", content)
+                resource.content = content
+                parsed_title, parsed_description = parse_example_md(content)
+                resource.title = payload.get("title") or parsed_title or resource.title
+                resource.description = payload.get("description") or parsed_description or resource.description
+        else:
+            raise ValueError(
+                "Only 'skill_file' and 'skill_example' resources are editable; "
+                "instructions and metadata are edited via the integration itself."
+            )
+        return resource
+
+    def remove_resource(self, integration_id: str, resource_id: str, **payload) -> None:
+        skill = self.get_integration(integration_id)
+        self._require_local_editable(skill)
+        resource = skill.resources.get(resource_id)
+        if resource is None:
+            return
+        if isinstance(resource, SkillFileResource):
+            self._delete_skill_file(skill, resource.relative_path)
+        elif isinstance(resource, SkillExampleResource):
+            self._delete_skill_file(skill, f"examples/{resource.filename}")
+        else:
+            raise ValueError("Only 'skill_file' and 'skill_example' resources can be removed.")
+        skill.resources.pop(resource_id, None)
+
     # --- Prompt (Tier 1: metadata only, as YAML) ---
 
     @property

From 759d2e54443237fb650aece58714f2f28fa877cb Mon Sep 17 00:00:00 2001
From: Matthew Printz <matt@jataware.com>
Date: Tue, 21 Jul 2026 09:48:10 -0600
Subject: [PATCH 2/7] Test coverage

---
 .../src/util/__tests__/skillArchive.spec.ts   | 117 ++++++
 .../skills/test_skill_mutation.py             | 380 ++++++++++++++++++
 .../skills/test_skill_provider.py             |  10 +
 3 files changed, 507 insertions(+)
 create mode 100644 beaker-vue/src/util/__tests__/skillArchive.spec.ts
 create mode 100644 tests/integrations/skills/test_skill_mutation.py

diff --git a/beaker-vue/src/util/__tests__/skillArchive.spec.ts b/beaker-vue/src/util/__tests__/skillArchive.spec.ts
new file mode 100644
index 00000000..84d0720c
--- /dev/null
+++ b/beaker-vue/src/util/__tests__/skillArchive.spec.ts
@@ -0,0 +1,117 @@
+import { describe, it, expect } from 'vitest';
+import { zipSync, strToU8 } from 'fflate';
+import { parseSkillUpload, type EnumeratedResource } from '../skillArchive';
+
+const SKILL_MD = '---\nname: test-skill\ndescription: A test skill.\n---\n# Test\n\nBody.';
+
+// jsdom's File does not implement arrayBuffer(); build a minimal File-like with
+// the fields parseSkillUpload uses (name/type/size/arrayBuffer). In a real
+// browser the native File provides all of these.
+function fakeFile(bytes: Uint8Array, name: string, type: string): File {
+    return {
+        name,
+        type,
+        size: bytes.byteLength,
+        arrayBuffer: async () =>
+            bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength),
+    } as unknown as File;
+}
+
+function zipFile(files: Record<string, Uint8Array>, name = 'skill.zip'): File {
+    return fakeFile(zipSync(files), name, 'application/zip');
+}
+
+function mdFile(text: string, name = 'SKILL.md'): File {
+    return fakeFile(strToU8(text), name, 'text/markdown');
+}
+
+const relPaths = (resources: EnumeratedResource[]) =>
+    resources.filter((r) => r.resource_type === 'skill_file').map((r) => r.relative_path).sort();
+const exampleNames = (resources: EnumeratedResource[]) =>
+    resources.filter((r) => r.resource_type === 'skill_example').map((r) => r.filename).sort();
+
+describe('parseSkillUpload', () => {
+    it('reads a bare SKILL.md with no resources', async () => {
+        const result = await parseSkillUpload(mdFile(SKILL_MD));
+        expect(result.skillMd).toBe(SKILL_MD);
+        expect(result.resources).toEqual([]);
+        expect(result.skipped).toEqual([]);
+    });
+
+    it('locates SKILL.md at the archive root and enumerates resources', async () => {
+        const result = await parseSkillUpload(zipFile({
+            'SKILL.md': strToU8(SKILL_MD),
+            'references/guide.md': strToU8('guide'),
+            'scripts/run.py': strToU8('print(1)'),
+            'assets/data.json': strToU8('{}'),
+            'examples/ex1.md': strToU8('# Ex1'),
+        }));
+        expect(result.skillMd).toBe(SKILL_MD);
+        expect(relPaths(result.resources)).toEqual(['assets/data.json', 'references/guide.md', 'scripts/run.py']);
+        expect(exampleNames(result.resources)).toEqual(['ex1.md']);
+    });
+
+    it('locates SKILL.md one directory deep and strips the root prefix', async () => {
+        const result = await parseSkillUpload(zipFile({
+            'my-skill/SKILL.md': strToU8(SKILL_MD),
+            'my-skill/reference/node.md': strToU8('node'),
+            'my-skill/scripts/run.py': strToU8('x'),
+        }));
+        // Singular "reference/" is recognized; paths are relative to the skill root.
+        expect(relPaths(result.resources)).toEqual(['reference/node.md', 'scripts/run.py']);
+    });
+
+    it('captures example content and file content', async () => {
+        const result = await parseSkillUpload(zipFile({
+            'SKILL.md': strToU8(SKILL_MD),
+            'references/guide.md': strToU8('guide body'),
+            'examples/ex1.md': strToU8('# Ex1\n\ndesc'),
+        }));
+        const file = result.resources.find((r) => r.resource_type === 'skill_file');
+        const example = result.resources.find((r) => r.resource_type === 'skill_example');
+        expect(file?.content).toBe('guide body');
+        expect(example?.content).toBe('# Ex1\n\ndesc');
+    });
+
+    it('rejects an archive with no SKILL.md', async () => {
+        await expect(parseSkillUpload(zipFile({ 'references/guide.md': strToU8('x') })))
+            .rejects.toThrow(/No SKILL.md/);
+    });
+
+    it('rejects an archive with more than one SKILL.md', async () => {
+        await expect(parseSkillUpload(zipFile({
+            'a/SKILL.md': strToU8(SKILL_MD),
+            'b/SKILL.md': strToU8(SKILL_MD),
+        }))).rejects.toThrow(/more than one/);
+    });
+
+    it('skips binary (non-text) files and reports them', async () => {
+        const result = await parseSkillUpload(zipFile({
+            'SKILL.md': strToU8(SKILL_MD),
+            'references/guide.md': strToU8('text'),
+            'assets/logo.png': new Uint8Array([0x89, 0x50, 0x4e, 0x47, 0x00, 0x01]), // has NUL
+        }));
+        expect(relPaths(result.resources)).toEqual(['references/guide.md']);
+        expect(result.skipped).toEqual(['assets/logo.png']);
+    });
+
+    it('ignores files outside SKILL.md and the recognized resource dirs', async () => {
+        const result = await parseSkillUpload(zipFile({
+            'my-skill/SKILL.md': strToU8(SKILL_MD),
+            'my-skill/LICENSE.txt': strToU8('license'),
+            'my-skill/docs/notes.md': strToU8('notes'),
+            'my-skill/references/guide.md': strToU8('guide'),
+        }));
+        expect(relPaths(result.resources)).toEqual(['references/guide.md']);
+        expect(result.skipped).toEqual([]);
+    });
+
+    it('ignores nested example paths (examples are flat)', async () => {
+        const result = await parseSkillUpload(zipFile({
+            'SKILL.md': strToU8(SKILL_MD),
+            'examples/ex1.md': strToU8('# Ex1'),
+            'examples/nested/ex2.md': strToU8('# Ex2'),
+        }));
+        expect(exampleNames(result.resources)).toEqual(['ex1.md']);
+    });
+});
diff --git a/tests/integrations/skills/test_skill_mutation.py b/tests/integrations/skills/test_skill_mutation.py
new file mode 100644
index 00000000..66366563
--- /dev/null
+++ b/tests/integrations/skills/test_skill_mutation.py
@@ -0,0 +1,380 @@
+"""Tests for the mutable SkillIntegrationProvider: creating, editing, removing,
+and previewing skills, resource CRUD, on-disk discovery, and path validation.
+"""
+import json
+import re
+from pathlib import Path
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+from beaker_notebook.lib.integrations.skill import (
+    SkillIntegrationProvider,
+    SKILL_RESOURCE_DIRS,
+)
+from beaker_notebook.lib.integrations.types import (
+    SkillIntegration,
+    SkillFileResource,
+    SkillExampleResource,
+    SkillMetadataResource,
+    SkillInstructionsResource,
+)
+
+# Route regex for a resource id path segment (app/api/integrations.py). Resource
+# ids must remain matchable here, i.e. contain no ':', '.', or '/'.
+RESOURCE_ID_RE = re.compile(r"[\w\d-]+")
+
+
+@pytest.fixture
+def provider(tmp_path: Path, monkeypatch) -> SkillIntegrationProvider:
+    """A provider whose search + writable roots are isolated to tmp_path and
+    that starts with an empty catalog (no skills discovered)."""
+    write_root = tmp_path / "writable"
+    monkeypatch.setattr(
+        SkillIntegrationProvider, "_candidate_write_roots",
+        classmethod(lambda cls: [write_root]),
+    )
+    monkeypatch.setattr(
+        "beaker_notebook.lib.integrations.skill.find_resource_dirs",
+        lambda *a, **k: [],
+    )
+    monkeypatch.setattr(
+        SkillIntegrationProvider, "_get_skill_search_roots",
+        classmethod(lambda cls: []),
+    )
+    p = SkillIntegrationProvider(id="test-provider", skill_paths=[])
+    p._test_write_root = write_root  # type: ignore[attr-defined]
+    return p
+
+
+def _mock_remote(text: str):
+    response = MagicMock()
+    response.text = text
+    response.raise_for_status = MagicMock()
+    return patch(
+        "beaker_notebook.lib.integrations.skill.requests.get",
+        return_value=response,
+    )
+
+
+REMOTE_MD = "---\nname: Remote Skill\ndescription: remote desc\nlicense: Apache-2.0\n---\n# Remote\n\nBody."
+
+
+# ---------------------------------------------------------------------------
+# add_integration (local)
+# ---------------------------------------------------------------------------
+
+class TestAddLocalSkill:
+    def test_creates_skill_md_and_registers(self, provider):
+        skill = provider.add_integration(
+            name="My Skill",
+            description="A test skill.",
+            source_type="local",
+            instructions="# My Skill\n\nDo the thing.",
+        )
+        assert isinstance(skill, SkillIntegration)
+        assert skill.source_type == "local"
+        assert skill in provider.list_integrations()
+        skill_md = Path(skill.base_path) / "SKILL.md"
+        assert skill_md.is_file()
+        text = skill_md.read_text()
+        assert "name: My Skill" in text
+        assert "Do the thing." in text
+
+    def test_deterministic_uuid(self, provider):
+        skill = provider.add_integration(name="My Skill", description="d", source_type="local")
+        assert skill.uuid == f"agent-skill:test-provider:{skill.slug}"
+
+    def test_writes_frontmatter_fields(self, provider):
+        skill = provider.add_integration(
+            name="Meta Skill",
+            description="d",
+            source_type="local",
+            license="MIT",
+            compatibility="python>=3.11",
+            allowed_tools="Bash, Read",
+            skill_metadata={"author": "matt"},
+        )
+        text = (Path(skill.base_path) / "SKILL.md").read_text()
+        assert "license: MIT" in text
+        assert "compatibility: python>=3.11" in text
+        assert "allowed-tools: Bash, Read" in text
+        assert "author: matt" in text
+
+    def test_lands_under_writable_root(self, provider):
+        skill = provider.add_integration(name="Where", description="d", source_type="local")
+        expected = provider._test_write_root / "skills" / skill.slug
+        assert Path(skill.base_path).resolve() == expected.resolve()
+
+    def test_duplicate_slug_raises(self, provider):
+        provider.add_integration(name="Dup", description="d", source_type="local")
+        with pytest.raises(ValueError):
+            provider.add_integration(name="Dup", description="d2", source_type="local")
+
+    def test_missing_name_raises(self, provider):
+        with pytest.raises(ValueError):
+            provider.add_integration(description="d", source_type="local")
+
+
+# ---------------------------------------------------------------------------
+# update_integration (local)
+# ---------------------------------------------------------------------------
+
+class TestUpdateLocalSkill:
+    def test_rewrites_body_and_description(self, provider):
+        skill = provider.add_integration(
+            name="Edit Me", description="old", source_type="local",
+            instructions="old body",
+        )
+        updated = provider.update_integration(
+            skill.uuid, name="Edit Me", description="new", instructions="new body",
+        )
+        assert updated.uuid == skill.uuid  # identity stable
+        assert updated.description == "new"
+        text = (Path(updated.base_path) / "SKILL.md").read_text()
+        assert "description: new" in text
+        assert "new body" in text
+
+    def test_preserves_metadata_when_omitted(self, provider):
+        skill = provider.add_integration(
+            name="Keep Meta", description="d", source_type="local",
+            license="MIT", skill_metadata={"author": "matt"},
+        )
+        # Update only the description; license/metadata must survive.
+        updated = provider.update_integration(skill.uuid, description="changed")
+        meta = next(r for r in updated.resources.values() if isinstance(r, SkillMetadataResource))
+        assert meta.license == "MIT"
+        assert meta.skill_metadata == {"author": "matt"}
+
+
+# ---------------------------------------------------------------------------
+# remove_integration
+# ---------------------------------------------------------------------------
+
+class TestRemoveSkill:
+    def test_local_deletes_dir_and_unregisters(self, provider):
+        skill = provider.add_integration(name="Doomed", description="d", source_type="local")
+        base = Path(skill.base_path)
+        assert base.is_dir()
+        provider.remove_integration(skill.uuid)
+        assert not base.exists()
+        assert all(s.uuid != skill.uuid for s in provider.list_integrations())
+
+
+# ---------------------------------------------------------------------------
+# Remote skills
+# ---------------------------------------------------------------------------
+
+class TestRemoteSkill:
+    def test_add_writes_manifest_and_sets_url(self, provider):
+        with _mock_remote(REMOTE_MD):
+            skill = provider.add_integration(source_type="remote", url="https://ex.com/skill/")
+        assert skill.source_type == "remote"
+        assert skill.url == "https://ex.com/skill/"
+        manifest = provider._test_write_root / "skills.json"
+        assert "https://ex.com/skill/" in json.loads(manifest.read_text())
+
+    def test_update_rewrites_manifest_url(self, provider):
+        with _mock_remote(REMOTE_MD):
+            skill = provider.add_integration(source_type="remote", url="https://ex.com/a/")
+        with _mock_remote(REMOTE_MD):
+            provider.update_integration(skill.uuid, url="https://ex.com/b/")
+        manifest = provider._test_write_root / "skills.json"
+        entries = json.loads(manifest.read_text())
+        assert "https://ex.com/b/" in entries
+        assert "https://ex.com/a/" not in entries
+
+    def test_remove_removes_manifest_entry(self, provider):
+        with _mock_remote(REMOTE_MD):
+            skill = provider.add_integration(source_type="remote", url="https://ex.com/skill/")
+        provider.remove_integration(skill.uuid)
+        manifest = provider._test_write_root / "skills.json"
+        assert "https://ex.com/skill/" not in json.loads(manifest.read_text())
+
+    def test_resource_add_rejected_for_remote(self, provider):
+        with _mock_remote(REMOTE_MD):
+            skill = provider.add_integration(source_type="remote", url="https://ex.com/skill/")
+        with pytest.raises(ValueError):
+            provider.add_resource(
+                skill.uuid, resource_type="skill_file",
+                relative_path="references/x.md", content="x",
+            )
+
+
+# ---------------------------------------------------------------------------
+# Preview (unsaved)
+# ---------------------------------------------------------------------------
+
+class TestPreview:
+    def test_content_preview_not_persisted(self, provider):
+        before = len(provider.list_integrations())
+        skill = provider.add_integration(
+            preview=True, source_type="local",
+            content="---\nname: Preview\ndescription: d\nlicense: MIT\n---\n# body",
+        )
+        assert len(provider.list_integrations()) == before  # not added
+        assert skill.name == "Preview"
+
+    def test_content_preview_has_no_file_resources(self, provider):
+        # A body that references files must NOT yield phantom skill_file resources
+        # in a preview (base_path-less); the client enumerates the real files.
+        skill = provider.add_integration(
+            preview=True, source_type="local",
+            content="---\nname: P\ndescription: d\n---\n# body\n\nSee [x](./reference/x.md).",
+        )
+        kinds = {r.resource_type for r in skill.resources.values()}
+        assert kinds == {"skill_metadata", "skill_instructions"}
+
+    def test_remote_preview_fetches_not_persisted(self, provider):
+        before = len(provider.list_integrations())
+        with _mock_remote(REMOTE_MD):
+            skill = provider.add_integration(preview=True, source_type="remote", url="https://ex.com/s/")
+        assert len(provider.list_integrations()) == before
+        assert skill.name == "Remote Skill"
+
+    def test_content_preview_requires_content(self, provider):
+        with pytest.raises(ValueError):
+            provider.add_integration(preview=True, source_type="local")
+
+
+# ---------------------------------------------------------------------------
+# Resource CRUD (local)
+# ---------------------------------------------------------------------------
+
+class TestResourceCRUD:
+    def _skill(self, provider):
+        return provider.add_integration(name="Res Skill", description="d", source_type="local")
+
+    def test_add_skill_file_writes_and_registers(self, provider):
+        skill = self._skill(provider)
+        resource = provider.add_resource(
+            skill.uuid, resource_type="skill_file",
+            relative_path="references/guide.md", content="guide text",
+        )
+        assert isinstance(resource, SkillFileResource)
+        assert (Path(skill.base_path) / "references/guide.md").read_text() == "guide text"
+        assert resource.resource_id in skill.resources
+
+    def test_add_skill_example_writes(self, provider):
+        skill = self._skill(provider)
+        resource = provider.add_resource(
+            skill.uuid, resource_type="skill_example",
+            filename="ex1.md", content="# Example One\n\ndesc",
+        )
+        assert isinstance(resource, SkillExampleResource)
+        assert (Path(skill.base_path) / "examples/ex1.md").is_file()
+
+    def test_resource_id_is_url_safe(self, provider):
+        skill = self._skill(provider)
+        resource = provider.add_resource(
+            skill.uuid, resource_type="skill_file",
+            relative_path="scripts/run.py", content="print(1)",
+        )
+        assert RESOURCE_ID_RE.fullmatch(resource.resource_id), resource.resource_id
+
+    def test_update_resource_rewrites_content(self, provider):
+        skill = self._skill(provider)
+        resource = provider.add_resource(
+            skill.uuid, resource_type="skill_file",
+            relative_path="references/g.md", content="v1",
+        )
+        provider.update_resource(skill.uuid, resource.resource_id, content="v2")
+        assert (Path(skill.base_path) / "references/g.md").read_text() == "v2"
+
+    def test_remove_resource_deletes_file(self, provider):
+        skill = self._skill(provider)
+        resource = provider.add_resource(
+            skill.uuid, resource_type="skill_file",
+            relative_path="assets/a.txt", content="a",
+        )
+        provider.remove_resource(skill.uuid, resource.resource_id)
+        assert not (Path(skill.base_path) / "assets/a.txt").exists()
+        assert resource.resource_id not in skill.resources
+
+    def test_singular_reference_dir_accepted(self, provider):
+        skill = self._skill(provider)
+        provider.add_resource(
+            skill.uuid, resource_type="skill_file",
+            relative_path="reference/node.md", content="node",
+        )
+        assert (Path(skill.base_path) / "reference/node.md").read_text() == "node"
+
+    @pytest.mark.parametrize("bad_path", [
+        "../escape.md",
+        "/abs/path.md",
+        "references/../../escape.md",
+        "notadir/x.md",
+    ])
+    def test_invalid_relative_path_rejected(self, provider, bad_path):
+        skill = self._skill(provider)
+        with pytest.raises(ValueError):
+            provider.add_resource(
+                skill.uuid, resource_type="skill_file",
+                relative_path=bad_path, content="x",
+            )
+
+
+# ---------------------------------------------------------------------------
+# On-disk discovery / scan behavior
+# ---------------------------------------------------------------------------
+
+class TestDiscoveryScan:
+    def _write_skill(self, root: Path, name: str, body: str, files: dict[str, str]) -> Path:
+        d = root / name
+        d.mkdir(parents=True)
+        (d / "SKILL.md").write_text(f"---\nname: {name}\ndescription: d\n---\n{body}")
+        for rel, content in files.items():
+            fp = d / rel
+            fp.parent.mkdir(parents=True, exist_ok=True)
+            fp.write_text(content)
+        return d
+
+    def test_local_files_from_disk_scan(self, tmp_path, monkeypatch):
+        skill_dir = self._write_skill(
+            tmp_path, "scan-skill", "# body (no file references)",
+            {"references/a.md": "a", "scripts/b.py": "b", "reference/c.md": "c"},
+        )
+        monkeypatch.setattr(
+            "beaker_notebook.lib.integrations.skill.find_resource_dirs", lambda *a, **k: [])
+        skill = SkillIntegrationProvider._load_local_skill(str(skill_dir))
+        paths = {r.relative_path for r in skill.resources.values() if isinstance(r, SkillFileResource)}
+        # All on-disk files enumerated even though the body references none.
+        assert paths == {"references/a.md", "scripts/b.py", "reference/c.md"}
+
+    def test_local_ignores_body_only_references(self, tmp_path, monkeypatch):
+        # SKILL.md references a file that is NOT on disk -> must not appear.
+        skill_dir = self._write_skill(
+            tmp_path, "phantom-skill", "See [x](references/missing.md).", {},
+        )
+        monkeypatch.setattr(
+            "beaker_notebook.lib.integrations.skill.find_resource_dirs", lambda *a, **k: [])
+        skill = SkillIntegrationProvider._load_local_skill(str(skill_dir))
+        file_resources = [r for r in skill.resources.values() if isinstance(r, SkillFileResource)]
+        assert file_resources == []
+
+    def test_remote_uses_body_references(self, provider):
+        body_md = "---\nname: R\ndescription: d\n---\n# body\n\nUse `references/guide.md`."
+        with _mock_remote(body_md):
+            skill = provider._load_remote_skill("https://ex.com/s/")
+        paths = {r.relative_path for r in skill.resources.values() if isinstance(r, SkillFileResource)}
+        assert "references/guide.md" in paths
+
+
+# ---------------------------------------------------------------------------
+# Context corpus namespacing (drives the read-only gate on the frontend)
+# ---------------------------------------------------------------------------
+
+class TestContextCorpus:
+    def test_context_provider_namespaces_corpus(self, tmp_path, monkeypatch):
+        d = tmp_path / "skills" / "ctx-skill"
+        d.mkdir(parents=True)
+        (d / "SKILL.md").write_text("---\nname: ctx-skill\ndescription: d\n---\n# body")
+        monkeypatch.setattr(
+            "beaker_notebook.lib.integrations.skill.find_resource_dirs", lambda *a, **k: [])
+        monkeypatch.setattr(
+            SkillIntegrationProvider, "_get_skill_search_roots",
+            classmethod(lambda cls: [tmp_path]))
+        provider = SkillIntegrationProvider(id="context-weather")
+        skill = provider.list_integrations()[0]
+        assert skill.corpus == "context-weather"
+        assert skill.uuid.startswith("agent-skill:context-weather:")
diff --git a/tests/integrations/skills/test_skill_provider.py b/tests/integrations/skills/test_skill_provider.py
index 581cf26a..2b51e1e7 100644
--- a/tests/integrations/skills/test_skill_provider.py
+++ b/tests/integrations/skills/test_skill_provider.py
@@ -217,6 +217,16 @@ def test_examples_paths_excluded(self):
         assert "examples/basic.md" not in refs
         assert "references/guide.md" in refs
 
+    def test_leading_dot_slash_normalized(self):
+        # A "./x" link normalizes to "x" so it matches on-disk / enumerated paths.
+        refs = extract_file_references("See [node](./reference/node.md).")
+        assert refs == ["reference/node.md"]
+
+    def test_singular_reference_backtick(self):
+        # The backtick form also recognizes the singular "reference/" directory.
+        refs = extract_file_references("Use `reference/patterns.md` here.")
+        assert "reference/patterns.md" in refs
+
 
 # ---------------------------------------------------------------------------
 # SkillIntegrationProvider — local loading

From c9913bc22395f164b7fdf4d82e275665c86ae3bc Mon Sep 17 00:00:00 2001
From: Matthew Printz <matt@jataware.com>
Date: Tue, 21 Jul 2026 11:58:25 -0600
Subject: [PATCH 3/7] Doc update and final cleanup

---
 .../src/util/__tests__/skillArchive.spec.ts   | 12 ++++
 beaker-vue/src/util/skillArchive.ts           | 24 +++++--
 docs/concept_integrations.md                  | 10 +++
 docs/integration_providers.md                 | 19 ++++--
 docs/integrations_api.md                      |  9 ++-
 src/beaker_notebook/lib/integrations/skill.py | 66 +++++++++++++------
 6 files changed, 108 insertions(+), 32 deletions(-)

diff --git a/beaker-vue/src/util/__tests__/skillArchive.spec.ts b/beaker-vue/src/util/__tests__/skillArchive.spec.ts
index 84d0720c..eb8fc228 100644
--- a/beaker-vue/src/util/__tests__/skillArchive.spec.ts
+++ b/beaker-vue/src/util/__tests__/skillArchive.spec.ts
@@ -61,6 +61,18 @@ describe('parseSkillUpload', () => {
         expect(relPaths(result.resources)).toEqual(['reference/node.md', 'scripts/run.py']);
     });
 
+    it('recognizes singular resource and example directory names', async () => {
+        const result = await parseSkillUpload(zipFile({
+            'SKILL.md': strToU8(SKILL_MD),
+            'reference/a.md': strToU8('a'),
+            'script/b.py': strToU8('b'),
+            'asset/c.json': strToU8('{}'),
+            'example/ex.md': strToU8('# Ex'),
+        }));
+        expect(relPaths(result.resources)).toEqual(['asset/c.json', 'reference/a.md', 'script/b.py']);
+        expect(exampleNames(result.resources)).toEqual(['ex.md']);
+    });
+
     it('captures example content and file content', async () => {
         const result = await parseSkillUpload(zipFile({
             'SKILL.md': strToU8(SKILL_MD),
diff --git a/beaker-vue/src/util/skillArchive.ts b/beaker-vue/src/util/skillArchive.ts
index ed522c4e..0f45227e 100644
--- a/beaker-vue/src/util/skillArchive.ts
+++ b/beaker-vue/src/util/skillArchive.ts
@@ -11,11 +11,21 @@ const MAX_FILE_BYTES = 50 * 1024 * 1024;
 const MAX_ENTRIES = 2000;
 const MAX_TOTAL_BYTES = 100 * 1024 * 1024;
 
-// Subtrees whose files become skill resources (mirrors the backend
-// SKILL_RESOURCE_DIRS). Both "references" and the singular "reference" are
-// recognized because real skills use the singular form. Anything outside these
-// (and SKILL.md / examples) is ignored.
-const RESOURCE_DIRS = ['references', 'reference', 'scripts', 'assets'];
+// Mirror of `with_plurals` in src/beaker_notebook/lib/integrations/skill.py:
+// naively appends "s" (does not handle irregular plurals) so both the singular
+// and plural directory names are recognized.
+const withPlurals = (items: string[]): string[] =>
+    items.flatMap((item) => [`${item}s`, item]);
+
+// Directory names whose files become skill resources. These MUST stay in sync
+// with SKILL_RESOURCE_DIRS / SKILL_EXAMPLE_DIRS in
+// src/beaker_notebook/lib/integrations/skill.py — the backend re-validates every
+// resource path on save, so a name recognized here but not there is rejected
+// (and vice versa a file in a dir only the backend knows is never uploaded).
+// Both singular and plural forms are recognized because real skills use either.
+// Anything outside these (and SKILL.md) is ignored.
+const RESOURCE_DIRS = withPlurals(['reference', 'script', 'asset']);
+const EXAMPLE_DIRS = withPlurals(['example']);
 
 export interface EnumeratedResource {
     resource_type: 'skill_file' | 'skill_example';
@@ -119,8 +129,8 @@ export async function parseSkillUpload(file: File): Promise<ParsedSkillUpload> {
         const parts = rel.split('/');
         const top = parts[0];
 
-        if (top === 'examples') {
-            // Examples are flat (examples/<file>); ignore nested paths.
+        if (EXAMPLE_DIRS.includes(top)) {
+            // Examples are flat (<dir>/<file>); ignore nested paths.
             if (parts.length !== 2) {
                 continue;
             }
diff --git a/docs/concept_integrations.md b/docs/concept_integrations.md
index c5826944..e2c58130 100644
--- a/docs/concept_integrations.md
+++ b/docs/concept_integrations.md
@@ -24,4 +24,14 @@ You will encounter integrations primarily in two places:
 * In the **Integrations panel**, which lists what's available in your current context and lets you add or configure them.
 * In conversation with the agent, when it tells you it's looking something up via an integration, fetching data, or following the instructions in a skill.
 
+## Working with skills
+
+The Integrations panel lets you view and manage **skills** directly:
+
+* **Local skills** live on disk and are fully editable. You can create a new skill, edit its name, description, instructions (the `SKILL.md` body), and metadata, and add, edit, or remove its resource files (progressively-disclosed `reference`, `script`, and `asset` files, and code `examples`) that the agent loads on demand.
+* **Remote skills** are defined by a URL pointing at a hosted `SKILL.md`. You select the *remote* source type and enter the URL; the fetched content is read-only. Use **Fetch** to preview a remote skill before saving.
+* **Importing a skill** — click **Upload** (or drag a file onto the Integrations panel) to import a skill from a `SKILL.md` file or a `.zip` containing a skill directory. The skill's details are read from the file so you can review them before saving.
+
+Skills **bundled with a context** are shown read-only — the panel opens them in a viewer rather than the editor — since a context owns its own skills. Everything else you added yourself is editable.
+
 To build your own integration provider, see [Integration Development](integration_development.html).
diff --git a/docs/integration_providers.md b/docs/integration_providers.md
index c5c68f83..7fedf704 100644
--- a/docs/integration_providers.md
+++ b/docs/integration_providers.md
@@ -29,11 +29,22 @@ def get_resource(self, integration_id: str, resource_id: str) -> Resource:
     ...
 ```
 
-The provider's display name is set during initialization via `super().__init__(display_name)`.
+A provider's identity is declared with class variables — `provider_type`, `slug`, and `display_name` — set on the provider class (not passed to `__init__`, which takes only an optional `id`).
 
-Providers inheriting `MutableBaseIntegrationProvider` — designed to have integrations added, updated, or deleted at runtime — have additional methods to implement for those add/update/delete flows.
+Providers inheriting `MutableBaseIntegrationProvider` — designed to have integrations added, updated, or deleted at runtime — implement the following additional methods for those flows:
 
-See `beaker_kernel/lib/integrations/base.py` for the full base class.
+```python
+def add_integration(self, **payload) -> Integration: ...
+def update_integration(self, integration_id: str, **payload) -> Integration: ...
+def remove_integration(self, integration_id: str, **payload) -> None: ...
+def add_resource(self, integration_id: str, **payload) -> Resource: ...
+def update_resource(self, integration_id: str, resource_id: str, **payload) -> Resource: ...
+def remove_resource(self, integration_id: str, resource_id: str, **payload) -> None: ...
+```
+
+These are the methods behind the create/update/delete routes in the [REST API](integrations_api.html). `SkillIntegrationProvider` (local skills persisted to disk) and `MCPIntegrationProvider` are working examples of mutable providers.
+
+See `beaker_notebook/lib/integrations/base.py` for the full base class.
 
 How a provider stores its integrations and manages their lifecycle is entirely up to the provider implementation.
 
@@ -63,7 +74,7 @@ At a glance:
 
 ## Integration and Resource types
 
-The `Integration` and `Resource` dataclasses, along with the specialized resource subclasses (`FileResource`, `ExampleResource`, `SkillMetadataResource`, `SkillInstructionsResource`, `SkillFileResource`, `SkillExampleResource`), are defined in `beaker_kernel/lib/integrations/types.py`. Resources are anything inheriting `Resource`, which carries:
+The `Integration` and `Resource` dataclasses, along with the specialized resource subclasses (`FileResource`, `ExampleResource`, `SkillMetadataResource`, `SkillInstructionsResource`, `SkillFileResource`, `SkillExampleResource`), are defined in `beaker_notebook/lib/integrations/types.py`. Resources are anything inheriting `Resource`, which carries:
 
 * `resource_type` — a `ClassVar` defined on subclasses
 * `resource_id` — a UUID
diff --git a/docs/integrations_api.md b/docs/integrations_api.md
index aa1529c6..1102db5b 100644
--- a/docs/integrations_api.md
+++ b/docs/integrations_api.md
@@ -32,6 +32,9 @@ Note: Integrations are exposed as a flattened map, so that no consumer is respon
 * `POST /beaker/integrations/{session_id}/{integration_id}`:
     * Method: `provider.update_integration(integration_id)`
 
+* `DELETE /beaker/integrations/{session_id}/{integration_id}`:
+    * Method: `provider.remove_integration(integration_id)`
+
 * `POST /beaker/integrations/{session_id}/{integration_id}/{resource_type}`:
     * Method: `provider.add_resource(integration_id)`
 
@@ -39,9 +42,11 @@ Note: Integrations are exposed as a flattened map, so that no consumer is respon
     * Method: `provider.update_resource(integration_id, resource_id)`
 
 * `DELETE /beaker/integrations/{session_id}/{integration_id}/{resource_type}/{resource_id}`:
-    * Method: `provider.delete_resource(integration_id, resource_id)`
+    * Method: `provider.remove_resource(integration_id, resource_id)`
+
+POST bodies are accessed through `**kwargs` on all of the respective methods above. What a body must contain is defined by the target provider (for example, a provider may accept a flag that previews a build without persisting it).
 
-POST bodies are accessed through `**kwargs` on all of the respective methods above.
+The add / update / remove methods above are only available on providers that inherit `MutableBaseIntegrationProvider`; see [Providers](integration_providers.html).
 
 ## REST API Implementation
 
diff --git a/src/beaker_notebook/lib/integrations/skill.py b/src/beaker_notebook/lib/integrations/skill.py
index 835efcb3..15cced53 100644
--- a/src/beaker_notebook/lib/integrations/skill.py
+++ b/src/beaker_notebook/lib/integrations/skill.py
@@ -5,7 +5,7 @@
 import re
 import shutil
 from pathlib import Path
-from typing import TYPE_CHECKING, Any, ClassVar, Optional, Mapping, cast
+from typing import TYPE_CHECKING, Any, ClassVar, Collection, Optional, Mapping, TypeAlias, cast
 from typing_extensions import Self
 from uuid import uuid4
 
@@ -29,7 +29,33 @@
 # resource files (mirrors the Agent Skills layout). Order is the display order.
 # Both "references" and the singular "reference" are recognized because real
 # skills (e.g. Anthropic's own) use the singular form.
-SKILL_RESOURCE_DIRS = ("references", "reference", "scripts", "assets")
+TypeCollection: TypeAlias = tuple[str, ...]
+
+def with_plurals(items: Collection[str], plural_form_first: bool = True) -> TypeCollection:
+    """
+    Returns a tuple of both the original value and plural value for each
+    string in a collection.
+
+    Note: Pluralization naively adds an 's' to the end of the string.
+    It does not validate that the original string is singular or
+    handle special plural forms such as -es, -i, etc.
+    """
+    return tuple(
+        item_str
+        for item in items
+        for item_str in ((f'{item}s', item) if plural_form_first else (item, f'{item}s'))
+    )
+
+# The recognized directory names below are mirrored on the frontend in
+# beaker-vue/src/util/skillArchive.ts (which enumerates an uploaded skill's
+# files). Keep the two in sync: a dir the client enumerates but this provider
+# rejects (see _validate_resource_path) fails on save, and a dir only this
+# provider knows is never uploaded by the client.
+SKILL_RESOURCE_TYPES: TypeCollection = ("reference", "script", "asset")
+SKILL_RESOURCE_DIRS: TypeCollection = with_plurals(SKILL_RESOURCE_TYPES)
+SKILL_EXAMPLE_TYPES: TypeCollection = ("example",)
+SKILL_EXAMPLE_DIRS: TypeCollection = with_plurals(SKILL_EXAMPLE_TYPES)
+
 if TYPE_CHECKING:
     from beaker_notebook.lib.agent import BeakerAgent
     from beaker_notebook.lib.context import BeakerContext
@@ -158,6 +184,7 @@ def extract_file_references(body: str) -> list[str]:
 
     # Markdown links: [text](path)
     link_pattern = re.compile(r'\[(?:[^\]]*)\]\(([^)]+)\)')
+    example_paths = tuple((f"{example_path}/" for example_path in SKILL_EXAMPLE_DIRS))
     for match in link_pattern.finditer(body):
         path = match.group(1)
         # Normalize a leading "./" so a body reference like ./reference/x.md
@@ -167,12 +194,13 @@ def extract_file_references(body: str) -> list[str]:
             path = path[2:]
         if not path.startswith(("http://", "https://", "#", "mailto:")):
             # Skip examples/ paths — they are handled as SkillExampleResources
-            if not path.startswith("examples/") and path != "examples/":
+            if not path.startswith(example_paths) and path not in example_paths:
                 references.append(path)
 
     # Backtick-quoted file paths: `some/path.ext`
     # Match paths that contain a / and end with a file extension
-    backtick_pattern = re.compile(r'`((?:references|reference|scripts|assets)/[^`]+)`')
+    backtick_pattern_str = rf'`((?:{"|".join(SKILL_RESOURCE_DIRS)})/[^`]+)`'
+    backtick_pattern = re.compile(backtick_pattern_str)
     for match in backtick_pattern.finditer(body):
         references.append(match.group(1))
 
@@ -589,21 +617,21 @@ def _discover_examples(
         """
         resources = []
         if source_type == "local" and base_path:
-            examples_dir = Path(base_path) / "examples"
-            if examples_dir.is_dir():
-                for example_path in sorted(examples_dir.glob("*.md")):
-                    try:
-                        content = example_path.read_text(encoding="utf-8")
-                        title, description = parse_example_md(content)
-                        resources.append(SkillExampleResource(
-                            integration=skill.uuid,
-                            filename=example_path.name,
-                            title=title or example_path.stem,
-                            description=description,
-                            content=None,  # Loaded on demand (tier 3)
-                        ))
-                    except Exception:
-                        logger.exception("Failed to parse example: %s", example_path)
+            for examples_dir in ((Path(base_path) / example_dir) for example_dir in SKILL_EXAMPLE_DIRS):
+                if examples_dir.is_dir():
+                    for example_path in sorted(examples_dir.glob("*.md")):
+                        try:
+                            content = example_path.read_text(encoding="utf-8")
+                            title, description = parse_example_md(content)
+                            resources.append(SkillExampleResource(
+                                integration=skill.uuid,
+                                filename=example_path.name,
+                                title=title or example_path.stem,
+                                description=description,
+                                content=None,  # Loaded on demand (tier 3)
+                            ))
+                        except Exception:
+                            logger.exception("Failed to parse example: %s", example_path)
         return resources
 
     # --- Abstract method implementations ---

From 15c94bcd63710679f05b06f1bdd0b451d0db6f59 Mon Sep 17 00:00:00 2001
From: Matthew Printz <matt@jataware.com>
Date: Tue, 21 Jul 2026 16:08:11 -0600
Subject: [PATCH 4/7] Interface fixes from testing

---
 .../integrations/IntegrationPanel.vue         |  2 +-
 beaker-vue/src/composables/index.ts           |  1 +
 .../src/composables/useIntegrationUpload.ts   | 56 +++++++++++++++++
 .../src/pages/IntegrationsInterface.vue       | 61 ++++++++++++++++---
 beaker-vue/src/pages/NotebookInterface.vue    |  6 ++
 5 files changed, 118 insertions(+), 8 deletions(-)
 create mode 100644 beaker-vue/src/composables/useIntegrationUpload.ts

diff --git a/beaker-vue/src/components/integrations/IntegrationPanel.vue b/beaker-vue/src/components/integrations/IntegrationPanel.vue
index 26c1f62c..ffceb810 100644
--- a/beaker-vue/src/components/integrations/IntegrationPanel.vue
+++ b/beaker-vue/src/components/integrations/IntegrationPanel.vue
@@ -223,7 +223,7 @@ const sessionIdParam = urlParams.has("session") ? `&session=${urlParams.get("ses
 const beakerSession = inject<BeakerSessionComponentType>("beakerSession");
 
 const sortIntegrations = (integrations: Integration[]) =>
-    integrations.toSorted((a, b) => a?.name.localeCompare(b?.name))
+    integrations.toSorted((a, b) => (a?.name ?? '').localeCompare(b?.name ?? ''))
 
 const filterIntegrations = (integrations: Integration[]) =>
     integrations.filter(integration =>
diff --git a/beaker-vue/src/composables/index.ts b/beaker-vue/src/composables/index.ts
index c534b017..c3877915 100644
--- a/beaker-vue/src/composables/index.ts
+++ b/beaker-vue/src/composables/index.ts
@@ -1,3 +1,4 @@
+export * from './useIntegrationUpload';
 export * from './useNotebookInterface';
 export * from './useNotebookSnapshot';
 export * from './useQueryCellFlattening';
diff --git a/beaker-vue/src/composables/useIntegrationUpload.ts b/beaker-vue/src/composables/useIntegrationUpload.ts
new file mode 100644
index 00000000..98564f17
--- /dev/null
+++ b/beaker-vue/src/composables/useIntegrationUpload.ts
@@ -0,0 +1,56 @@
+import { ref, toValue, type MaybeRefOrGetter } from 'vue';
+import { useRouter } from 'vue-router';
+
+// Module-scoped singleton: a raw upload File handed off from a page that does
+// not itself parse skill uploads (e.g. the notebook) to the integrations page,
+// which owns the parse/preview flow. Module scope is deliberate — it must
+// survive the route navigation that unmounts the originating page.
+const pendingUploadFile = ref<File | null>(null);
+
+export interface UseIntegrationUploadOptions {
+    /** Session id to forward so the integrations page resolves the same session. */
+    sessionId?: MaybeRefOrGetter<string | null | undefined>;
+}
+
+export interface UseIntegrationUploadReturn {
+    handleUpload: (file: File) => Promise<void>;
+    takePendingUpload: () => File | null;
+}
+
+/**
+ * Bridges the IntegrationPanel `upload` event from pages that cannot handle it
+ * in place (currently the notebook) over to the integrations page. The raw
+ * File is stashed and the integrations page is opened in "new skill" mode,
+ * where the existing upload handler picks the file up and parses it.
+ */
+export const useIntegrationUpload = (
+    options: UseIntegrationUploadOptions = {},
+): UseIntegrationUploadReturn => {
+    const router = useRouter();
+
+    const handleUpload = async (file: File): Promise<void> => {
+        pendingUploadFile.value = file;
+        // `selected=upload` is a distinct signal from `selected=new` (a blank
+        // new integration): it tells the integrations page to consume the
+        // stashed file rather than open an empty editor.
+        const query: Record<string, string> = { selected: 'upload' };
+        const sessionId = toValue(options.sessionId);
+        if (sessionId) {
+            query.session = sessionId;
+        }
+        await router.push({ name: 'integrations', query });
+    };
+
+    // Consumed once by the integrations page; clears the stash so a later blank
+    // "New → Skill" does not re-trigger a stale import.
+    const takePendingUpload = (): File | null => {
+        const file = pendingUploadFile.value;
+        pendingUploadFile.value = null;
+        return file;
+    };
+
+    return {
+        handleUpload,
+        takePendingUpload,
+    };
+};
diff --git a/beaker-vue/src/pages/IntegrationsInterface.vue b/beaker-vue/src/pages/IntegrationsInterface.vue
index 86fbbe4c..da810e7c 100644
--- a/beaker-vue/src/pages/IntegrationsInterface.vue
+++ b/beaker-vue/src/pages/IntegrationsInterface.vue
@@ -213,6 +213,7 @@ import {
 } from '@/util/integration';
 import { parseSkillUpload } from '@/util/skillArchive';
 import { useRoute } from 'vue-router';
+import { useIntegrationUpload } from '../composables/useIntegrationUpload';
 
 const beakerNotebookRef = ref<BeakerNotebookComponentType>();
 const beakerInterfaceRef = ref();
@@ -360,7 +361,7 @@ const readOnly = computed<boolean>(() => {
 // --- Integration selector logic (moved from IntegrationEditor) ---
 
 const sortIntegrations = (integrations: IntegrationMap): Integration[] =>
-    Object.values(integrations).toSorted((a, b) => a?.name.localeCompare(b?.name));
+    Object.values(integrations).toSorted((a, b) => (a?.name ?? '').localeCompare(b?.name ?? ''));
 
 const sortedIntegrations = computed<Integration[]>(() =>
     sortIntegrations(integrations.value.integrations ?? {}));
@@ -492,10 +493,35 @@ const delayUntil = (condition, retryInterval) => {
     return new Promise(poll);
 };
 
+const { takePendingUpload } = useIntegrationUpload();
+
 const route = useRoute();
-watch(() => route, (newRoute) => {
-    if (newRoute.query?.selected === "new") {
-        const providerType = (newRoute.query?.type as string | undefined) ?? 'skill';
+// Watch only the `selected` query value (not the whole route object) so a
+// single navigation fires this exactly once. A deep watch on the route re-fired
+// as the route settled, letting a later fire clobber a just-filled-in upload
+// with a blank `newIntegration`.
+watch(() => route.query?.selected, (selected) => {
+    if (selected === "upload") {
+        // Hand-off from another page's upload (e.g. the notebook): consume the
+        // stashed file and run the full parse/preview flow. Falls back to a
+        // blank new skill if there is no pending file (e.g. a reload of this
+        // URL, where the module-level stash is empty).
+        const pendingFile = takePendingUpload();
+        const start = () => {
+            if (pendingFile) {
+                handleSkillUpload(pendingFile);
+            } else {
+                newIntegration('skill');
+            }
+        };
+        if (integrations.value.finishedInitialLoad) {
+            start();
+        } else {
+            delayUntil(() => integrations.value.finishedInitialLoad, 100)
+                .then(start);
+        }
+    } else if (selected === "new") {
+        const providerType = (route.query?.type as string | undefined) ?? 'skill';
         if (integrations.value.finishedInitialLoad) {
             newIntegration(providerType);
         } else {
@@ -503,9 +529,23 @@ watch(() => route, (newRoute) => {
                 .then(() => newIntegration(providerType));
         }
     } else {
-        integrations.value.selected = newRoute.query?.selected as string | undefined ?? integrations.value.selected;
+        integrations.value.selected = selected as string | undefined ?? integrations.value.selected;
     }
-}, {immediate: true, deep: true});
+}, {immediate: true});
+
+// Whenever selection moves off an unsaved "new" entry, drop it so it doesn't
+// linger in the list. This covers every path that changes the selection (route
+// navigation, the Select dropdown, the New Integration button), not just route
+// changes. A successful save removes "new" via its own path; by the time this
+// fires the save has already captured what it needs, so the extra delete is a
+// harmless no-op. `newIntegration` keeps selection on "new" (overwriting the
+// entry), so it does not trigger this.
+watch(() => integrations.value.selected, (newSelected, oldSelected) => {
+    if (oldSelected === "new" && newSelected !== "new" && integrations.value.integrations?.["new"]) {
+        delete integrations.value.integrations["new"];
+        integrations.value.unsavedChanges = false;
+    }
+});
 
 // --- API operations ---
 
@@ -526,7 +566,14 @@ const fetchResourcesForSelectedIntegration = async () => {
 }
 
 const fetchIntegrations = async () => {
-    integrations.value.integrations = await listIntegrations(sessionId);
+    const fetched = await listIntegrations(sessionId);
+    // Preserve any unsaved, client-only "new" entry (an in-progress upload or a
+    // blank new integration). It has no server-side counterpart, so replacing
+    // the map wholesale would wipe it -- which is what caused an uploaded skill
+    // to flash in and then vanish when a refetch (triggered by session/context
+    // changes) landed after the upload populated it.
+    const unsaved = integrations.value.integrations?.["new"];
+    integrations.value.integrations = unsaved ? { ...fetched, new: unsaved } : fetched;
     integrations.value.finishedInitialLoad = true;
 }
 
diff --git a/beaker-vue/src/pages/NotebookInterface.vue b/beaker-vue/src/pages/NotebookInterface.vue
index d5a674d1..3a1d7092 100644
--- a/beaker-vue/src/pages/NotebookInterface.vue
+++ b/beaker-vue/src/pages/NotebookInterface.vue
@@ -120,6 +120,7 @@
                 >
                     <IntegrationPanel
                         v-model="integrations"
+                        @upload="handleIntegrationUpload"
                     >
                     </IntegrationPanel>
                 </SideMenuPanel>
@@ -214,6 +215,7 @@ import BeakerQueryCell from '../components/cell/BeakerQueryCell.vue';
 import BeakerRawCell from '../components/cell/BeakerRawCell.vue';
 import BeakerAgentCell from '../components/cell/BeakerAgentCell.vue';
 
+import { useIntegrationUpload } from '../composables/useIntegrationUpload';
 import { useNotebookInterface } from '../composables/useNotebookInterface';
 import { useQueryCellFlattening } from '../composables/useQueryCellFlattening';
 import { listIntegrations, type IntegrationMap } from '../util/integration';
@@ -270,6 +272,10 @@ beakerApp.setPage("notebook");
 const urlParams = new URLSearchParams(window.location.search);
 const sessionIdFromUrl = urlParams.has("session") ? urlParams.get("session") : "nextgen_notebook_dev_session";
 const sessionIdFromProps = computed(() => props.sessionId);
+
+const { handleUpload: handleIntegrationUpload } = useIntegrationUpload({
+    sessionId: () => sessionIdFromProps.value || sessionIdFromUrl,
+});
 const renderersFromProps = computed(() => props.renderers);
 
 const truncateAgentCodeCells = ref<boolean>(false);

From 02c7de99ba0002094303fb8c6231daf227b8f650 Mon Sep 17 00:00:00 2001
From: Matthew Printz <matt@jataware.com>
Date: Tue, 21 Jul 2026 16:08:11 -0600
Subject: [PATCH 5/7] Add easy nav button

---
 .../components/integrations/IntegrationPanel.vue   | 14 +++++++++++---
 1 file changed, 11 insertions(+), 3 deletions(-)

diff --git a/beaker-vue/src/components/integrations/IntegrationPanel.vue b/beaker-vue/src/components/integrations/IntegrationPanel.vue
index ffceb810..2084a13f 100644
--- a/beaker-vue/src/components/integrations/IntegrationPanel.vue
+++ b/beaker-vue/src/components/integrations/IntegrationPanel.vue
@@ -28,6 +28,13 @@
                     padding-top: 0.25rem;
                     width: 100%;
             ">
+                <RouterLink
+                    :to="(route.name == 'integrations' ? `/?session=${sessionId}` : `/integrations?session=${sessionId}`)"
+                >
+                    <Button
+                        :label="(route.name == 'integrations' ? 'Back to session' : 'Manage Integrations') "
+                    />
+                </RouterLink>
                 <span style="flex: 1"></span>
                 <RouterLink
                     :to="`/integrations?selected=new${sessionIdParam}`"
@@ -161,9 +168,10 @@ import Card from "primevue/card";
 import { marked } from "marked";
 import { type BeakerSessionComponentType } from "../session/BeakerSession.vue";
 import { type IntegrationMap, type Integration, type IntegrationProviders, listIntegrations, getIntegrationProviderType, getIntegrationIcon, getIntegrationTypeLabel, isContextProvidedIntegration } from "@/util/integration";
-import { RouterLink } from "vue-router";
+import { useRoute, RouterLink } from "vue-router";
 import { read } from "fs";
 
+const route = useRoute();
 const searchText = ref(undefined);
 
 interface PropTypes {
@@ -218,9 +226,9 @@ const onDrop = (event: DragEvent) => {
 };
 
 const urlParams = new URLSearchParams(window.location.search);
-const sessionIdParam = urlParams.has("session") ? `&session=${urlParams.get("session")}` : "";
+const sessionId = urlParams.get("session") ?? "";
+const sessionIdParam = sessionId ? `&session=${sessionId}` : "";
 
-const beakerSession = inject<BeakerSessionComponentType>("beakerSession");
 
 const sortIntegrations = (integrations: Integration[]) =>
     integrations.toSorted((a, b) => (a?.name ?? '').localeCompare(b?.name ?? ''))

From 676c038e1607ebb21e099a9bdb52a8098137d346 Mon Sep 17 00:00:00 2001
From: Matthew Printz <matt@jataware.com>
Date: Tue, 28 Jul 2026 09:05:38 -0600
Subject: [PATCH 6/7] Fix for upstream issue caused by new version of
 playwright

---
 beaker-vue/tests/tsconfig.json | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/beaker-vue/tests/tsconfig.json b/beaker-vue/tests/tsconfig.json
index f31fe714..82d59584 100644
--- a/beaker-vue/tests/tsconfig.json
+++ b/beaker-vue/tests/tsconfig.json
@@ -1,4 +1,4 @@
 {
-  "extends": "@tsconfig/node22/tsconfig.json",
+  "extends": "../tsconfig.node.json",
   "include": ["./**/*"]
 }

From 8451bf0e7ea7a6725baac5dd331d521ec08bc806 Mon Sep 17 00:00:00 2001
From: Matthew Printz <matt@jataware.com>
Date: Tue, 28 Jul 2026 09:26:50 -0600
Subject: [PATCH 7/7] Limit python mcp package to <2.0.0 due to upstream
 breaking change

---
 pyproject.toml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/pyproject.toml b/pyproject.toml
index 80aab0a5..9cc68e6c 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -37,7 +37,7 @@ dependencies = [
   "python-dotenv~=1.0",
   "hatch",
   "platformdirs",
-  "mcp",
+  "mcp<2.0.0",
   "toml",
   "pyyaml",
   "dill",