@opencangjie/skills

JavaScript/TypeScript SDK for AgentSkills Runtime - Install, manage, and execute AI agent skills with built-in runtime support.

Features

• Complete Runtime Management: Download, install, start, and stop the AgentSkills runtime
• Skill Management: Install, list, execute, and remove skills
• CLI & Programmatic API: Use via command line or integrate into your applications
• Cross-Platform: Supports Windows, macOS, and Linux

Installation

npm install @opencangjie/skills

Or use directly with npx:

npx @opencangjie/skills find react
npx @opencangjie/skills list
npx @opencangjie/skills add ./my-skill

Quick Start

1. Install the Runtime

# Download and install the AgentSkills runtime
npx skills install-runtime

# Or specify a version
npx skills install-runtime --runtime-version 0.0.16

2. Configure the Runtime

Before starting the runtime, you need to configure the AI model API key. The runtime requires an AI model to process skill execution and natural language understanding.

Edit the .env file in the runtime directory:

• Windows: %USERPROFILE%\.agentskills-runtime\<platform>-<arch>\release\.env
• macOS/Linux: ~/.agentskills-runtime/<platform>-<arch>/release/.env

Where <platform>-<arch> is your system architecture, e.g., win-x64, darwin-x64, or linux-x64

Add your AI model configuration (choose one provider):

# Option 1: StepFun (阶跃星辰)
MODEL_PROVIDER=stepfun
MODEL_NAME=step-1-8k
STEPFUN_API_KEY=your_stepfun_api_key_here
STEPFUN_BASE_URL=https://api.stepfun.com/v1

# Option 2: DeepSeek
MODEL_PROVIDER=deepseek
MODEL_NAME=deepseek-chat
DEEPSEEK_API_KEY=your_deepseek_api_key_here

# Option 3: 华为云 MaaS
MODEL_PROVIDER=maas
MAAS_API_KEY=your_maas_api_key_here
MAAS_BASE_URL=https://api.modelarts-maas.com/v2
MAAS_MODEL_NAME=qwen3-coder-480b-a35b-instruct

# Option 4: Sophnet
MODEL_PROVIDER=sophnet
SOPHNET_API_KEY=your_sophnet_api_key_here
SOPHNET_BASE_URL=https://www.sophnet.com/api/open-apis/v1

Note: Without proper AI model configuration, the runtime will fail to start with an error like "Get env variable XXX_API_KEY error."

3. Start the Runtime

# Start in background (default)
npx skills start

# Start in foreground
npx skills start --foreground

# Custom port and host
npx skills start --port 3000 --host 0.0.0.0

4. Manage Skills

# Find and install skills
npx skills find react
npx skills add ./my-skill

# List installed skills
npx skills list

# Execute a skill
npx skills run my-skill -p '{"input": "data"}'

CLI Commands

Runtime Management

npx skills install-runtime

Download and install the AgentSkills runtime binary.

npx skills install-runtime
npx skills install-runtime --runtime-version 0.0.16

npx skills start

Start the AgentSkills runtime server.

# Start in background (default)
npx skills start

# Start in foreground
npx skills start --foreground

# Custom configuration
npx skills start --port 3000 --host 0.0.0.0

Options:

• -p, --port <port> - Port to listen on (default: 8080)
• -h, --host <host> - Host to bind to (default: 127.0.0.1)
• -f, --foreground - Run in foreground (default: background)

npx skills stop

Stop the AgentSkills runtime server.

npx skills stop

npx skills status

Check the status of the skills runtime server.

npx skills status

Skill Management

npx skills find [query]

Search for skills interactively or by keyword.

npx skills find
npx skills find react testing
npx skills find "pdf generation"
npx skills find skill --source github --limit 10
npx skills find skill --source atomgit --limit 5

Options:

• -l, --limit <number>: Maximum number of results, default 10
• -s, --source <source>: Search source, options: all (default), github, gitee, atomgit

Note: AtomGit search requires setting the ATOMGIT_TOKEN environment variable in the runtime's .env configuration file.

npx skills add <source>

Install a skill from GitHub or local path.

# Install from local directory
npx skills add ./my-skill

# Install from GitHub repository
npx skills add github.com/user/skill-repo
npx skills add github.com/user/skill-repo --branch develop

# Install from multi-skill repository (specify subdirectory)
npx skills add https://github.com/user/skills-repo/tree/main/skills/my-skill
npx skills add https://atomgit.com/user/skills-repo/tree/main/skills/skill-creator

# Install with options
npx skills add github.com/user/skill-repo -y  # Skip confirmation

Tip: For repositories containing multiple skills, use the /tree/<branch>/<skill-path> format to specify the exact subdirectory. This avoids the interactive selection prompt.

npx skills list

List installed skills.

npx skills list
npx skills list --limit 50 --page 1
npx skills list --json

npx skills run <skillId>

Execute a skill.

npx skills run my-skill -p '{"param1": "value"}'
npx skills run my-skill --tool tool-name -p '{"param1": "value"}'
npx skills run my-skill -i  # Interactive mode

npx skills remove <skillId>

Remove an installed skill.

npx skills remove my-skill
npx skills rm my-skill -y

npx skills info <skillId>

Show detailed information about a skill.

npx skills info my-skill

npx skills init [name]

Initialize a new skill project.

npx skills init my-new-skill
npx skills init my-new-skill --directory ./skills

npx skills check

Check for skill updates.

npx skills check

npx skills update [skillId]

Update skills to their latest versions.

npx skills update my-skill
npx skills update --all

npx skills config <skillId>

Manage skill configuration.

npx skills config my-skill --list
npx skills config my-skill --get API_KEY
npx skills config my-skill --set API_KEY=abc123

Programmatic API

Basic Usage

import { createClient, SkillsClient, RuntimeManager } from '@opencangjie/skills';

const client = createClient({
  baseUrl: 'http://127.0.0.1:8080',
  authToken: 'your-jwt-token' // optional
});

// Check runtime status
const status = await client.runtime.status();
console.log(`Runtime running: ${status.running}`);

// List skills
const result = await client.listSkills({ limit: 10 });
console.log(result.skills);

// Execute a skill
const execResult = await client.executeSkill('my-skill', {
  param1: 'value'
});
console.log(execResult.output);

Runtime Management

import { RuntimeManager } from '@opencangjie/skills';

const runtime = new RuntimeManager();

// Check if runtime is installed
if (!runtime.isInstalled()) {
  // Download and install
  await runtime.downloadRuntime('1.0.0');
}

// Check status
const status = await runtime.status();
if (!status.running) {
  // Start the runtime
  runtime.start({
    port: 8080,
    host: '127.0.0.1',
    detached: true
  });
}

// Stop the runtime
runtime.stop();

Skill Management

// Install from local path
const installResult = await client.installSkill({
  source: './my-skill',
  validate: true
});

// Install from Git
const gitInstallResult = await client.installSkill({
  source: 'https://github.com/user/skill.git',
  branch: 'main'
});

// Uninstall
await client.uninstallSkill('my-skill');

// Update
await client.updateSkill('my-skill', { version: '2.0.0' });

Execute Skills

// Execute skill with parameters
const result = await client.executeSkill('my-skill', {
  input: 'data'
});

if (result.success) {
  console.log(result.output);
} else {
  console.error(result.errorMessage);
}

// Execute specific tool
const toolResult = await client.executeSkillTool('my-skill', 'tool-name', {
  param1: 'value'
});

Defining Skills

You can also use this SDK to define skills programmatically:

import { defineSkill, getConfig } from '@opencangjie/skills';

export default defineSkill({
  metadata: {
    name: 'my-skill',
    version: '1.0.0',
    description: 'My awesome skill',
    author: 'Your Name'
  },
  tools: [
    {
      name: 'greet',
      description: 'Greet someone by name',
      parameters: [
        {
          name: 'name',
          paramType: 'string',
          description: 'Name to greet',
          required: true
        }
      ]
    }
  ],
  validateConfig: (config) => {
    if (!config.API_KEY) {
      return { err: 'API_KEY is required' };
    }
    return { ok: null };
  }
});

// Access configuration
const config = getConfig();
const apiKey = config.API_KEY;

Architecture

┌─────────────────────────────────────┐
│        Language Ecosystem           │
│   (npm, pip, maven, cargo, etc.)    │
├─────────────────────────────────────┤
│  CLI Commands (skills find/add/run) │
├─────────────────────────────────────┤
│     SDK Programmatic API            │
│     (SkillsClient, RuntimeManager)  │
├─────────────────────────────────────┤
│   Standard API Interface Layer      │
│     (RESTful + JWT Auth)            │
├─────────────────────────────────────┤
│   Agent Skill Runtime Kernel        │
│     (Cangjie Binary)                │
└─────────────────────────────────────┘

Manual Runtime Installation

If you prefer to manually install the runtime without using the SDK:

Download

Download the latest release from AtomGit:

• agentskills-runtime-win-x64.tar.gz - Windows x64
• agentskills-runtime-linux-x64.tar.gz - Linux x64 (coming soon)
• agentskills-runtime-darwin-x64.tar.gz - macOS x64 (coming soon)

Installation

# Download and extract
tar -xzf agentskills-runtime-win-x64.tar.gz

# Navigate to bin directory
cd release/bin

# Run the runtime
./agentskills-runtime.exe

Release Package Contents

release/
├── bin/                    # Executables and ALL DLLs
│   ├── agentskills-runtime.exe    # Main entry point
│   ├── magic.api.exe              # Alternative entry point
│   └── *.dll                      # All required DLLs (stdx, runtime, magic)
├── magic/                  # Runtime modules
├── commonmark4cj/          # Markdown parser
├── yaml4cj/                # YAML parser
└── VERSION                 # Version information

Usage

After extraction, simply run the executable:

# Windows
cd release/bin
agentskills-runtime.exe

# The server will start on http://127.0.0.1:8080

API Endpoints

| Endpoint | Method | Description | |----------|--------|-------------| | /hello | GET | Health check | | /skills | GET | List all skills | | /skills/:id | GET | Get skill details | | /skills/add | POST | Install a skill | | /skills/edit | POST | Update a skill | | /skills/del | POST | Uninstall a skill | | /skills/execute | POST | Execute a skill | | /skills/search | POST | Search skills | | /mcp/stream | GET | MCP server with streaming |

Verify Installation

# Check health
curl http://127.0.0.1:8080/hello
# Response: {"message":"Hello World"}

# List skills
curl http://127.0.0.1:8080/skills

Environment Variables

Runtime Configuration

The runtime loads environment variables from a .env file in the same directory as the executable.

Location: Place the .env file in the bin/ directory alongside agentskills-runtime.exe:

sdk/javascript/runtime/win-x64/release/bin/.env

Example .env file:

# GitHub Personal Access Token (optional, for higher rate limits)
GITHUB_TOKEN=ghp_your_github_token

# Gitee Private Token (optional, for higher rate limits)
GITEE_TOKEN=your_gitee_token

# AtomGit Access Token (optional, for higher rate limits)
ATOMGIT_TOKEN=your_atomgit_token

How to obtain tokens:

| Platform | How to Get Token | Auth Method | |----------|------------------|-------------| | GitHub | Settings → Tokens | Authorization: token header | | Gitee | 设置 → 私人令牌 | access_token URL parameter | | AtomGit | 设置 → 访问令牌 | access_token URL parameter |

Note: API tokens are optional. Without tokens, search still works but with lower rate limits:

• GitHub: 10 requests/min (unauthenticated) vs 30 requests/min (authenticated)
• Gitee/AtomGit: Limited without token, higher with token

SDK Environment Variables

| Variable | Description | Default | |----------|-------------|---------| | SKILL_RUNTIME_API_URL | API server URL | http://127.0.0.1:8080 | | SKILL_* | Skill configuration (accessible via getConfig()) | - |

API Reference

SkillsClient

| Method | Description | |--------|-------------| | runtime | Access RuntimeManager instance | | healthCheck() | Check server status | | listSkills(options) | List installed skills | | getSkill(skillId) | Get skill details | | installSkill(options) | Install a skill | | uninstallSkill(skillId) | Uninstall a skill | | executeSkill(skillId, params) | Execute a skill | | executeSkillTool(skillId, toolName, args) | Execute a specific tool | | searchSkills(options) | Search for skills (supports query, source, limit) | | updateSkill(skillId, updates) | Update a skill | | getSkillConfig(skillId) | Get skill configuration | | setSkillConfig(skillId, config) | Set skill configuration | | listSkillTools(skillId) | List tools in a skill |

RuntimeManager

| Method | Description | |--------|-------------| | isInstalled() | Check if runtime is installed | | getRuntimePath() | Get runtime binary path | | downloadRuntime(version) | Download and install runtime | | start(options) | Start the runtime server | | stop() | Stop the runtime server | | status() | Check runtime status |

Comparison with Vercel Labs Skills CLI

| Feature | @opencangjie/skills | Vercel Labs Skills CLI | |---------|---------------------|------------------------| | Runtime Management | Built-in | External | | Installation | npm install | npm install -g skills | | Language | TypeScript/JavaScript | TypeScript | | Runtime | Cangjie (native) | Node.js | | Platform Support | Win/Mac/Linux | Win/Mac/Linux | | API Protocol | RESTful + MCP | RESTful |

Real-World Usage Example

This SDK is used in the UCToo open source project for AI agent skill management.

Project Structure

uctoo/
├── apps/
│   ├── backend/                    # Backend API service (Node.js/TypeScript)
│   │   ├── package.json            # Contains: @opencangjie/skills
│   │   └── src/
│   │       └── app/services/uctoo/
│   │           └── runtimeManager.ts  # Runtime management service
│   │
│   ├── uctoo-app-client-pc/        # Frontend application (Vue 3)
│   │   ├── package.json            # Contains: @opencangjie/skills
│   │   └── src/
│   │       └── views/uctoo/agent_skills/
│   │           └── home.vue        # Skill management UI
│   │
│   └── agentskills-runtime/        # Runtime kernel (Cangjie)
│       └── sdk/javascript/         # This SDK

Backend Integration (apps/backend)

// apps/backend/src/app/services/uctoo/runtimeManager.ts
import { createClient, RUNTIME_VERSION } from '@opencangjie/skills';

const runtimeClient = createClient({
  baseUrl: process.env.SKILL_RUNTIME_API_URL || 'http://127.0.0.1:8080'
});

export class RuntimeManager {
  async getRuntimeVersion(): Promise<string> {
    return RUNTIME_VERSION;
  }

  async listSkills(limit: number = 10, page: number = 0) {
    return runtimeClient.listSkills({ limit, skip: page * limit });
  }

  async installSkill(source: string) {
    return runtimeClient.installSkill({ source });
  }

  async executeSkill(skillId: string, params: Record<string, any>) {
    return runtimeClient.executeSkill(skillId, params);
  }

  async searchSkills(query: string) {
    return runtimeClient.searchSkills({ query });
  }
}

Frontend Integration (apps/uctoo-app-client-pc)

<!-- apps/uctoo-app-client-pc/src/views/uctoo/agent_skills/home.vue -->
<template>
  <div class="skill-management">
    <a-input-search
      v-model:value="searchQuery"
      placeholder="Search skills..."
      @search="handleSearch"
    />
    
    <a-table :dataSource="skills" :columns="columns">
      <template #bodyCell="{ column, record }">
        <template v-if="column.key === 'action'">
          <a-button @click="executeSkill(record.id)">Execute</a-button>
        </template>
      </template>
    </a-table>
  </div>
</template>

<script setup lang="ts">
import { ref, onMounted } from 'vue';
import { createClient } from '@opencangjie/skills';

const client = createClient({
  baseUrl: '/api/skills'  // Proxied to runtime
});

const skills = ref([]);
const searchQuery = ref('');

const loadSkills = async () => {
  const result = await client.listSkills({ limit: 20 });
  skills.value = result.skills;
};

const handleSearch = async () => {
  if (searchQuery.value) {
    const result = await client.searchSkills({ query: searchQuery.value });
    skills.value = result.skills;
  } else {
    loadSkills();
  }
};

const executeSkill = async (skillId: string) => {
  // Open execution dialog
};

onMounted(loadSkills);
</script>

Package Dependencies

// apps/backend/package.json
{
  "dependencies": {
    "@opencangjie/skills": "^0.0.16"
  }
}

// apps/uctoo-app-client-pc/package.json
{
  "dependencies": {
    "@opencangjie/skills": "^0.0.16"
  }
}

Links

• NPM Package
• Documentation
• Repository
• Issue Tracker
• Python SDK

License

MIT