Skip to content

Replace Specialist Agent with full Skill editing in the integration editor - #252

Merged
mattprintz merged 8 commits into
devfrom
skill-integration-editor
Jul 28, 2026
Merged

mattprintz merged 8 commits into
devfrom
skill-integration-editor

Conversation

@mattprintz

Copy link
Copy Markdown
Collaborator

Summary

Removes the "Specialist Agent" / AdhocAPI integration from the integration
editor and replaces it with full management of Agent Skills. Skills are now a
mutable integration provider: you can create, edit, and delete local skills,
add remote (URL-based) skills, edit their progressively-disclosed resources,
and import a skill from a SKILL.md file or a .zip. Skills bundled within a
context remain read-only (view mode).

Backend

  • SkillIntegrationProvider is now a MutableBaseIntegrationProvider:
    add/update/remove_integration (local + remote) and
    add/update/remove_resource for local skills, with SKILL.md
    (frontmatter + body) serialization and file writes under reference/script/
    asset (singular and plural) and examples.
  • Deterministic integration uuids (agent-skill:<corpus>:<slug>); context
    skills namespaced under context-<slug> so the UI renders them read-only.
  • Local file-resource discovery scans on-disk resource dirs; body-reference
    extraction is used only for remote skills and normalizes ./ prefixes
    (fixes phantom/duplicate resources).
  • add_integration(preview=True, ...) builds an unsaved skill from a URL or
    raw SKILL.md content so the editor can prefill before saving.
  • Write-location resolution (first existing-writable, else first creatable)
    across the skill search roots; remote skills persisted as skills.json
    entries. Path-containment guards on all resource writes.
  • New DELETE /beaker/integrations/{session}/{id} → remove_integration.
  • System-preamble refresh is now lazy: an integration mutation marks it dirty
    and it rebuilds at the next agent turn — no session restart.

Frontend

  • New SkillIntegrationEditor.vue (source type/URL, name, description, metadata
    incl. allowed-tools chips, instructions body) and editable
    SkillResourcePanel.vue (add/edit/delete file & example resources; shows
    pending-import resources).
  • agent-skill uses the MCP-style viewer/editor split; Specialist Agent removed
    from the New-Integration menu and dispatch.
  • Import: skillArchive.ts unzips in the browser (fflate), locates
    SKILL.md (root or one dir deep, fails on >1), enumerates valid resource
    files, skips non-text with a surfaced count. Upload button + panel-wide drop
    target.
  • Delete button; Save is always present for editable skills (disabled until
    dirty). Left-panel Edit/View label now correct for skills.
  • Layout fix: header and action bar stay pinned; only the content between them
    scrolls (also fixes the same issue for MCP).

Docs & tests

  • Updated concept_integrations.md, integration_providers.md,
    integrations_api.md (incl. correcting pre-existing remove_resource /
    display_name / package-path inaccuracies).
  • Backend tests/integrations/skills/test_skill_mutation.py (+ extraction
    tests); frontend src/util/__tests__/skillArchive.spec.ts.

Behavior notes

  • Remote skills: source type + URL are the only editable fields; fetched content
    is read-only. Source type is fixed after creation (delete + recreate to
    change). Binary resource content is not yet supported (text-only).

Follow-ups (out of scope)

  • Remove the adhoc backend provider + adhoc_api dependency (UI-only removal
    here). Existing adhoc integrations now render a blank editor — deprecated and
    believed unused.
  • Hard backend read-only guard for context-bundled integrations (tracked
    separately); currently enforced frontend-only, matching MCP.
  • Binary resource support (base64 content_encoding marker); remote name/slug
    override (needs skills.json object-entry parsing).

Testing

  • Backend: hatch run pytest tests/ — full suite green (skills suite: 99).
  • Frontend: vitest run green; vue-tsc --build 0 errors.

- 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
Resolves three conflicts in the skill provider, all where dev's
remote-example discovery met this branch's plural-directory support:

- extract_file_references: keep the "./" normalization and the
  constant-driven directory lists, adopt dev's behavior of emitting
  examples/ paths for the caller to route, and generalize the
  bare-directory drop to every recognized example dir spelling.
- _build_skill_integration: keep the _discover_file_resources /
  _discover_examples split, and do dev's single-pass example/file
  routing in the caller so _discover_examples still receives its
  `referenced` paths.
- _discover_examples: keep the scan over every example dir spelling,
  plus dev's `seen` bookkeeping and referenced-path pass.

dev's EXAMPLES_DIR constant is replaced by EXAMPLE_DIR_PREFIXES and a
strip_example_dir() helper so the singular "example/" spelling routes
and strips the same as "examples/".
@mattprintz
mattprintz merged commit d7d0f30 into dev Jul 28, 2026
4 checks passed
@mattprintz
mattprintz deleted the skill-integration-editor branch July 28, 2026 15:41
mattprintz pushed a commit that referenced this pull request Aug 25, 2026
…el (#261)

* Render skill markdown and make resource lists clickable

Skill resources previously displayed as raw markdown in a read-only code
editor, and the resource/example lists in the read-only skill viewer were
inert.

- SkillResourcePanel: markdown resources open in a rendered view; editable
  resources get an Edit/Preview toggle, read-only ones are rendered only.
  Non-markdown resources keep the code editor.
- SkillIntegrationViewer: show the SKILL.md instructions (rendered), and
  make Available Resources / Code Examples items clickable, opening the
  resource focused in the right-side panel.
- IntegrationsInterface: wire the open-resource event to the right panel
  via its exposed focusResource().

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KxxsV6UyDEGTBGsMP4jeLy

* Generate routes.json during make init UI build

The html build target ran only build-ui, skipping the routes step, so a
dev server built via make init had no routes.json and 404'd every page
route (/notebook, /integrations, ...).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KxxsV6UyDEGTBGsMP4jeLy

* Make the skill editor read-first

Editable skills (e.g. from the global ~/.beaker/skills root) opened
straight into a raw SKILL.md code editor with no way to browse the
skill's resources from the center pane.

- Instructions default to a rendered markdown preview with an
  Edit/Preview toggle; new or empty skills start in the editor.
- Add the clickable Available Resources / Code Examples lists (as in the
  read-only viewer), opening the resource rendered in the right panel.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KxxsV6UyDEGTBGsMP4jeLy

* Fix markdown overflow and make relative skill links open in the drawer

Long unbreakable lines in rendered code blocks propagated their intrinsic
width up through the fieldset flex items (min-width: auto), stretching the
center pane sideways. Let fieldsets shrink (min-width: 0) and constrain
pre/table/img inside rendered markdown to scroll within their own box.

Relative links between a skill's markdown files (references/REST-API.md,
../references/X.md, examples/Y.md) navigated the app to a 404. Intercept
clicks on relative hrefs in rendered markdown, resolve them against the
linking file's directory, and open the matching resource in the resource
panel; unresolvable relative links become no-ops and external links are
untouched.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KxxsV6UyDEGTBGsMP4jeLy

* Clamp rendered skill instructions to a preview by default

A full SKILL.md runs to thousands of pixels and buried the Available
Resources / Code Examples sections below it. Extract a ClampedMarkdown
component that caps rendered markdown at a preview height with a fade-out
and a Show more/Show less toggle, shown only when the content actually
overflows; use it for the instructions in both the skill editor and the
read-only viewer. Relative-link interception passes through unchanged.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KxxsV6UyDEGTBGsMP4jeLy

* Sanitize rendered markdown, drop dead components, test link resolution

- Rendered integration markdown (skill instructions, resource files, MCP
  descriptions) went into v-html unsanitized; skills can arrive from
  remote URLs and uploads, so route all integration marked.parse calls
  through renderMarkdown(), which sanitizes with DOMPurify. Lives in
  util/markdown.ts alongside the existing marked/KaTeX setup.
- Delete ResourceViewer and ExamplesPanel: unreferenced since the skill
  editor rework (#252), and ResourceViewer still carried debug logging.
- Unit-test isRelativeHref/resolveResourceFromHref (.., ./, fragments,
  query strings, externals) and renderMarkdown's sanitization.
- Show empty custom-metadata values as blank instead of "null".

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KxxsV6UyDEGTBGsMP4jeLy

* Fix data-loss races and duplication found in review

Correctness (from adversarial review of the branch):
- openResource: guard against stale fetch responses (a slow load for
  resource A no longer lands in — or gets saved over — resource B), track
  load failures visibly, and disable Save while content is loading or
  failed so a blank draft can't overwrite the file on disk.
- Confirm before discarding an unsaved draft when navigation (row click,
  rendered link, center viewer, Back) opens another resource.
- Only treat .md/.markdown files as markdown (a .csv/.txt no longer
  renders garbled through marked), and offer the Raw/Preview toggle on
  read-only markdown too, so the exact content the agent receives is
  always viewable.
- Resolve relative links with a skill-root fallback (examples/ files use
  root-relative paths) and percent-decode hrefs before matching.
- Don't yank the user out of the raw instructions editor when a resource
  refresh re-syncs state; flip to preview only when instructions first
  arrive into an empty editor.
- ClampedMarkdown re-measures overflow on element resize and captured
  image loads, so late reflow can't clip content below an unreachable
  fold.
- IntegrationPanel: render+sanitize descriptions in a cached computed
  instead of inline in the v-for (was re-sanitizing every card on every
  hover change and keystroke).

Structure:
- Deduplicate the relative-link click handling into
  resourceFromLinkClick() (was copy-pasted three times).
- Extract the Available Resources / Code Examples fieldsets into
  SkillResourceLinks (was duplicated between viewer and editor).
- Move the shared .skill-description prose styles into index.scss;
  components no longer depend on another component's style block.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KxxsV6UyDEGTBGsMP4jeLy

---------

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant