Skills

Skills are the actions an agent can perform. They transform an agent from a text generator into an active participant that can interact with systems, fetch data, and accomplish real tasks.

What are Skills?

Skills are executable modules that agents can invoke to:

• Execute shell commands
• Run Python scripts
• Fetch web content
• Manage files
• Send notifications
• And much more...

Skill Architecture

┌─────────────────────────────────────────────────┐
│                  Skill Manager                   │
├─────────────────────────────────────────────────┤
│  ┌─────────────────────────────────────────┐   │
│  │           Skill Registry                 │   │
│  │  ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐       │   │
│  │  │host │ │web  │ │git  │ │mcps │  ...  │   │
│  │  │shell│ │crawl│ │     │ │     │       │   │
│  │  └─────┘ └─────┘ └─────┘ └─────┘       │   │
│  └─────────────────────────────────────────┘   │
├─────────────────────────────────────────────────┤
│  ┌─────────────────────────────────────────┐   │
│  │          Skill Executors                 │   │
│  │  ┌────────┐ ┌────────┐ ┌────────┐      │   │
│  │  │ Shell  │ │ Python │ │  MCP   │      │   │
│  │  └────────┘ └────────┘ └────────┘      │   │
│  └─────────────────────────────────────────┘   │
└─────────────────────────────────────────────────┘

Skill Types

Type	Description	Example
Shell	Bash/shell scripts	host_shell, git
Python	Python scripts	host_python, web_crawler
MCP	Model Context Protocol tools	External APIs
Native	Rust-based (built-in)	Core framework functions

How Agents Use Skills

Invocation Format

Agents invoke skills using XML tags:

<invoke name="skill_name">["arg1", "arg2"]</invoke>

For MCP skills with named parameters:

<invoke name="mcp_skill">{"param": "value"}</invoke>

Example Flow

User: "List all Python files in my project"

Agent thinks:
  I need to use the host_shell skill to find Python files.

Agent invokes:
  <invoke name="host_shell">["find . -name '*.py' -type f"]</invoke>

System executes:
  → Runs the find command
  → Captures stdout/stderr
  → Returns result

Agent responds:
  I found 23 Python files in your project:
  - src/main.py
  - src/utils.py
  ...

Built-in Skills

System Skills

Skill	Description
host_shell	Execute shell commands
host_python	Run Python scripts
computer_control	macOS accessibility automation

Network Skills

Skill	Description
web_crawler	Fetch and parse web pages
browse_network	Network operations

Git Skills

Skill	Description
git	Git operations (clone, commit, push, etc.)

Communication Skills

Skill	Description
telegram_notify	Send Telegram notifications
delegate_task	Delegate work to other agents

Scheduling Skills

Skill	Description
scheduler	Create cron-based heartbeats
modify_schedule	Modify scheduled jobs
remove_schedule	Remove scheduled jobs

Skill Management

Skill	Description
create_skill	Create a new skill
install_skill	Install a skill from source
modify_skill	Modify an existing skill
remove_skill	Remove a skill
upgrade_skill	Upgrade a skill
list_skills	List available skills
read_skill	Read skill source code

Vault Skills

Skill	Description
manage_vault	Manage encrypted secrets

MCP Skills

Skill	Description
mcp	Call MCP server tools

Dev Skills

Skill	Description	Mode
evolve_core	Self-modify framework code	Dev only

See Built-in Skills Reference for detailed documentation.

Custom Skills

Create your own skills to extend agent capabilities.

Skill Structure

skills/
└── my_skill/
    ├── manifest.toml    # Skill metadata
    └── run.sh           # Entry point

manifest.toml

name = "my_skill"
description = "What this skill does"
version = "1.0.0"
run_command = "sh"
entrypoint = "run.sh"
needs_network = false
needs_fs_read = true
needs_fs_write = false
needs_env = false

run.sh

#!/bin/bash
# Arguments are passed as JSON array to stdin

# Read arguments
read -r args

# Process
result=$(echo "$args" | jq -r '.[0]')

# Output (returned to agent)
echo "Processed: $result"

Installing Custom Skills

Method 1: Direct Placement

mkdir -p ~/.moxxy/agents/default/skills/my_skill
# Add manifest.toml and run.sh

Method 2: Via Agent

Create a skill called "my_skill" that does X

Method 3: From Repository

Install the skill from https://github.com/user/moxxy-skills/tree/main/my_skill

See Custom Skills for detailed guide.

MCP Integration

Connect external tools via Model Context Protocol:

# Add MCP server via web dashboard
# Settings → MCP Servers → Add Server

MCP tools are automatically registered as agent skills with [MCP] prefix.

See MCP Integration for details.

Skill Permissions

Skills declare their requirements in the manifest:

needs_network = true   # Internet access
needs_fs_read = true   # Filesystem read
needs_fs_write = true  # Filesystem write
needs_env = true       # Environment variables

In WASM mode, these are enforced through capability-based permissions.

Skill Execution

Native Mode

Skills run directly on the host:

┌──────────┐     ┌──────────┐     ┌──────────┐
│  Agent   │ ──▶ │  Skill   │ ──▶ │   Host   │
│ Request  │     │ Executor │     │   OS     │
└──────────┘     └──────────┘     └──────────┘

WASM Mode

Skills run in a sandboxed environment:

┌──────────┐     ┌──────────┐     ┌──────────┐     ┌──────────┐
│  Agent   │ ──▶ │  Skill   │ ──▶ │   WASM   │ ──▶ │   Host   │
│ Request  │     │ Executor │     │ Runtime  │     │   OS     │
└──────────┘     └──────────┘     └──────────┘     └──────────┘
                                      │
                                      ▼
                              ┌──────────────┐
                              │ Capabilities │
                              │   Check      │
                              └──────────────┘

Best Practices

Skill Design

1. Single Purpose - Each skill does one thing well
2. Clear Input/Output - Document expected arguments
3. Error Handling - Return meaningful error messages
4. Idempotent - Safe to run multiple times

Security

1. Minimal Permissions - Only request needed capabilities
2. Input Validation - Sanitize all inputs
3. Output Sanitization - Don't leak sensitive data
4. Use WASM - Sandbox untrusted operations

Performance

1. Timeout - Set reasonable execution limits
2. Streaming - Stream large outputs
3. Caching - Cache repeated operations

Troubleshooting

Skill Not Found

1. Check skill is registered: moxxy run --agent default --prompt "List your skills"
2. Verify manifest.toml syntax
3. Check file permissions

Permission Denied

1. Check manifest capability flags
2. Verify WASM configuration
3. Check host permissions

Timeout

1. Increase timeout in configuration
2. Optimize skill implementation
3. Consider async operations

Unexpected Output

1. Check skill exit code
2. Verify stdout/stderr capture
3. Test skill in isolation