Admin — Skills Catalog

The Skills Catalog is where skill packs are browsed, installed, uploaded, and authored. Skills are the reusable capability bundles that agents inherit — a skill can add tool definitions, background knowledge, or behavior instructions, and any agent that’s been assigned the skill inherits it at invocation time.

Two sources feed the catalog:

• Public catalog — skills published by the ThinkWork project and community, backed by the public skill catalog S3 bucket; read-only from the tenant’s perspective
• Tenant-owned skills — skills the tenant has installed from the public catalog (catalog-installed), uploaded as a ZIP/folder (tenant-uploaded), or authored from scratch in the builder (tenant-created)

The list view

Route: /skills
File: apps/admin/src/routes/_authed/_tenant/skills/index.tsx

The list is a unified DataTable with tabbed filtering: All, Installed, Custom, and Catalog. Each row shows:

• Name
• Description
• Category
• Version (with an upgrade badge if a newer version is available in the catalog)
• Type — built-in, catalog-installed, tenant-uploaded, or tenant-created
• Status — enabled / active

The “Upload Skill” button opens a dialog with a drag-drop file zone. The dialog accepts ZIPs (extracted via JSZip), YAML, Markdown, and Python files. For ZIP uploads, it parses the SKILL.md frontmatter to auto-fill the skill’s name and description.

Clicking a row navigates to the skill detail view.

Underlying API

The list is REST-driven, not GraphQL:

Endpoint	Purpose
GET /api/skills/catalog	Read the public catalog
GET /api/skills/tenant	Read tenant-installed and tenant-created skills
POST /api/skills/tenant/:slug/install	Install a skill from the catalog
POST /api/skills/tenant/create	Create a new tenant-owned skill
POST /api/skills/tenant/:slug/files/:path	Write a file into a tenant skill
GET /api/skills/tenant/:slug/upgradeable	Check if a newer catalog version is available

Every tenant-scoped request carries x-tenant-slug in the header.

The upgrade badge

When an operator views Installed skills, the list calls checkUpgradeable() in batch against the catalog. For each installed skill, the endpoint checks whether a newer version exists and returns a flag. If true, the row shows an “Update” badge; clicking through to detail offers an explicit upgrade action.

The skill detail view

Route: /skills/:slug
File: apps/admin/src/routes/_authed/_tenant/skills/$slug.tsx

The detail view is a full file-tree browser plus editor, sized for real skill authoring work:

• Header — skill name, description, action buttons (Install / Uninstall / Upgrade depending on state)
• Metadata badges — Built-in / Catalog / Custom, Category, Version, Tags, Read-only where applicable
• Dependencies — if the skill declares dependencies, they render as clickable badges showing which are installed vs missing
• File tree — collapsible folder structure on the left, built from listCatalogFiles() or listTenantSkillFiles()
• Editor pane — on the right, a CodeMirror editor (markdown, Python, and YAML syntax support) or a ReactMarkdown preview for .md files
• Toolbar — file name, Preview / Raw toggle for markdown, Delete button (custom skills only), Save / Discard (editable files only)

Built-in and catalog-installed skills are read-only in the editor. Only tenant-created or tenant-uploaded skills are editable; trying to type in a built-in skill’s editor is a no-op.

Files and destructive actions

For tenant-owned skills, operators can:

• Edit a file — type, click Save, PUT to /api/skills/tenant/:slug/files/:path
• Add a new file — click ”+ Add”, type a path, hit Enter, POST to the same endpoint
• Delete a file — click the trash icon next to the file in the tree, confirm, DELETE

Destructive actions (uninstall, delete file, upgrade) use alert dialogs and do not have undo.

The skill builder

Route: /skills/builder
File: apps/admin/src/routes/_authed/_tenant/skills/builder.tsx

The builder is a guided wizard for creating tenant-owned custom skills from scratch. Four steps:

1. Template picker — four cards: Script Tool, Knowledge, Process, Blank
2. Metadata form — name, description, category, tags. The slug is derived from the name.
3. Content editor — CodeMirror in markdown mode editing the generated SKILL.md template. Templates use {{name}}, {{slug}}, {{slug_underscore}}, and {{description}} substitutions that are pre-filled from step 2.
4. Review — confirmation card showing name, slug, template, category, approximate line count, and any extra files the template will also create (e.g. the Script Tool template adds a scripts/tool.py stub with a TODO comment)

Submitting fires createTenantSkill() (creates the skill row), then iteratively PUTs each template file. On success, the builder navigates to /skills/:slug so the operator can immediately start editing.

Note

The builder is deliberately small. Serious skill authoring — multi-file packs, tests, dependency management — should happen in your editor of choice and land via ZIP upload or the Authoring Guide: Skill Packs. The builder is for quick prototypes and single-file skills.

Distinction: workspace skills vs the Skills Catalog

• Skills Catalog (this page) — browse, install, and author skills at the tenant level. Skills here exist whether or not any agent uses them.
• Agent or template Workspace tab — materialize an editable skill under workspace/skills/<slug>/SKILL.md so it can affect a real invocation. See Agents → Workspace.

A workspace skill goes through two steps before it affects a real invocation: install or author it at the tenant/catalog level, then add it to an agent or template workspace.

Built-in tools do not follow this path. Tools such as web_search and send_email are injected by runtime configuration and should not be copied into workspace/skills/.

Known limits

• Python skill builder is lightly tested. The Script Tool template produces a valid stub but the actual iteration loop (edit → test → deploy) is better handled in a real development environment and uploaded as a ZIP.
• Dependency resolution is read-only. The detail page shows which dependencies are installed vs missing, but there’s no auto-install button.
• No archival. Deleted skills are hard-deleted. There’s no undo.
• Upgrade can force-overwrite customizations. If a tenant has customized a catalog-installed skill, running upgrade with force=true overwrites the customizations. The UI warns before this happens but relies on the operator confirming.

Related pages

• Agents — where agent workspaces and workspace skills are managed
• Authoring Guide: Skill Packs — the authoring reference for serious skill development
• Tenant MCP Servers — the other path for exposing external capabilities to agents
• Built-in Tools — platform-owned tools that are injected by runtime configuration instead of installed as skill packs