# How to Create and Manage Agent Skills in WeKnora: A Complete Developer Guide

> Learn how to create and manage agent skills in WeKnora. Discover reusable skill bundles, REST endpoints, UI management, and sandbox integration for your developer projects.

- Repository: [Tencent/WeKnora](https://github.com/tencent/WeKnora)
- Tags: how-to-guide
- Published: 2026-09-13

---

**WeKnora treats agent skills as reusable, sandbox-portable bundles that you register via REST endpoints or the Skill Settings UI, install into Docker/Cube/E2B sandboxes, and manage through snapshot-based lifecycle tracking.**

WeKnora is an open-source platform developed by Tencent for deploying AI agents within isolated sandbox environments. Understanding how to create and manage agent skills in WeKnora is essential for extending agent capabilities with custom tools and integrations. This guide examines the complete skill lifecycle—from packaging the bundle to monitoring real-time installation status—based on the actual source code implementation in the `Tencent/WeKnora` repository.

## What Are Agent Skills in WeKnora?

In the WeKnora architecture, a **skill** is a reusable agent component distributed as a zipped bundle. Each bundle must contain a [`skill.json`](https://github.com/Tencent/WeKnora/blob/main/skill.json) manifest file, optional executable scripts, and any required resource files. The platform treats skills as first-class entities that can be installed into one or more sandbox configurations, including Docker, Cube, and E2B environments.

The skill system decouples tool definition from runtime execution. Once registered in the tenant-specific catalog, a skill can be instantiated across multiple sandboxes while maintaining isolated configuration states and encrypted environment variables.

## Registering a New Skill

Before installation, you must register the skill bundle in the tenant catalog. The platform stores bundle metadata in the `TenantSkillCatalogEntity` struct defined in [`internal/types/tenant_skill.go`](https://github.com/Tencent/WeKnora/blob/main/internal/types/tenant_skill.go). You can register skills through the **Skill Settings** UI or programmatically via the REST API.

The registration endpoint accepts a multipart upload of the zip file:

```bash

# Build a zip containing skill.json + scripts

zip -r my-skill.zip skill.json scripts/

# POST the bundle to the catalog endpoint

curl -X POST https://<weknora-host>/api/v1/skills/catalog \
     -H "Authorization: Bearer <token>" \
     -F "file=@my-skill.zip"

```

Upon successful upload, the handler in [`internal/handler/skill_catalog.go`](https://github.com/Tencent/WeKnora/blob/main/internal/handler/skill_catalog.go) extracts the manifest, validates the bundle structure, and persists the record to the tenant-skill-catalog table. The skill then appears in the catalog browser within [`frontend/src/views/settings/SkillSettings.vue`](https://github.com/Tencent/WeKnora/blob/main/frontend/src/views/settings/SkillSettings.vue).

## Installing Skills into Sandboxes

Once registered, install a skill into a specific sandbox configuration using the installation endpoint. This operation creates two persistent records: a `TenantSkillEntity` linking the skill to the sandbox config, and a `TenantSkillSnapshotEntity` tracking the specific image version and installation status.

The snapshot entity maintains status constants including `installing`, `ready`, `failed`, and `removing`, enabling reliable state recovery during asynchronous installation workflows.

Install a skill using the sandbox-specific endpoint:

```bash

# Obtain sandbox ID (e.g. from GET /api/v1/sandbox-configs)

SANDBOX_ID=abc123
SKILL_ID=my-skill

curl -X POST "https://<weknora-host>/api/v1/sandbox-configs/${SANDBOX_ID}/skills/${SKILL_ID}/install" \
     -H "Authorization: Bearer <token>"

```

The [`internal/handler/skill_catalog.go`](https://github.com/Tencent/WeKnora/blob/main/internal/handler/skill_catalog.go) file implements this handler, which orchestrates the image build process and emits progress events consumed by the frontend.

### Monitoring Installation Progress

Real-time installation feedback streams through the `install-events` endpoint. The frontend subscribes to `GET /api/v1/sandbox-configs/:id/skills/:skillId/install-events` to update the UI chip status icon (`installChipStatusIcon`) and display per-sandbox progress indicators.

Monitor installation programmatically using the chat stream handler:

```typescript
import { useChatStreamHandler } from '@/composables/useChatStreamHandler.ts';

// The handler parses incoming tool events and updates the UI chip status automatically
useChatStreamHandler(sessionId, (event) => {
  if (event.tool_name === 'execute_skill_script') {
    // Update install progress UI based on event payload
  }
});

```

This event-driven approach ensures users receive immediate feedback during lengthy image builds or dependency installations without polling the REST API.

## Configuring Environment Variables

Skills may declare required environment variables using the `SkillEnvVar` type defined in [`internal/types/tenant_env_vars.go`](https://github.com/Tencent/WeKnora/blob/main/internal/types/tenant_env_vars.go). When a skill manifest contains variable declarations, the **Env Var Settings** UI—managed via [`envVarState.ts`](https://github.com/Tencent/WeKnora/blob/main/envVarState.ts)—renders dynamic input forms for each sandbox instance.

Variable values are encrypted and stored in the `Envs` column of the associated `TenantSkillEntity`, ensuring sensitive credentials remain secure across the distributed system.

Check for declared environment variables before rendering configuration UI:

```typescript
import { skillHasDeclaredEnvs } from '@/views/settings/envVarState.ts';

// Verify the skill declares env vars before showing the edit form
if (skillHasDeclaredEnvs(selectedSkill)) {
  // Persist values via POST /api/v1/sandbox-configs/:id/skills/:skillId/envs
}

```

The encryption logic resides in [`internal/types/tenant_env_vars.go`](https://github.com/Tencent/WeKnora/blob/main/internal/types/tenant_env_vars.go), which handles the `SkillEnvVars` type and serialization before database persistence.

## Uninstalling and Reinstalling Skills

Removing a skill from a sandbox triggers a cleanup workflow that ensures complete image removal. The deletion endpoint creates a `SkillStatusRemoving` snapshot entry, signaling the reaper process to garbage collect the underlying container image.

Uninstall a skill using the DELETE method:

```bash
curl -X DELETE "https://<weknora-host>/api/v1/sandbox-configs/${SANDBOX_ID}/skills/${SKILL_ID}" \
     -H "Authorization: Bearer <token>"

```

Re-installation follows the same POST flow as initial installation, optionally accepting an updated installer model. This design supports version upgrades and configuration changes without orphaning previous snapshots.

## Key Architecture Components

The WeKnora skill system spans multiple layers of the stack, from Vue.js frontend components to Go backend handlers:

- **Skill Settings UI** – [`frontend/src/views/settings/SkillSettings.vue`](https://github.com/Tencent/WeKnora/blob/main/frontend/src/views/settings/SkillSettings.vue) provides the central interface for catalog browsing, bundle upload, sandbox targeting, and environment variable management.
- **Skill Catalog API** – [`internal/handler/skill_catalog.go`](https://github.com/Tencent/WeKnora/blob/main/internal/handler/skill_catalog.go) implements the REST surface for listing, registering, downloading, and deleting skill bundles.
- **Tenant Skill Models** – [`internal/types/tenant_skill.go`](https://github.com/Tencent/WeKnora/blob/main/internal/types/tenant_skill.go) defines the GORM entities `TenantSkillEntity`, `TenantSkillSnapshotEntity`, and `TenantSkillCatalogEntity`, along with status constants and snapshot lifecycle logic.
- **Env-Var Handling** – [`internal/types/tenant_env_vars.go`](https://github.com/Tencent/WeKnora/blob/main/internal/types/tenant_env_vars.go) contains the `SkillEnvVar` declaration and encryption routines for secure variable storage.
- **Router Definitions** – [`internal/router/router_api_key_capabilities_test.go`](https://github.com/Tencent/WeKnora/blob/main/internal/router/router_api_key_capabilities_test.go) maps HTTP routes to skill-related handler functions.
- **UI Utilities** – [`frontend/src/utils/skillToolDisplay.ts`](https://github.com/Tencent/WeKnora/blob/main/frontend/src/utils/skillToolDisplay.ts) and [`frontend/src/utils/skillArtifacts.ts`](https://github.com/Tencent/WeKnora/blob/main/frontend/src/utils/skillArtifacts.ts) render skill file titles, detect `execute_skill_script` tool calls, and expose skill-generated artifacts in the chat interface.

## Summary

- **Skills are zipped bundles** containing a [`skill.json`](https://github.com/Tencent/WeKnora/blob/main/skill.json) manifest, scripts, and resources, registered via `/api/v1/skills/catalog` and stored in `TenantSkillCatalogEntity`.
- **Installation creates linked records** in `TenantSkillEntity` and `TenantSkillSnapshotEntity`, tracking status across states like `installing`, `ready`, and `failed`.
- **Environment variables** declared as `SkillEnvVar` are encrypted and stored in the `Envs` column, configurable through the dedicated settings UI.
- **Real-time monitoring** streams via the `install-events` endpoint, consumed by frontend utilities like `useChatStreamHandler` for live progress updates.
- **Uninstallation** creates a `SkillStatusRemoving` snapshot and triggers background cleanup, while re-installation supports version upgrades through the standard POST flow.

## Frequently Asked Questions

### What file structure is required for a WeKnora skill bundle?

A valid skill bundle is a zip file containing a [`skill.json`](https://github.com/Tencent/WeKnora/blob/main/skill.json) manifest at the root, optional executable scripts, and any resource files referenced by the manifest. The [`skill.json`](https://github.com/Tencent/WeKnora/blob/main/skill.json) must declare the skill ID, version, and optional `SkillEnvVar` definitions. The upload handler in [`internal/handler/skill_catalog.go`](https://github.com/Tencent/WeKnora/blob/main/internal/handler/skill_catalog.go) validates this structure before persisting the bundle to the tenant catalog.

### How does WeKnora secure skill environment variables?

Environment variables declared in a skill manifest are stored using the `SkillEnvVar` type defined in [`internal/types/tenant_env_vars.go`](https://github.com/Tencent/WeKnora/blob/main/internal/types/tenant_env_vars.go). When users configure values through the **Env Var Settings** UI, the platform encrypts the data before storing it in the `Envs` column of the `TenantSkillEntity` database record. This ensures credentials and API keys remain encrypted at rest within the tenant's database.

### Can I install the same skill across multiple sandbox configurations?

Yes. The architecture separates the global skill catalog (stored in `TenantSkillCatalogEntity`) from individual sandbox installations (stored in `TenantSkillEntity`). You can install a single registered skill into multiple sandbox configs—such as Docker, Cube, and E2B—each maintaining independent snapshots (`TenantSkillSnapshotEntity`) and environment variable sets. Each installation generates a unique snapshot tracking the image version and deployment status.

### What happens if a skill installation fails?

Failed installations transition the `TenantSkillSnapshotEntity` status to `failed`, which the **Skill Settings** UI surfaces through the `installChipStatusIcon` component. The installation events stream provides detailed error logs via the `install-events` endpoint, allowing users to diagnose build or dependency issues. You can safely retry installation by calling the POST endpoint again, which creates a new snapshot attempt without affecting previous records.