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

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 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. 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:

# 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 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.

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:

# 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 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:

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. When a skill manifest contains variable declarations, the Env Var Settings UI—managed via 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:

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, 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:

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 provides the central interface for catalog browsing, bundle upload, sandbox targeting, and environment variable management.
• Skill Catalog API – 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 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 contains the SkillEnvVar declaration and encryption routines for secure variable storage.
• Router Definitions – internal/router/router_api_key_capabilities_test.go maps HTTP routes to skill-related handler functions.
• UI Utilities – frontend/src/utils/skillToolDisplay.ts and 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 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 manifest at the root, optional executable scripts, and any resource files referenced by the manifest. The skill.json must declare the skill ID, version, and optional SkillEnvVar definitions. The upload handler in 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. 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}