Skill Module

What is Skill?

Skill is a modular mechanism in the MaiAgent platform for encapsulating AI assistant professional capabilities. Unlike Function Calling which allows LLMs to call a single tool, Skill packages a set of Instructions, Tools, and Resources into a reusable capability unit, enabling AI assistants to dynamically unfold complete task execution workflows during conversations.

In simple terms:

• Function Calling / Tools: LLM calls a single API or function

• Skill: LLM unfolds a complete set of SOP instructions and calls multiple tools as needed during the process

┌─────────────────────────────────┐
│           Skill                 │
│                                 │
│  ┌───────────────────────┐      │
│  │  Instructions (SOP)   │      │
│  │  - Trigger conditions │      │
│  │  - Execution steps    │      │
│  │  - Response format    │      │
│  └───────────────────────┘      │
│                                 │
│  ┌──────┐ ┌──────┐ ┌──────┐    │
│  │Tool A│ │Tool B│ │Tool C│    │
│  └──────┘ └──────┘ └──────┘    │
│                                 │
│  ┌───────────────────────┐      │
│  │  Resources (files)    │      │
│  └───────────────────────┘      │
└─────────────────────────────────┘

---

How Skill Works

Overall Architecture

The operation of Skill in the MaiAgent system involves the following core components:

Component	Description
Skill Model	Stores skill name, description, instruction content, and attached tool associations
ChatbotSkill	Many-to-many association between AI assistants and Skills (Junction Model)
SkillExpandTool	Built-in system tool responsible for dynamically expanding skill instructions during conversations
LoadSkillTool	Built-in system tool responsible for dynamically loading skill-attached tools
SkillFileParser	Parses uploaded .skill / .zip files, extracts SKILL.md and resources

Workflow

User inquiry
    │
    ▼
AI assistant receives message
    │
    ▼
LLM analyzes intent, matches descriptions of bound skills
    │
    ├─ Skill matched → Call SkillExpandTool
    │                    │
    │                    ▼
    │              Expand complete skill instruction content
    │              + List available attached tools
    │                    │
    │                    ▼
    │              LLM executes step by step according to instructions
    │              Calls LoadSkillTool to load tools as needed
    │                    │
    │                    ▼
    │              Tool execution results returned to LLM
    │                    │
    │                    ▼
    │              LLM generates response according to instruction format
    │
    └─ Not matched → Regular conversation response

1. Skill Expansion

When an AI assistant determines that a user's question should be handled by a particular skill, the system calls SkillExpandTool:

• Input: Skill name (skill_name)

• Processing: Query skill by name, retrieve complete instruction content and attached tool list

• Output: Instruction content in Markdown format + available tool list

{
  "name": "expand_skill",
  "arguments": {
    "skill_name": "休假天數計算"
  }
}

2. Tool Dynamic Loading

After skill expansion, when the LLM needs to call tools during instruction execution, it dynamically loads them via LoadSkillTool:

• Input: Tool name (tool_name)

• Processing: Query tool (supports MCP tools and API tools, case-insensitive)

• Output: Tool's ID, name, description, and availability status

This dynamic loading mechanism ensures that skill tools don't need to be fully loaded into the conversation context in advance, reducing token consumption.

---

SKILL.md Specification

The core definition file for Skill is SKILL.md, using YAML Frontmatter + Markdown content format:

---
name: Skill name
description: Skill description (determines when AI triggers this skill)
---

# Skill title

## Trigger Conditions
Triggered when user asks XXX related questions.

## Execution Steps

### Step 1: Confirm Information
Guide user to provide necessary information...

### Step 2: Query Data
Use retrieve_text_nodes to search knowledge base...

### Step 3: Generate Response
Reply according to the following format:
- ① Applicable regulations
- ② Calculation results
- ③ Reference examples

Frontmatter Fields

Field	Required	Description
name	Yes	Skill name, must be unique within organization
description	Yes	Skill description, used by LLM to determine whether to trigger this skill

Instruction Writing Guidelines

1. Clear trigger conditions: Clearly define "when to trigger" and "when not to trigger" in description and instructions

2. Structured steps: Use numbered steps (Step 1, Step 2...) for LLM to execute sequentially

3. Tool call guidance: Explicitly specify which tool to use and query strategy in steps

4. Response format definition: Define final response format using templates or tables to ensure output consistency

5. Error prevention checklist: Add checklist at end of instructions for LLM self-verification

---

Skill Package

File Structure

Uploaded .skill or .zip files should contain the following structure:

my-skill.skill (ZIP format)
├── SKILL.md          # Required: Skill definition file
├── reference.pdf     # Optional: Reference materials
├── template.xlsx     # Optional: Template files
└── examples/         # Optional: Example data
    └── case1.json

Security Validation

The system performs the following security checks when parsing skill packages:

• Compression ratio check: Maximum 100:1 to prevent ZIP bomb attacks

• Path traversal protection: Block ../ and other path injection attempts

• File size limit: Based on organization's upload limit (default 100 MB)

• SKILL.md validation: Must exist and contain valid name and description

Storage Architecture

S3 storage path:
media/skills/{organization_id}/{skill_id}/package.zip    # Skill package
media/skills/{organization_id}/{skill_id}/resources/     # Resource files

---

API Endpoints

Skill CRUD

Method	Endpoint	Description
GET	/api/v1/skills/	List all skills in organization (supports pagination, search)
POST	/api/v1/skills/	Manually create skill
GET	/api/v1/skills/{id}/	Get skill details
PATCH	/api/v1/skills/{id}/	Update skill
DELETE	/api/v1/skills/{id}/	Delete skill (includes S3 cleanup)

Skill Package Operations

Method	Endpoint	Description
POST	/api/v1/skills/upload/	Upload .skill / .zip to create skill
POST	/api/v1/skills/{id}/reupload/	Re-upload to replace skill package
GET	/api/v1/skills/{id}/export/	Export skill as .skill file
GET	/api/v1/skills/{id}/package-structure/	View skill package file structure

Resource Management (Nested Routes)

Method	Endpoint	Description
GET	/api/v1/skills/{id}/resources/	List skill resource files
POST	/api/v1/skills/{id}/resources/	Upload resource (manually created skills only)
DELETE	/api/v1/skills/{id}/resources/{rid}/	Delete resource (manually created skills only)
GET	/api/v1/skills/{id}/resources/{rid}/download/	Download resource file

Skill Creation Examples

Manual creation:

POST /api/v1/skills/
{
  "name": "退貨處理流程",
  "description": "當客戶要求退貨、換貨時觸發。查詢訂單、確認退貨資格、建立退貨單。",
  "instructions": "# 退貨處理\n\n## Step 1：查詢訂單\n...",
  "attached_tool_ids": [
    "uuid-of-order-query-tool",
    "uuid-of-return-api-tool"
  ]
}

Upload skill package:

curl -X POST /api/v1/skills/upload/ \
  -F "file=@my-skill.skill" \
  -F "attached_tool_ids=[\"uuid-1\",\"uuid-2\"]"

---

Binding Skills to AI Assistants

Skills establish many-to-many associations with AI assistants through the ChatbotSkill junction model:

• One AI assistant can bind multiple skills

• One skill can be used by multiple AI assistants

• Bind/unbind operations are recorded in the ChatbotSkillEvent history tracking table

AI Assistant A ──┬── Skill: Return Processing
                 ├── Skill: Product Consultation
                 └── Skill: Email Sending

AI Assistant B ──┬── Skill: Product Consultation  ← Shared
                 └── Skill: Meeting Query

---

Unique Advantages of MaiAgent Skill

1. Instruction and Tool Decoupling

Skill instructions and attached tools are managed independently, allowing instruction logic to be adjusted at any time without affecting tool settings, and vice versa. This makes skill maintenance and iteration more flexible.

2. Dynamic Expansion Mechanism

Skill instructions are not preloaded into conversation context but are dynamically expanded when the LLM determines they are needed. This significantly reduces token consumption per conversation, especially suitable for AI assistants with numerous bound skills.

3. Skill Package Ecosystem

Through the .skill file format, skills can be shared and imported between different organizations. Enterprises can build internal skill libraries or package best practices as skill packages for distribution to partners.

4. Complete Version Control

Skills created via upload support re-upload (Reupload), allowing skill package content to be updated without deleting the original skill. The system completely replaces the skill package and resource files to ensure version consistency.

5. Permission Control

Skill access is controlled by the chatbot_skill_access permission. Organization administrators can precisely manage who can create, edit, and delete skills through the role permission system.