Skip to content
BranchesTags

Repository files navigation

AgentSkills Runtime

License Version Cangjie

Project Introduction

AgentSkills Runtime is a runtime environment for the Agent Skills standard implemented based on the Cangjie programming language. It is a domestic technology stack implementation of the AgentSkills open standard, providing a secure and efficient AI agent skill execution environment. It aims to enable AgentSkills to run anywhere. Open source project address: https://atomgit.com/uctoo/agentskills-runtime

Product Screenshots

AI Builder Task Management Developer Requirement Docking
AI Builder Tasks
Organization Management Token Usage Dashboard
Organization Token Dashboard
Investment Research Assistant Demo
Investment Research Assistant Demo

PC Desktop Client — Fastest Way to Get Started

For most users who just want to run AgentSkills Runtime, the fastest path is to install the PC desktop client — no need to clone the source, set up the Cangjie toolchain, or configure a database. The desktop app bundles the Cangjie-language runtime kernel, an embedded PostgreSQL, and the web-admin management frontend into a single install-and-run experience.

  • Repository: https://atomgit.com/UCToo/agentskills-runtime-pc
  • Tech stack: Electron 42 + Vue 3 + Vite 8
  • Version: 0.1.0 · App ID: com.uctoo.agentskills-runtime-pc · Product name: AgentSkills Runtime
  • What it does: on first launch it auto-extracts the runtime, initializes PostgreSQL, generates the .env config, then brings up the PostgreSQL → runtime → web-admin service chain and lands you on the AI Builder homepage
  • Extras: registers the agentskills:// custom protocol, supports auto-launch on boot, system tray, and auto-update via electron-updater

Steps:

  1. Go to the releases page and download the installer for your platform: https://atomgit.com/UCToo/agentskills-runtime-pc/releases
  2. Windows users: double-click AgentSkills Runtime-Windows-<version>-Installer.exe to run the standard setup wizard, or download the ...-Portable.exe no-install portable edition
  3. macOS users: download AgentSkills Runtime-Mac-<version>-Installer.dmg
  4. Linux users: download AgentSkills Runtime-Linux-<version>.AppImage
  5. After installation, launch the app. The first run auto-completes environment initialization, after which you'll land on the AI Builder homepage and can start using it

The auto-update URL is https://atomgit.com/UCToo/agentskills-runtime-pc/releases/download/<version>/. The client has electron-updater built in and will prompt you to upgrade when a new version is released.

If you prefer to run the runtime kernel directly from source (e.g. for server deployment or secondary development), continue reading the Overview and Quick Start sections below.

Overview

AgentSkills Runtime is a comprehensive framework for building and executing AI agent skills. It provides a secure, portable, and intelligent runtime environment for AI agent tools that follow the agentskills standard. The framework is built on the Cangjie programming language and incorporates advanced features from the UCToo project architecture.

The framework includes:

  • Support for the agentskills standard, including loading and validation of SKILL.md files
  • DSL support with @skill, @tool, and @agent macros
  • Clean architecture with clear separation of concerns (domain layer, application layer, infrastructure layer)
  • MCP (Model Context Protocol) support for integration with AI agents
  • Skill-to-tool adapter for compatibility between skills and tools
  • Progressive skill loading from configurable directories
  • WASM-based security sandboxing for secure skill execution
  • Advanced RAG search with hybrid dense+sparse search capabilities
  • Multi-format skill support (WASM components and SKILL.md files)

🎯 Project Vision

Build a domestically developed and controllable AI agent skill runtime, promote the application of Agent Skills standards in the AI ecosystem, and construct an open, secure, and efficient AI-native application infrastructure. Aiming to enable AgentSkills to run anywhere.

Business Case & Value Proposition

Submission

Final Submission Checklist:

  • Software Application Track: Beichen Commercial Management — Beichen Industrial Cloud Community Challenge
  • Work Name: AgentSkills-runtime — Domestic AI Agent Using Cangjie Programming Language
  • Slogan: With Chinese wisdom, build global intelligence connectivity, co-create new productive forces in the AI era
  • Work Description: Using the fully self-developed AgentSkills-runtime (ASR) next-generation AI-driven development framework, we developed a complete solution for the Beichen Industrial Cloud Community. The main deliverables for this competition include: 1) Updated ASR to v0.0.27, releasing the "everything is a skill" plugin system, benchmarked against deepseek-harness's "everything is a plugin" approach — ASR's plugin system is more intelligent with strong security, high performance, native intelligence, and deterministic design principles more suitable for enterprise customers. 2) Developed an online supply-demand matching portal subsystem for the Beichen Industrial Cloud Community. 3) Developed the Industrial Policy Assistant and Finance Matching Agent for the two key challenges of "precision policy empowerment" and "systematized financial services", enabling resident enterprises to intelligently match industrial needs and financial services.
  • Project Images: (to be supplemented)
  • GitHub Repositories (set Topic to #shenicest-fission):
    1. AI-Driven Development Framework: https://atomgit.com/UCToo/agentskills-runtime
    2. shenicest Hackathon SDD Docs: apps/agentskills-runtime/.codeartsdoer/specs/shenicestHackathon
    3. Beichen Policy Assistant: apps/agentskills-runtime/skills/beichen-policy-assistant
    4. Beichen Finance Matching: apps/agentskills-runtime/skills/beichen-finance-matching
    5. Supply-Demand Portal: https://atomgit.com/UCToo/web-admin
  • Project Documentation (background, target users, tech stack, innovation, team division, development process, and follow-up plans): apps/agentskills-runtime/.codeartsdoer/specs/shenicestHackathon/shenicest项目文档-AgentSkills-runtime.docx
  • Demo Video: beichen policy assistant Demo Recording
  • Live Demo Link (optional): https://demo.uctoo.com
  • Zhihu Article: "Major Update: Everything is a Skill Plugin System" https://zhuanlan.zhihu.com/p/2077145055673037317

Competition Entry: Financial Industry Agent Hackathon (2026/07/27 - 2026/08/08) Demo Video: Investment Research Assistant Demo Recording Source Code: https://atomgit.com/UCToo/agentskills-runtime Technical Docs: This README (product docs + architecture design + core modules + performance data)

4.1 Target Scenarios

This work targets real financial industry business scenarios, using "Investment Research Assistant" as the typical application, automating the full pipeline: automated fetching → data cleaning → factor extraction → report generation → database persistence → daily investment brief:

  1. Intelligent Investment Research & Daily Brief: Automatically fetches multi-source data (market data, announcements, news), cleans and deduplicates, extracts key investment factors (valuation, financials, events, sentiment), generates structured daily investment briefs, writes company data to the company table and research reports to the tasks table, visualized through the aibuilder module.
  2. Financial Industry Agent Infrastructure: AgentSkills Runtime provides a standardized skill runtime environment (SKILL.md loading/validation, WASM sandbox, RBAC permissions, MCP/WebMCP integration, audit logs), enabling rapid development and secure operation of financial business Agents.
  3. Financial Business System Integration: Built on the Cangjie-language high-performance application server (HTTP/HTTPS, WebSocket, SSE), Agents seamlessly integrate with traditional financial ICT infrastructure.

Reference Resources (A Complete Run Flow & Outputs)

To inspect the actual run-flow logs, working outputs, and SDD engineering directory of the investment-research-assistant skill, refer to the following locations:

Resource Path Description
Run-flow log logs/agentskills-runtime.log Runtime-side complete record of the skill's six-step SOP execution chain, tool invocations, LLM reasoning/thinking-chain events, errors, and fallback processes
Startup log logs/runtime_start.log Runtime service startup log (MCP/WebMCP/SSE listener init, skill loading, permissions, and database connections)
Web console log logs/web_console.md Actual interaction records of the web chat window (thinking-chain dynamic display, cancel-chat, and other frontend behaviors)
Skill working outputs skills/investment-research-assistant/output/ Actual outputs of the six-step SOP: raw/ (raw fetched JSON), clean/ (cleaned JSON), factors/ (factor JSON), brief/ (investment brief Markdown), sql/ (DB-persistence SQL)
SDD engineering directory .codeartsdoer/specs/fintech-agent-hackathon/ Full Specification-Driven Development engineering docs: competition requirements, requirement specs, technical design, task lists, iterative optimization analysis reports (optimization-report.md) and implementation plans (optimization-plan.md)

Iteration note: optimization-report.md and optimization-plan.md append a new chapter per real-test iteration (currently through V17), fully recording each round's root causes, log evidence, fix plans, and verification checklists — the core reference for understanding the skill's evolution and reproducing the fix process.

4.2 Target Customers

Customer Type Typical Scenario Value Proposition
Securities/Fund Research Depts Daily investment brief, stock analysis, industry reports Research production efficiency gains, standardized output
Bank/Insurance Wealth Management Client portfolio analysis, market news aggregation Automated advisory content, expanded service coverage
Fintech Companies Agent application platform, research data services Rapid business Agent delivery, reduced development costs
Financial Regulators/Research Institutes Market data monitoring, sentiment analysis Compliance data retention, auditable traceability
Developers/Open Source Community Agent skill development, standard practices Open standards, domestically controllable tech stack

4.3 Business Model

  1. Open Source Community Edition (Free): AgentSkills Runtime is MIT-licensed, providing the complete skill runtime environment and the investment-research-assistant skill to attract developer ecosystem participation.
  2. Enterprise Private Deployment (License): For financial institutions requiring private deployment with PostgreSQL, RBAC, audit logs, and domestic tech stack (Cangjie + Ascend computing), billed as annual License.
  3. Cloud Service Subscription (SaaS): Managed Agent runtime platform and intelligent research service subscription, billed per seat/API usage.
  4. Value-Added Services: Industry skill customization, data source integration, deployment & operations, training and technical support.

4.4 Demo Video

https://atomgit.com/UCToo/agentskills-runtime/blob/main/public/demo.mp4

You can also download the demo video to watch locally.

Architecture Design

This implementation follows clean architecture principles with clear separation of concerns:

  • Domain Layer: Contains business logic and entities (SkillManifest, SkillParameter, etc.)
  • Application Layer: Orchestrates use cases (SkillLoadingService, SkillValidationService, etc.)
  • Infrastructure Layer: Handles external concerns (file loading, YAML processing, etc.)
  • Presentation Layer: Manages skill and tool interactions

Features

GB/Z 185-2026 National Standard for Agent Interconnection Support

AgentSkills Runtime has implemented support for the national standard "Artificial Intelligence - Agent Interconnection" (GB/Z 185.1~185.7-2026), adopting a dual-mode layered architecture:

  • Local Mode: For agent collaboration within the same system, reusing the existing uctoo_user + RBAC system for identity management, agent_messages + agent_tasks for message passing, and extending the national standard data models (ACS description format, interaction message/task/session structures). The system runs in local mode by default.
  • Interconnection Mode: For scenarios requiring interconnection with agents in external systems, fully implementing GB/Z 185.2~185.7 capabilities on top of local mode, integrating with ACPs registry service, CA service, discovery service, and MQ service, with AIC identity codes, CAI credentials, and mTLS authentication. Interconnection mode is a superset of local mode.

Core Capabilities

Standard Part Capability Local Mode Interconnection Mode
GB/Z 185.2 Agent Identity Management (AIC/CAI) uctoo_user + RBAC ACPs registry + AIC + CAI + mTLS
GB/Z 185.3 Agent Trusted Registration (ATR) Local auto-creation ACPs registry full process
GB/Z 185.4 Agent Capability Description (ACS) agents + agent_skills table extension Sync to ACPs registry/discovery
GB/Z 185.5 Agent Discovery (ADP) Local agents table query ACPs discovery cross-system
GB/Z 185.6 Agent Interaction Protocol (AIP) agent_messages + agent_tasks MQ message distribution + mTLS
GB/Z 185.7 Tool Invocation Reuse MCP tool system Reuse MCP tool system

Database Extensions

The agents table has been extended with AIP-related fields:

Field Type Description
aic varchar(128) Agent Identity Code (AIC), GB/Z 185.2 OID format
identity_status varchar(20) AIP identity status: none/active/locked/revoked
aip_registered_at timestamptz AIP identity registration time
capabilities jsonb Auxiliary Capability Description (ACS), GB/Z 185.4
default_input_types jsonb Default input types (ACS), GB/Z 185.4
default_output_types jsonb Default output types (ACS), GB/Z 185.4
discoverable bool Whether discoverable by other agents, GB/Z 185.5

AGENTS.md Format Extension

The YAML frontmatter of AGENTS.md has been extended to support AIP fields:

---
name: MainAgent
agent_type: main
description: Main Agent description
identity_status: none          # AIP identity status
discoverable: true             # Whether discoverable
capabilities: []               # Auxiliary Capability Description (ACS)
default_input_types: []        # Default input types
default_output_types: []       # Default output types
---

MQ Message Distribution Adapter

In interconnection mode, AcpsMqAdapter implements reliable distribution of GB/Z 185.6 group interaction messages, based on activemq4cj (Cangjie ActiveMQ SDK, JMS 2.0 specification implementation), supporting:

  • Point-to-point and publish/subscribe dual-mode message channels
  • Durable subscriptions and transactional messages
  • Failover automatic reconnection
  • TLS encrypted connections
  • MQ authentication service ACL validation

For detailed design documentation, see .codeartsdoer/specs/aip-implementation/ and .codeartsdoer/specs/aip-mq-adapter/.

AgentSkills Standard Support

  • Loading skills from SKILL.md files according to the agentskills specification
  • YAML frontmatter parsing with validation
  • Markdown body processing for skill instructions
  • External resource access (scripts/, references/, assets/)

API Interface Layer

  • Comprehensive RESTful API for skill management
  • Endpoints for skill lifecycle management (add, edit, delete, execute)
  • Real-time skill loading and reloading
  • Standardized response formats following UCToo API specification

API Endpoints

All API endpoints now follow the uctoo v4 standard with /api/v1/uctoo prefix:

  • GET /api/v1/uctoo/agent_skills: Retrieve a list of installed skills with pagination support
  • GET /api/v1/uctoo/agent_skills/:id: Retrieve details of a specific skill
  • POST /api/v1/uctoo/skills/install: Install a skill from a local path or remote URL
  • POST /api/v1/uctoo/agent_skills/edit: Update an existing skill
  • POST /api/v1/uctoo/agent_skills/del: Uninstall a skill
  • POST /api/v1/uctoo/skills/execute: Execute a skill with provided parameters
  • POST /api/v1/uctoo/skills/search: Search for skills using semantic search
  • GET /api/v1/uctoo/health: Health check endpoint
  • GET /api/v1/uctoo/mcp/stream: MCP server with HTTP streaming mode
  • GET /api/v1/uctoo/ws/chat: WebSocket chat interface

API Implementation Details

The API layer now provides real functionality using underlying services:

  • POST /api/v1/uctoo/skills/install: Uses SkillPackageManager to perform actual skill installation from local paths or Git repositories
  • POST /api/v1/uctoo/agent_skills/edit: Updates skills using the SkillPackageManager with proper reloading
  • POST /api/v1/uctoo/agent_skills/del: Removes skills from the system using SkillPackageManager and refreshes the skill registry

DSL Support

  • @skill macro for declarative skill definition
  • @tool macro for tool definition
  • @agent macro for agent definition

Security

  • WASM-based security sandboxing with Component Model support
  • Capability-based access control (filesystem, network, etc.)
  • Resource quotas and execution limits
  • Execution context isolation

Search & Discovery

  • Advanced RAG search with hybrid dense+sparse search (vector embeddings + BM25 with RRF fusion)
  • Cross-encoder reranking for improved precision
  • Query understanding with intent classification and entity extraction
  • Context compression for token-efficient output

Multi-Format Skill Support

  • WASM component model execution with Component Model support
  • SKILL.md file parsing and execution following agentskills standard
  • Format-agnostic skill interface
  • Dynamic format detection and validation

MCP Integration

  • Dynamic tool discovery from skill manifests
  • Semantic search integration with MCP protocol
  • Pagination support for large skill catalogs
  • HTTP streaming mode with embedded web UI

Built-in Tools v2.0

AgentSkills Runtime v2.0 provides a complete set of built-in tools supporting CLI, HTTP, and internal API invocation methods, all integrated with the RBAC permission system.

Tool Categories

File System Tools (9)

  • file_read - Read file (Sensitivity: Low)
  • file_write - Write file (Sensitivity: Medium)
  • file_edit - Edit file (Sensitivity: Medium)
  • file_delete - Delete file (Sensitivity: High, requires confirmation)
  • file_copy - Copy file (Sensitivity: Low)
  • file_move - Move file (Sensitivity: Medium)
  • file_search - Search files (Sensitivity: Low)
  • directory_list - List directory (Sensitivity: Low)
  • directory_create - Create directory (Sensitivity: Medium)

Web Tools (4)

  • http_request - HTTP request (Sensitivity: Medium)
  • web_fetch - Web page fetch (Sensitivity: Low)
  • firecrawl - Firecrawl crawler (Sensitivity: Medium)
  • browser_tool - Browser tool (Sensitivity: Medium)

Skill Tools (2)

  • skill_initializer - Initialize skill (Sensitivity: Medium)
  • skill_packager - Package skill (Sensitivity: Medium)

Code Generation Tools (2)

  • template_engine - Template engine (Sensitivity: Low)
  • code_snippet_generator - Code snippet generator (Sensitivity: Low)

CLI Tools (1)

  • cli_execute - Execute CLI command (Sensitivity: High, requires confirmation)

HTTP Interface

Base Path: /api/v1/tools

Endpoints:

  • GET /api/v1/tools/list - Get tool list
  • GET /api/v1/tools/:toolName/info - Get tool information
  • POST /api/v1/tools/:toolName - Invoke tool

Usage Example:

# Get tool list
curl -X GET https://javatoarktsapi.uctoo.com/api/v1/tools/list \
  -H "Authorization: Bearer <token>"

# Invoke file read tool
curl -X POST https://javatoarktsapi.uctoo.com/api/v1/tools/file_read \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"path": "./SKILL.md"}'

Permission System

All tool invocations are protected by the RBAC permission system:

  • Sensitivity Levels: Low(1), Medium(2), High(3)
  • Permission Check: Every invocation validates user permissions
  • Audit Logging: All operations are recorded in the database
  • Confirmation Required: High-sensitivity operations require confirmation parameter

Detailed documentation: Built-in Tools Documentation

High-Performance Application Server

AgentSkills Runtime includes a high-performance HTTP/HTTPS application server providing enterprise-level API service capabilities.

Server Features

  • HTTPS Support: Built-in SSL/TLS encryption with certificate configuration
  • High-Performance Routing: Efficient Trie-tree based route matching
  • Middleware System: Extensible middleware chain
  • WebSocket Support: Real-time bidirectional communication
  • Connection Pool: Database connection pool management
  • Cache System: Built-in cache manager

Core Components

HTTPServer

  • HTTP/HTTPS protocol support
  • Configurable thread pool
  • Request/response interceptors
  • Static file serving

Router

  • RESTful routing support
  • Path parameter extraction
  • Route grouping
  • Middleware mounting

Middleware

  • DeserializeUserMiddleware - JWT authentication
  • RequirePermissionMiddleware - Permission checking
  • CORSMiddleware - CORS support
  • LoggingMiddleware - Request logging

Server Configuration

# .env configuration
PORT=443
HOST=0.0.0.0
SSL_CERT=./ssl/server.crt
SSL_KEY=./ssl/server.key
DB_URL=postgresql://user:pass@host:port/db

Start Service

# Build
cjpm build

# Start HTTPS service
cjpm run --skip-build --name magic.app

API Endpoints

  • GET /hello - Health check
  • GET /api/v1/health - Service status
  • GET /api/v1/info - Application info
  • /api/v1/uctoo/* - UCToo business API
  • /api/v1/tools/* - Tool management API
  • /api/v1/skills/* - Skill management API

Performance Metrics

  • Concurrent Connections: Supports 1000+ concurrent connections
  • Response Time: Average response time < 50ms
  • Throughput: > 10000 req/s
  • Memory Usage: Base memory < 100MB

Multi-Language Ecosystem Support

  • Cross-Language Interoperability: Support for skills written in different programming languages working together in the same runtime environment
  • Language Adapters: Standardized skill interface adapters for different programming languages
  • Unified API Layer: Abstracts underlying implementation details and provides consistent programming interfaces
  • Dependency Management: Intelligent handling of dependency relationships and version conflicts in multi-language projects

Multi-Language SDK Support

  • JavaScript/TypeScript SDK: Complete Node.js and browser environment support, for web applications and frontend integration
  • Python SDK: Integration with popular Python AI and data science libraries, suitable for data analysis and AI model integration
  • Java SDK: Enterprise application and Android platform support, suitable for large enterprise systems
  • Go SDK: High-performance concurrent processing and cloud-native application support, suitable for microservice architecture
  • Rust SDK: System-level performance and memory safety guarantees, suitable for performance-critical scenarios
  • C# SDK: .NET ecosystem and Windows platform integration, suitable for enterprise internal systems

SDK Core Value

  • Traditional Systems + AI: Quickly integrate AI capabilities into existing digital systems without rebuilding existing architecture
  • Skill Market Access: Easily access the skill market through SDK, enabling unlimited capability expansion
  • Standardized Integration: Provide unified API interfaces, simplifying cross-language integration complexity
  • Out-of-the-Box: Built-in runtime installation and management functionality, no manual configuration required
  • Cross-Platform Support: The same API adapts to different technology stacks, reducing learning costs

Core Features

🚀 High-Performance Execution

  • High Performance: High-performance runtime based on Cangjie programming language
  • Strong Security: WASM sandbox secure execution environment + multi-layer permission control security architecture
  • Standardization: Fully compatible with AgentSkills open standard specifications

🔒 Security and Reliability

  • Execution Isolation: Multi-layer security protection mechanism
  • Permission Control: Fine-grained permission management and resource access control
  • Audit Tracking: Complete operation logs and security audit mechanism

📦 Standard Compatibility

  • Fully compatible with AgentSkills open standards
  • Support for SKILL.md file format
  • Implementation of standard YAML frontmatter specifications

🔧 Ease of Use

  • Simple Integration: Provides clean API interfaces
  • Rich Examples: Diverse usage examples and best practices
  • Comprehensive Documentation: Complete Chinese and English technical documentation

🔧 Flexible Extension

  • Plugin-based architecture design
  • Support for custom skill development
  • Rich API interfaces and tool sets

Quick Start

Simplest Usage Solution (Recommended)

If you want to quickly experience AgentSkills Runtime's capabilities, you don't need to download the source code of this project. Simply clone the UCToo project:

Deployment Steps

  1. Clone UCToo Project

    git clone https://atomgit.com/UCToo/web-admin.git
cd web-admin

  2. Run Installation Assistant

    • Double-click to run web-admin/start-installer.bat (Windows system)
    • Or execute in command line: 
      cd web-admin
start-installer.bat

  3. Follow Installation Assistant to Configure Environment

    • The installation assistant will automatically check the environment (Node.js, PostgreSQL, Redis, etc.)
    • Configure database connection information
    • Configure SSL certificate (development environment can choose self-signed certificate)
    • Configure LLM API Key (supports DeepSeek, OpenAI, Huawei Cloud MaaS, etc.)
    • Create administrator account

  4. Use JavaScript SDK in web-admin

    • After installation, web-admin has built-in AgentSkills Runtime JavaScript SDK
    • Install and start agentskills-runtime through the installation wizard or configuration page in web-admin management backend

  5. Login to Use Agent Applications

    • Open web-admin management backend (default address: http://localhost:3031)
    • Login with the created administrator account
    • Access AI Module -> Chat Page to use agent functions
    • Use natural language to chat with AI and perform CRUD operations on the database
    • Example conversations:
      • "Query the list of users registered in the past week"
      • "Create a new user named 'John Doe'"
      • "Calculate the total order amount for this month"

Solution Advantages

  • Zero Configuration: No need to install the Cangjie programming language environment
  • Ready to Use: One-click start of installation assistant, automatic configuration of complete runtime environment
  • Full Functionality: Supports the built-in uctoo-api-skill for natural language database operations
  • Easy to Extend: Can continue developing custom skills based on the UCToo framework
  • Visual Configuration: Easily manage runtime and configuration through web-admin graphical interface

Starting from Source (For Developers)

If you need to perform secondary development on the runtime or contribute code, please refer to the following steps:

Environment Requirements

  • Cangjie programming language environment (https://cangjie-lang.cn/)
  • Supported operating systems: Windows/Linux/macOS
  • Windows System Specific Requirement: OpenSSL library is required for WebSocket communication
    • Download URL: https://slproweb.com/products/Win32OpenSSL.html
    • During installation, select "Copy OpenSSL DLLs to: The OpenSSL binaries (/bin) directory"
    • Ensure the OpenSSL bin directory is added to the system PATH environment variable

Installation

# Ensure Cangjie programming language environment is installed
cjpm --version

# Clone the project
git clone https://atomgit.com/uctoo/agentskills-runtime.git
cd agentskills-runtime

Running Examples

# Build the project
cjpm build

Running API Service

# Run the API service on default port 8080
cjpm run --skip-build --name magic.app

# Or run on a specific port
cjpm run --skip-build --name magic.app 8081

For detailed instructions on running the API service, see API Service Run Guide.

Code Generation Tools (crudgen / crudweb)

AgentSkills Runtime includes two built-in code generation tools that automatically generate backend CRUD modules and frontend Web pages from database table structures, implementing Code Definition Specification (CDS) features to ensure architectural stability.

Important: You must use the cjpm run command to execute code generation tools. Do not run exe files directly from the target directory (DLL path issues will cause startup failures). The working directory must be the agentskills-runtime project root directory.

crudgen - Backend CRUD Module Generator

Automatically generates Cangjie backend standard modules (Model → DAO → Service → Controller → Route) from database table structures.

# Generate backend CRUD module for a specific table
cjpm run --skip-build --name magic.app.tools.crudgen --run-args="--db <database> --table <table_name>"

# Example: Generate backend module for point_transactions table in uctoo database
cjpm run --skip-build --name magic.app.tools.crudgen --run-args="--db uctoo --table point_transactions"

# Generate backend CRUD modules for all tables in a database
cjpm run --skip-build --name magic.app.tools.crudgen --run-args="--db uctoo --all"

# View help information
cjpm run --skip-build --name magic.app.tools.crudgen --run-args="--help"

Generated files:

  • PO (Persistence Object): src/app/po/uctoo/<table_name>PO.cj
  • Model: src/app/models/uctoo/<TableName>.cj
  • DAO (Data Access Layer): src/app/dao/uctoo/<TableName>DAO.cj
  • Service (Business Logic Layer): src/app/services/uctoo/<TableName>Service.cj
  • Controller: src/app/controllers/uctoo/<table_name>/<TableName>Controller.cj
  • Route: src/app/routes/uctoo/<table_name>/<TableName>Route.cj
  • Auto-updates AutoRouteConfig.cj for route registration

crudweb - Frontend Web Page Generator

Automatically generates Vue frontend CRUD pages (list, add, edit form, data table) and Pinia-ORM Store models from database table structures.

# Generate frontend Web page for a specific table
cjpm run --skip-build --name magic.app.tools.crudweb --run-args="--db <database> --table <table_name>"

# Example: Generate frontend page for point_transactions table in uctoo database
cjpm run --skip-build --name magic.app.tools.crudweb --run-args="--db uctoo --table point_transactions"

# Generate frontend Web pages for all tables in a database
cjpm run --skip-build --name magic.app.tools.crudweb --run-args="--db uctoo --all"

# Specify output directory (optional, defaults to WEB_CRUD_OUTPUT_DIR in .env)
cjpm run --skip-build --name magic.app.tools.crudweb --run-args="--db uctoo --table <table_name> --output <output_dir>"

# View help information
cjpm run --skip-build --name magic.app.tools.crudweb --run-args="--help"

Generated files (output to directory configured by WEB_CRUD_OUTPUT_DIR, with /web/src/ path appended):

  • Page entry: views/database/<db_name>/<table_name>/index.vue
  • Add component: views/database/<db_name>/<table_name>/components/add-<table_name>.vue
  • Data table: views/database/<db_name>/<table_name>/components/<table_name>-table.vue
  • Edit form: views/database/<db_name>/<table_name>/components/edit-form.vue
  • Store model: store/models/<db_name>/<table_name>.ts
  • Auto-updates Store index.ts exports

Environment variable configuration (in .env file):

# Web CRUD code output root directory (crudweb automatically appends /web/src/ subdirectory)
WEB_CRUD_OUTPUT_DIR=D:\path\to\web-admin

plugingen - Plugin Generator (Plugin Track)

plugingen is a deterministic generation tool isomorphic to crudgen, but its output lands on the plugin track rather than the host track: it reads the table structure from db_info and generates the "three-in-one" plugin directory skills/{name}/ (SKILL.md + plugin.yaml + scripts/cj/ five-layer CRUD + plugin entry). New capabilities are delivered exclusively in plugin form — no new code is appended to src/app or AutoRouteConfig.cj.

crudgen vs plugingen selection:

  • crudgen: generates host modules into src/app/ and auto-appends AutoRouteConfig.cj — targets the frozen host body (reduce-only channel).
  • plugingen: generates plugins into skills/{name}/, synced to src/plugins/{name}/ via build.cj's build-sync (PS-T015) for compilation, package name magic.plugins.{name} — targets future new plugins (plugin track of the dual-track coexistence).
# Table-driven: read table structure from db_info, generate five-layer CRUD plugin to skills/{name}/
cjpm run --skip-build --name magic.plugin.tools.plugingen --run-args="--name <plugin_name> --db <database> --table <table_name>"

# Example: generate a CRUD plugin for the feedback table in the uctoo database (plugin name equals table name)
cjpm run --skip-build --name magic.plugin.tools.plugingen --run-args="--name feedback --db uctoo --table feedback"

# Blank skeleton: generate only SKILL.md + plugin.yaml + package placeholder + plugin entry (skip table structure)
cjpm run --skip-build --name magic.plugin.tools.plugingen --run-args="--name mytool --blank"

# View help information
cjpm run --skip-build --name magic.plugin.tools.plugingen --run-args="--help"

Options:

Option Description
--name <plugin_name> Plugin unique name (required). Lowercase letters/digits/underscores; hyphens auto-converted to underscores.
--db <database> Table-driven mode: database name (reads db_info table structure).
--table <table_name> Table-driven mode: table name.
--blank Generate a blank plugin skeleton (skip table structure).
--help, -h Show help.

Generated content (artifacts in skills/{name}/):

Artifact Path Description
Skill definition skills/{name}/SKILL.md SkillEngine asset, not compiled
Plugin manifest skills/{name}/plugin.yaml Plugin static metadata (name/version/entry/tables/routes)
Package placeholder skills/{name}/scripts/cj/pkg.cj Cangjie package declaration package magic.plugins.{name}
PO layer skills/{name}/scripts/cj/{ClassName}PO.cj Persistent object
DAO layer skills/{name}/scripts/cj/{ClassName}DAO.cj Data access
Service layer skills/{name}/scripts/cj/{ClassName}Service.cj Business logic
Controller layer skills/{name}/scripts/cj/{ClassName}Controller.cj Controller
Route layer skills/{name}/scripts/cj/{ClassName}Route.cj Route (@ModuleRoute annotation)
Plugin entry skills/{name}/scripts/cj/{ClassName}Plugin.cj @Plugin annotation, onLoad wires Service→Controller

It also auto-appends a host loading manifest entry to config/plugins.yaml (containing name/className/enabled/order/routeClass/config).

Auto-generating menu permission nodes (consistent with crudgen):

After generating the code files, plugingen automatically writes a three-level menu structure to the permissions table and inserts multilingual titles into the i18 table. The web admin backend renders menus based on this data:

database (root menu)
└── database.{dbName} (database menu)
    └── database.{dbName}.{tableName} (table menu, component points to database/{dbName}/{tableName}/index)
  • Idempotent: existing nodes are skipped; soft-deleted nodes are restored (deleted_at = NULL); non-existent nodes are created.
  • i18 multilingual: after the table node is inserted, a title record is written to the i18 table keyed by locale (e.g., menu.database.uctoo.feedback).
  • Menu visibility: after generation, assign the menu permission to the corresponding role in the web admin backend, or view it directly with an admin account.

Note: plugingen only generates menu permission nodes in table-driven mode (--db + --table); --blank skeleton mode does not involve database tables and does not generate menus.

Next steps (build-sync auto-chaining):

  1. cjpm build: the pre-build hook in build.cj automatically syncs skills/{name}/scripts/cj/ to src/plugins/{name}/ (artifacts are not committed, see .gitignore), and scans plugin.yaml's entry/routes class names to generate src/plugins/generated_anchors.cj (L1 reflection anchors, ensuring the static linker retains plugin classes).
  2. Start the host: PluginManager loads plugins per config/plugins.yaml, and PluginRouteScanner registers routes at runtime via reflection (@ModuleRoute → ClassTypeInfo.get → ConstructorInfo.apply → register(router, controller)).
  3. Zero-framework-change rollout: new plugins go live without modifying main.cj or AutoRouteConfig.cj — the build-sync anchor mechanism covers it automatically.

Dependency validation: build-sync performs a lightweight warn-level check on plugin.yaml's dependencies before syncing (prints WARN if skills/{dep}/ is missing); hard validation is performed by the runtime PluginLoader.

Everything is a Skill: Plugin System Complete Guide

AgentSkills Runtime follows the "Everything is a Skill" design philosophy — all new capabilities are delivered exclusively in plugin form, with no new code appended to src/app or AutoRouteConfig.cj. The plugin system evolves through four phases:

Phase Version Milestone Status
I: Plugin Framework Core v0.5 Integration tests green, zero regression to existing functionality ✅ Complete
II: Incremental Pluginization v0.6 First real new plugin goes live without framework code changes ✅ Verified
III: L2 Dynamic Loading v0.7~v0.9 Install a new plugin without recompiling the host ✅ Complete
IV: Plugin Marketplace v1.0/v1.1 Third parties can independently publish plugins ⏳ Planning

Plugin System Architecture

┌─────────────────────────────────────────────────────────────┐
│                    Host (magic.app)                         │
│  ┌─────────────┐  ┌──────────────┐  ┌────────────────────┐ │
│  │PluginManager│  │PluginRoute   │  │SkillBridge         │ │
│  │(lifecycle)  │  │Scanner(route)│  │(skill fusion)      │ │
│  └──────┬──────┘  └──────┬───────┘  └─────────┬──────────┘ │
│         │                │                     │            │
│  ┌──────▼──────┐  ┌──────▼───────┐  ┌─────────▼──────────┐ │
│  │PluginLoader │  │PluginEventBus│  │ServiceRegistry      │ │
│  │(reflection) │  │(event bus)   │  │(service registry)   │ │
│  └──────┬──────┘  └──────────────┘  └────────────────────┘ │
│         │                                                    │
│  ┌──────▼──────┐                                            │
│  │PluginDylib  │  ← L2 dynamic library loading (PS-T012)   │
│  │Loader       │                                            │
│  └─────────────┘                                            │
└─────────────────────────────────────────────────────────────┘
                    ↕ plugin_spi contract
┌─────────────────────────────────────────────────────────────┐
│              Plugin Package (magic.plugins.{name})          │
│  @PluginAnnotation + @ModuleRouteAnnotation                 │
│  Independent cjpm package → libskill_{name}.so → closed-source distribution │
└─────────────────────────────────────────────────────────────┘

Plugin Development Methods

Method 1: plugingen table-driven generation (recommended)

# Read table structure from db_info, generate five-layer CRUD plugin to skills/{name}/
cjpm run --skip-build --name magic.plugin.tools.plugingen \
  --run-args="--name <plugin_name> --db <database> --table <table_name>"

# Example: generate CRUD plugin for feedback table in uctoo database
cjpm run --skip-build --name magic.plugin.tools.plugingen \
  --run-args="--name feedback --db uctoo --table feedback"

Method 2: Blank skeleton manual development

# Generate blank plugin skeleton (SKILL.md + plugin.yaml + package placeholder + plugin entry only)
cjpm run --skip-build --name magic.plugin.tools.plugingen \
  --run-args="--name mytool --blank"

After generation, add business code under skills/mytool/scripts/cj/, which participates in compilation via build-sync.

Plugin three-in-one structure:

Dimension Artifact Description
Service {ClassName}Service.cj Business logic, exposed via ServiceRegistry type-safe track
Skill SKILL.md SkillEngine asset, auto-registered via SkillBridge
Route {ClassName}Route.cj @ModuleRouteAnnotation declarative route, registered via PluginRouteScanner reflection

Plugin Loading Mechanism

L1 Reflection Loading (Phase I~II, existing track):

  • ClassTypeInfo.get(qualified_name) → findAnnotation<PluginAnnotation>() → ConstructorInfo.apply instantiation
  • build-sync syncs skills/{name}/scripts/cj/ → src/plugins/{name}/ to participate in host compilation
  • generated_anchors.cj reflection anchors prevent LTO pruning

L2 Dynamic Library Loading (Phase III, plugin track):

  • Plugin independent cjpm package compiled to libskill_{name}.so (output-type = "dynamic")
  • PluginDylibLoader.loadFromDylib(libPath, pluginName) dynamically loads
  • Reuses fountain App.run() pipeline: PackageInfo.load → BeanFactory.afterRegistered() → getList<Plugin>()
  • Install a new plugin without recompiling the host — Phase III milestone achieved

Plugin Publishing Methods

Workspace member mode (Scheme A, Phase III L2 dynamic library loading):

Plugins are independent members of the host cjpm workspace, compiled as dynamic libraries (output-type = "dynamic"), and dynamically loaded by the host via fountain's PackageInfo.load pipeline.

  1. Generate plugin: plugingen --name entity --db uctoo --table entity
    • Auto-generates skills/entity/cjpm.toml (workspace member config)
    • Auto-appends host cjpm.toml [workspace] members
    • Auto-appends config/plugins.yaml loading manifest entry
  2. Independent compilation: cd skills/entity && cjpm build, producing target/release/libskill_entity.so
  3. Distribution unit: plugin.yaml is the distribution unit manifest (containing name/version/entry/dylib/tables/routes)
  4. Closed-source distribution: plugin-spi dependency minimization (only Cangjie standard library + cangjie-stdx), plugins can be distributed as closed-source dynamic libraries
  5. Host loading: Host-side config/plugins.yaml declares plugin entry, PluginDylibLoader dynamically loads

Independent plugin directory structure (using entity as example):

skills/entity/
├── cjpm.toml          # workspace member config (name="skill_entity", output-type="dynamic")
├── plugin.yaml        # Distribution unit manifest (containing dylib: libskill_entity.so)
├── SKILL.md           # Skill description (SkillEngine asset)
└── src/               # Source directory (conforms to cjpm package structure, src-dir="src")
    ├── pkg.cj         # Package placeholder (package skill_entity)
    ├── EntityPO.cj    # Persistent object
    ├── EntityDAO.cj   # Data access
    ├── EntityService.cj    # Business logic
    ├── EntityController.cj # Controller
    ├── EntityRoute.cj      # Route (@ModuleRouteAnnotation)
    └── EntityPlugin.cj     # Plugin entry (@PluginAnnotation)

Host cjpm.toml workspace configuration:

[workspace]
  members = ["./skills/entity", "./skills/feedback"]

New plugin加入: append "./skills/{name}" to members list (plugingen auto-completes).

Plugin Uninstall Methods

pluginuninstall CLI tool (PS-T019/PS-T020):

# Uninstall plugin (remove entry from plugins.yaml + prompt runtime uninstall)
cjpm run --skip-build --name magic.plugin.tools.pluginuninstall \
  --run-args="--name entity"

# Also delete plugin directory
cjpm run --skip-build --name magic.plugin.tools.pluginuninstall \
  --run-args="--name entity --purge"

# Specify config file path
cjpm run --skip-build --name magic.plugin.tools.pluginuninstall \
  --run-args="--name entity --config ./config/plugins.yaml"

Uninstall flow:

  1. Precisely remove the specified plugin entry from plugins.yaml (backward trace comments/blank lines, forward delete to next entry)
  2. Prompt runtime uninstall (CLI tool does not directly call PluginManager.deactivate; requires host restart or Agent tool plugin_deactivate)
  3. Optionally delete plugin directory (--purge, recursive deletion)

Runtime uninstall (Agent tool):

  • plugin_deactivate(name) → PluginManager.deactivate(name)
  • Five-dimensional cleanup after uninstall: route cleanup, event subscription cleanup, registry cleanup, service deregistration cleanup, isolation verification

Plugin System Core Components

Component File Responsibility
PluginManager src/plugin/plugin_manager.cj Plugin lifecycle orchestrator (load → onLoad → onActivate → register → skill registration)
PluginLoader src/plugin/plugin_loader.cj L1 reflection loader (ClassTypeInfo.get → findAnnotation → ConstructorInfo.apply)
PluginDylibLoader src/plugin/plugin_dylib_loader.cj L2 dynamic library loader (PackageInfo.load → BeanFactory.afterRegistered → getList)
PluginRouteScanner src/plugin/plugin_route_scanner.cj Plugin route runtime registrar (plugin track of dual-track routing)
PluginEventBus libs/plugin-spi/src/plugin_event_bus.cj Plugin collaboration event bus (emit broadcast + waterfall chain + ConcurrentHashMap concurrency control)
ServiceRegistry libs/plugin-spi/src/service_registry.cj Service registry (Scheme B fully delegated to BeanFactory)
PluginSyncBridge src/plugin/plugin_sync_bridge.cj Plugin runtime sync bridge (subscribe PluginEventBus events → write back agent_skills table)
plugin-spi libs/plugin-spi/ Plugin SPI contract package (dependency minimization, supports independent compilation as dynamic library)

plugin-spi Extraction (PS-T017 Scheme B)

Plugin contracts migrated from magic.plugin to independent package plugin_spi (libs/plugin-spi/), adopting Scheme B fully delegated + forwarding mode:

  • plugin-spi dependency minimization: Only depends on Cangjie standard library (std.) + cangjie-stdx (stdx.), does not depend on http_lib/magic.log/fountain
  • ServiceRegistry delegates to BeanFactory: Scheme B full delegation, reusing fountain BeanFactory's getList/getFirst generic lookup
  • PluginEventBus concurrency control optimization: ConcurrentHashMap replaces HashMap+Mutex, reusing fountain f_concurrent concurrency pattern
  • Forwarding mode: src/plugin/spi_reexport.cj's public import plugin_spi.{Plugin, ...} allows existing import magic.plugin.{Plugin, ...} consumers to work with zero changes

plugin-spi package structure:

libs/plugin-spi/
├── cjpm.toml          # Independent cjpm package config (output-type="dynamic")
└── src/
    ├── plugin.cj              # Plugin interface (getName/onLoad/onActivate/onDeactivate/onUnload)
    ├── plugin_annotation.cj   # @PluginAnnotation annotation
    ├── plugin_context.cj      # PluginContext (lifecycle carrier + onCleanup cleanup stack)
    ├── plugin_event_bus.cj    # PluginEventBus (ConcurrentHashMap concurrency control)
    ├── service_registry.cj    # ServiceRegistry (delegates to BeanFactory)
    ├── module_route_annotation.cj  # @ModuleRouteAnnotation annotation
    └── plugin_types.cj        # PluginState/PluginError/LoadResult and other types

Plugin System Acceptance Criteria

Phase III milestone achieved:

  • ✅ plugin-spi extraction (Scheme B + forwarding mode, dependency minimization, supports independent compilation as dynamic library)
  • ✅ L2 dynamic library loading prototype (PluginDylibLoader, reuses fountain App.run() pipeline)
  • ✅ pluginuninstall tool (isomorphic with plugingen, precise YAML entry removal + recursive deletion)
  • ✅ build-sync dual-track (existing track src/app/ + plugin track skills/{name}/ → src/plugins/{name}/)
  • ✅ plugingen upgrade (template imports upgraded to plugin_spi, generated plugins consistent with latest plugin mechanism)
  • ✅ Uninstall regression verification (testUninstallRegression 5 dimensions 13 assertions: route/event/registry/service/isolation)

Uninstall regression verification five dimensions (PS-T021 testUninstallRegression):

  1. Route cleanup: routeClassNames() no longer contains the uninstalled plugin's routeClass
  2. Event subscription cleanup: After PluginEventBus.unsubscribeAll(name), all event subscriptions for that plugin are removed
  3. Registry cleanup: registryRef().get(name) returns None
  4. Service deregistration cleanup: services().getService<T>() returns None
  5. Isolation verification: Uninstalling doc-helper does not affect other plugins

Standard Module Development Process

Following the uctoo-v4 Module Development Specification, the standard development process after adding new database tables:

  1. Execute SQL changes: Run table creation or schema change SQL in the database
  2. Refresh database info: Click "Load Database Info" in the Web admin "Database Info" page, or call the API
  3. Generate backend modules: Use crudgen to generate backend standard CRUD modules
  4. Generate frontend pages: Use crudweb to generate frontend Web pages
  5. Business logic development: Write custom business logic outside the AutoCreateCode regions
  6. Build verification: Run cjpm build to verify compilation passes

Release Packaging

Building Release Packages

AgentSkills Runtime provides an automated packaging script to build release packages from source.

Build Steps

# 1. Build the project
cjpm build

# 2. Run the packaging script (automatically reads version from cjpm.toml)
cjpm run --skip-build --name magic.scripts.package_release

Packaging Script Features

  • Automatic Version Detection: Reads version number from cjpm.toml file
  • Automatic Platform Detection: Automatically detects current OS and architecture
  • Lean Packaging: Automatically excludes examples, tests, and other non-essential modules
  • Complete Dependencies: Includes all runtime-required DLL files

Output Files

After packaging completes, release packages will be generated in the release/ directory:

release/
├── agentskills-runtime-win-x64.tar.gz    # Windows x64 release package
├── agentskills-runtime-linux-x64.tar.gz  # Linux x64 release package
├── agentskills-runtime-darwin-arm64.tar.gz # macOS ARM64 release package
└── .env.example                           # Environment variable template

Release Package Directory Structure

release/
├── bin/                    # Executables and all DLLs
│   ├── agentskills-runtime.exe  # Main entry point
│   └── *.dll               # All dependency libraries
├── magic/                  # Runtime modules
├── commonmark4cj/          # Markdown parser
├── yaml4cj/                # YAML parser
├── VERSION                 # Version information
└── .env.example            # Configuration template

Using Release Package

# 1. Extract the release package
tar -xzf agentskills-runtime-win-x64.tar.gz

# 2. Enter directory and configure environment
cd release
cp .env.example bin/.env
# Edit .env file to configure API keys

# 3. Run the service
./bin/agentskills-runtime.exe 8080

Version Release Process

  1. Update version number in cjpm.toml
  2. Update CHANGELOG.md with changes
  3. Run cjpm build to build the project (packaging is automatic)
  4. Create release notes in release/release-notes-<version>.md
  5. Upload release packages to GitHub Releases or AtomGit Releases

Note: Starting from v0.0.21, cjpm build automatically executes the packaging script after completion. The generated release packages are located in the target/release directory.

Manual packaging command is still available (optional):

cjpm run --name magic.scripts.package_release

API Endpoints

After starting the API service, the following endpoints will be available:

  • GET //hello** - Health check endpoint returning "Hello World"
  • GET /skills - Get list of available skills
  • GET /skills/:id - Get details of a specific skill
  • POST /skills/add - Add a new skill
  • POST /skills/edit - Edit an existing skill
  • POST /skills/del - Delete a skill
  • POST /skills/execute - Execute a skill
  • POST /skills/search - Search for skills
  • GET /mcp/stream - MCP server streaming interface
  • WS /ws/chat - WebSocket chat interface (supports AI conversation and skill execution)

WebSocket Chat Interface

The WebSocket endpoint /ws/chat provides real-time AI conversation and skill execution capabilities:

Connection URL

ws://127.0.0.1:8080/ws/chat

Message Formats

Send chat message:

{
  "type": "chat",
  "content": "Hello, please help me analyze this code"
}

Execute skill:

{
  "type": "execute_skill",
  "skill_id": "skill-name",
  "parameters": {
    "param1": "value1"
  },
  "timeout": "60s"
}

Get skill list:

{
  "type": "list_skills"
}

Heartbeat:

{
  "type": "ping"
}

Response Message Types

  • welcome - Welcome message when connection is established
  • chat_response - AI conversation response
  • skill_result - Skill execution result
  • skills_list - Skill list
  • status - Status update
  • error - Error message
  • pong - Heartbeat response

Configuration Requirements

The WebSocket chat feature requires configuring a large model API Key. Configure in the .env file:

# Huawei Cloud MaaS configuration
MAAS_API_KEY=your_api_key_here
MAAS_BASE_URL=https://api.modelarts-maas.com/v2

Supported model providers include: maas, openai, deepseek, dashscope, etc.

Usage

Creating Skills with DSL

import { Skill, Tool } from "agentskills-runtime";

@Skill(
  name = "hello-world",
  description = "A simple skill that greets users",
  license = "MIT",
  metadata = {
    author = "Your Name",
    version = "1.0.0",
    tags = ["greeting", "example"]
  }
)
public class HelloWorldSkill {
    @Tool(
      name = "greet",
      description = "Greet a user by name",
      parameters = [
        { name: "name", type: "string", required: true, description: "The name of the person to greet" }
      ]
    )
    public String greet(String name) {
        return "Hello, " + name + "!";
    }
}

Loading Skills from SKILL.md

Create a SKILL.md file:

---
name: example-skill
description: An example skill demonstrating the SKILL.md format
license: MIT
metadata:
  author: Your Name
  version: "1.0"
---

# Example Skill

This is an example skill that demonstrates the SKILL.md format.

## Tools Provided

### greet

Greet a user by name.

**Parameters:**
- `name` (required, string): The name of the person to greet

**Example:**
```bash
skill run example-skill:greet name=Alice

### Progressive Skill Loading

```cangjie
let skillDir = "path/to/skill/directory"
let loader = ProgressiveSkillLoader(skillBaseDirectory: skillDir)
let skillManager = CompositeSkillToolManager()
let skills = loader.loadSkillsToManager(skillManager)

Application Examples

🎯 Natural Language Database Query - uctoo-api-skill Example

uctoo-api-skill is a complete backend API integration skill example that demonstrates how to query databases using natural language.

Features

  • Natural Language to API Calls: Users can describe query requirements in natural language, and the skill automatically converts them to API calls
  • Multi-Database Support: Works with the uctoo backend project to support multiple database types (MySQL, PostgreSQL, MongoDB, etc.)
  • Any Database Structure: No need to pre-define table structures; supports querying any database structure
  • Universal Query Capability: Supports user management, product management, order management, authentication, and more

Usage Example

User input: "Please query the list of users registered in the last week"

Skill automatically executes:

  1. Analyzes user intent (query users)
  2. Determines time range (last week)
  3. Constructs API request: GET /api/uctoo/entity/10/0?filter={"created_at":{"gte":"2024-01-01"}}&sort=-created_at
  4. Returns formatted results

API Specification: uctoo follows RESTFul style API. Query interface format is /api/{database}/{table}/{limit}/{page}, supporting Prisma ORM where condition queries (filter parameter) and orderBy sorting (sort parameter, minus sign indicates descending order). See uctoo API Design Specification for details.

Technical Implementation

  • Uses built-in http_request tool to make HTTP requests
  • Automatic Token management mechanism, no manual authentication handling required
  • Supports full CRUD operations

View the complete example: src/examples/uctoo_api_skill

🚀 No Cangjie Programming Language Required - JavaScript SDK Quick Integration

If you don't need to do secondary development on the runtime, you don't need to master or install the Cangjie programming language. Just use the multi-language SDK for quick integration.

Integration Steps

1. Install JavaScript SDK

npm install @opencangjie/skills

2. Install Runtime Binary Release

# Automatically download and install AgentSkills runtime
npx skills install-runtime

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

3. Configure AI Model Edit the .env file in the runtime directory:

  • Windows: %USERPROFILE%\.agentskills-runtime\release\.env
  • macOS/Linux: ~/.agentskills-runtime/release/.env
# Configure AI model (DeepSeek example)
MODEL_PROVIDER=deepseek
MODEL_NAME=deepseek-chat
DEEPSEEK_API_KEY=your_deepseek_api_key_here

4. Start Runtime

npx skills start

5. Install and Execute Skills

# Find skills
npx skills find database

# Install skill
npx skills add ./my-database-skill

# Execute skill
npx skills run my-database-skill -p '{"query": "Query user information"}'

Programming API Usage

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

const client = createClient({
  baseUrl: 'http://127.0.0.1:8080'
});

// List skills
const skills = await client.listSkills();

// Execute skill
const result = await client.executeSkill('database-skill', {
  query: 'Query users registered in the last week'
});

console.log(result.output);

Advantages

  • Progressive AI Capability: Gradually implement "+AI" capability in existing projects
  • Zero Learning Cost: No need to learn Cangjie programming language
  • Quick Integration: Integrate AI skills with just a few lines of code
  • Cross-Platform Support: Supports Windows, macOS, Linux

View the complete SDK documentation: sdk/javascript/README.md

Multi-Language SDK Usage Examples

JavaScript/TypeScript Example

import { AgentSkillsRuntime } from '@agentskills/runtime';

// Initialize runtime
const runtime = new AgentSkillsRuntime({
  baseUrl: 'http://localhost:8080',
  apiKey: 'your-api-key'
});

// Load and execute skill
const result = await runtime.executeSkill('example-skill', {
  name: 'Alice',
  age: 30
});

console.log('Execution result:', result);

Python Example

from agentskills import Runtime

# Initialize runtime
runtime = Runtime(
    base_url="http://localhost:8080",
    api_key="your-api-key"
)

# Load and execute skill
result = runtime.execute_skill("example-skill", {
    "name": "Alice",
    "age": 30
})

print(f"Execution result: {result}")

Java Example

import com.agentskills.Runtime;
import com.agentskills.SkillResult;

// Initialize runtime
Runtime runtime = Runtime.builder()
    .baseUrl("http://localhost:8080")
    .apiKey("your-api-key")
    .build();

// Load and execute skill
Map<String, Object> parameters = new HashMap<>();
parameters.put("name", "Alice");
parameters.put("age", 30);

SkillResult result = runtime.executeSkill("example-skill", parameters);
System.out.println("Execution result: " + result.getOutput());

Development Guide

Development Environment Setup

# Install dependencies
cjpm install

# Run tests
cjpm test

# Code checking
cjpm check

Project Structure

apps/agentskills-runtime/
├── cjpm.toml                            # Cangjie package configuration
├── build.cj                             # Build script
├── README.md                            # Project documentation
├── README_cn.md                         # Chinese project documentation
├── LICENSE                              # License information
├── docs/                                # Documentation
│   ├── architecture.md                  # Architecture overview
│   ├── quickstart.md                    # Quick start guide
│   ├── builtin-tools.md                 # Built-in tools documentation
│   └── api-reference.md                 # API reference
├── src/                                 # Source code
│   ├── app/                            # Application server module
│   │   ├── main.cj                     # Application main entry
│   │   ├── core/                       # Core components
│   │   │   ├── server/                 # HTTP/HTTPS server
│   │   │   ├── router/                 # Routing system
│   │   │   ├── middleware/             # Middleware
│   │   │   ├── http/                   # HTTP request/response
│   │   │   └── database/               # Database connection pool
│   │   ├── routes/                     # Route handlers
│   │   │   ├── skill/                  # Skill routes
│   │   │   └── tool/                   # Tool routes
│   │   ├── controllers/                # Controllers
│   │   ├── services/                   # Business services
│   │   ├── middlewares/                # Middleware implementations
│   │   └── registry/                   # Auto route registration
│   ├── skill/                          # Skill-related functionality
│   │   ├── domain/                     # Skill domain models
│   │   ├── infrastructure/             # Skill infrastructure components
│   │   └── application/                # Skill application services
│   ├── tool/                           # Tool module
│   │   ├── tool_dispatcher.cj          # Tool dispatcher
│   │   ├── permission_checker.cj       # Permission checker
│   │   ├── builtin_tools_registry.cj   # Built-in tools registry
│   │   └── file_tools.cj               # File tools implementation
│   ├── security/                       # Security module
│   │   ├── wasm_sandbox/               # WASM sandbox
│   │   └── access_control/             # Access control
│   ├── runtime/                        # Runtime core
│   ├── utils/                          # Utility functions
│   └── examples/                       # Example implementations
├── specs/                               # Specification documents
├── skills/                              # Example and reference skills
├── sdk/                                 # Multi-language SDK implementations
│   ├── javascript/                     # JavaScript/TypeScript SDK
│   ├── python/                         # Python SDK
│   ├── java/                           # Java SDK
│   ├── go/                             # Go SDK
│   ├── rust/                           # Rust SDK
│   └── csharp/                         # C# SDK
└── tests/                               # Test implementations

Dependencies

This implementation leverages existing libraries from the Cangjie ecosystem:

  • yaml4cj: For parsing YAML frontmatter from SKILL.md files
  • commonmark4cj: For processing markdown content in SKILL.md files according to CommonMark specification
  • stdx: For various utility functions

Multi-Language SDK Dependencies

Each language SDK depends on its respective ecosystem:

  • JavaScript: npm package manager, depending on mainstream AI libraries like langchain, openai-api
  • Python: pip package manager, depending on numpy, scikit-learn, transformers, etc.
  • Java: Maven/Gradle, depending on Spring Boot, Apache HttpComponents
  • Go: Go modules, depending on gin, gorilla/websocket, etc.
  • Rust: Cargo, depending on tokio, serde, reqwest, etc.
  • C#: NuGet, depending on .NET Core related packages

Basic Usage

import magic.agentskills.runtime

// Create skill runtime instance
let runtime = SkillRuntime()

// Load skill
let skill = runtime.loadSkill("path/to/skill")

// Execute skill
let result = skill.execute(params)

Skill Development Example

import magic.agentskills.runtime
import magic.agentskills.skill.domain.models.skill_manifest

// Define skill manifest
let manifest = SkillManifest {
    name: "example_skill",
    version: "1.0.0",
    description: "Example skill",
    author: "UCToo",
    parameters: [],
    implementation: "./skill_impl.cj"
}

// Create skill runtime
let runtime = SkillRuntime()

// Load and execute skill
let skill_result = runtime.execute(manifest, {})

Documentation Resources

Specification Driven Development Documents

Contribution Guide

Welcome to contribute to the project! Please check CONTRIBUTING.md for details.

Please refer to the contribution guidelines in the documentation.

Contribution Methods

  1. Code Contribution: Submit Pull Request to improve code
  2. Documentation Improvement: Help improve technical documentation and usage guides
  3. Issue Feedback: Report bugs or propose feature suggestions
  4. Skill Development: Develop new skill examples
  5. SDK Development: Develop SDKs for new programming languages
  6. Language Adapters: Develop new language adapters and bindings
  7. Ecosystem Integration: Integrate mainstream development tools and platforms

Development Process

# Fork the project
# Create feature branch
git checkout -b feature/your-feature

# Commit changes
git commit -am 'Add new feature'

# Push branch
git push origin feature/your-feature

# Create Pull Request

Project Status

  • Core runtime implementation
  • Security sandbox mechanism
  • Standard compatibility verification
  • Performance optimization
  • Production environment deployment
  • Community ecosystem building

Overall Process and Key Technologies

Core Workflow

  1. Skill Discovery and Loading

    • Automatically scan skill files in configuration directories
    • Parse YAML frontmatter of SKILL.md files
    • Validate skill format and dependency relationships

  2. Secure Execution Environment

    • WASM sandbox provides isolated execution environment
    • Capability-based permission control system
    • Resource usage monitoring and limitations

  3. Skill Execution and Orchestration

    • Dynamic parameter parsing and validation
    • Inter-skill dependency relationship management
    • Execution result collection and processing

Key Technology Components

  • Skill Manifest Parser: Parse and validate SKILL.md file format
  • WASM Runtime: Secure skill execution environment
  • Capability Manager: Fine-grained permission control system
  • Resource Monitor: Resource usage monitoring and quota management
  • Dependency Resolver: Skill dependency relationship resolution
  • Execution Orchestrator: Skill execution orchestration engine

License

This project uses the MIT license. See LICENSE file for details.

Contact Information

Acknowledgements

Thanks for the support from the following open source projects and communities:

Technical Standards

Programming Languages

Open Source Tools

References

AgentSkills Runtime - Making AI Development Simpler, Safer, and Faster!

About

AgentSkills Runtime is a runtime environment for the Agent Skills standard implemented based on the Cangjie programming language. It is a domestic technology stack implementation of the AgentSkills open standard, providing a secure and efficient AI agent skill execution environment. It aims to enable AgentSkills to run anywhere.

Resources

Readme
MIT license
Activity

Stars

2 stars

Watchers

0 watching

Forks

1 fork
Report repository

Releases

Packages

Contributors

Languages