Inspect and Import Skill Packages

Precheck a local skill .zip archive to inspect its manifest metadata, content digest, and validation warnings, then import the package into your workspace and record the created skill ID and version.

Task flow

Read local skill ZIP archive bytes
                │
                ▼
Inspect package name, digest, and warnings
                │
                ▼
Import package and save skill ID and version

Prerequisites

  1. Complete the endpoint, personal access token, and workspace setup in Use the SDK.

  2. Prepare a local skill .zip archive (provided by the skill author or packaged from a skill directory containing SKILL.md), and export its path:

export SKILL_ARCHIVE='./skill-package.zip'

Inspect a skill package

Call inspect_skill_package (InspectSkillPackage in Go) to run a read-only precheck on the .zip archive and print the skill name, archive_digest, and any validation warnings without creating a workspace resource.

import os
from pathlib import Path

import moi_product_sdk as sdk

client = sdk.new_with_personal_access_token(
    os.environ["PRODUCT_API_BASE_URL"],
    os.environ["PRODUCT_API_KEY"],
)
service = client.workspace(os.environ["WORKSPACE_ID"]).agents()
archive = Path(os.environ["SKILL_ARCHIVE"])
data = archive.read_bytes()

inspection = service.inspect_skill_package(archive.name, data)
print("Skill name:", inspection.get("name"))
print("Archive digest:", inspection.get("archive_digest"))
print("Warnings:", inspection.get("warnings"))
package main

import (
	"bytes"
	"context"
	"fmt"
	"log"
	"os"
	"path/filepath"

	sdk "github.com/matrixorigin/matrixflow/sdk/go-sdk"
)

func main() {
	ctx := context.Background()
	client, err := sdk.NewWithPersonalAccessToken(
		os.Getenv("PRODUCT_API_BASE_URL"),
		os.Getenv("PRODUCT_API_KEY"),
	)
	if err != nil {
		log.Fatal(err)
	}
	defer client.Close()

	workspace, err := client.Workspace(os.Getenv("WORKSPACE_ID"))
	if err != nil {
		log.Fatal(err)
	}
	archivePath := os.Getenv("SKILL_ARCHIVE")
	data, err := os.ReadFile(archivePath)
	if err != nil {
		log.Fatal(err)
	}

	service := workspace.Agents()
	inspection, err := service.InspectSkillPackage(ctx, filepath.Base(archivePath), bytes.NewReader(data))
	if err != nil {
		log.Fatal(err)
	}
	values, ok := inspection.AsMap()
	if !ok {
		log.Fatal("expected an object response from InspectSkillPackage")
	}
	fmt.Println("Skill name:", values["name"])
	fmt.Println("Archive digest:", values["archive_digest"])
	fmt.Println("Warnings:", values["warnings"])
}

Import the skill package

After reviewing the skill name, digest, and warnings, continue with service and the archive bytes to call import_skill_package (ImportSkillPackage in Go), then record the returned skill id, name, and version:

result = service.import_skill_package(archive.name, data)
skill = result.get("skill") or {}
print("Skill ID:", skill.get("id"))
print("Name:", skill.get("name"), "Version:", skill.get("version"))
imported, err := service.ImportSkillPackage(ctx, filepath.Base(archivePath), bytes.NewReader(data))
if err != nil {
	log.Fatal(err)
}
result, ok := imported.AsMap()
if !ok {
	log.Fatal("expected an object response from ImportSkillPackage")
}
skill, ok := result["skill"].(map[string]any)
if !ok {
	log.Fatal("import response missing skill object")
}
fmt.Println("Skill ID:", skill["id"])
fmt.Println("Name:", skill["name"], "Version:", skill["version"])

Once imported, you can bind the skill to an agent in the console or attach it per invocation request.

Next steps

Last updated on