Skills & Primitives

Moxxy has two distinct concepts for agent capabilities: primitives (built-in tool calls) and skills (composable Markdown instructions).

Primitives

Primitives are the 85 built-in tools that agents invoke through standard LLM tool_use/function calling. They are implemented in Rust as part of the gateway and are always available (subject to per-agent allowlists and denylists).

Primitive Categories

Filesystem

Primitive	Description
fs.read	Read file contents
fs.write	Write content to a file
fs.list	List directory contents
fs.remove	Remove a file or directory
fs.cd	Change working directory

Git

Primitive	Description
git.init	Initialize a git repository
git.clone	Clone a repository
git.status	Show working tree status
git.commit	Create a commit
git.push	Push to remote
git.checkout	Switch branches or restore files
git.pr_create	Create a pull request
git.fork	Fork a repository
git.worktree_add	Add a git worktree
git.worktree_list	List git worktrees
git.worktree_remove	Remove a git worktree

Web

Primitive	Description
browse.fetch	HTTP fetch with CSS selector extraction
browse.extract	Extract structured data from web content

Shell

Primitive	Description
shell.exec	Execute a shell command (allowlist enforced)

HTTP

Primitive	Description
http.request	Make an HTTP request (domain-gated)

Memory

Primitive	Description
memory.store	Store information in long-term memory
memory.recall	Semantic search over long-term memory
memory.stm_read	Read short-term memory
memory.stm_write	Write to short-term memory

Skills Management

Primitive	Description
skill.create	Create a new skill
skill.execute	Execute a skill
skill.find	Search for skills
skill.get	Get skill details
skill.list	List available skills
skill.remove	Remove a skill
skill.validate	Validate a skill definition

Vault

Primitive	Description
vault.set	Store a secret
vault.get	Retrieve a secret
vault.delete	Delete a secret
vault.list	List secret keys

Webhooks

Primitive	Description
webhook.register	Register a webhook endpoint
webhook.list	List webhooks
webhook.listen	Listen for webhook events
webhook.delete	Delete a webhook
webhook.update	Update a webhook
webhook.rotate	Rotate webhook secret

Notifications

Primitive	Description
notify.cli	Send a CLI notification
channel.notify	Send a notification through a channel

Heartbeats

Primitive	Description
heartbeat.create	Create a scheduled heartbeat
heartbeat.list	List heartbeats
heartbeat.update	Update a heartbeat
heartbeat.disable	Disable a heartbeat
heartbeat.delete	Delete a heartbeat

User Interaction

Primitive	Description
user.ask	Prompt the user for input
agent.respond	Send a response to the user

Agent Management

Primitive	Description
agent.spawn	Spawn a sub-agent
agent.status	Check agent status
agent.list	List agents
agent.stop	Stop an agent
agent.dismiss	Dismiss a sub-agent
agent.self.get	Get own agent info
agent.self.update	Update own configuration
agent.self.persona_read	Read own persona
agent.self.persona_write	Update own persona

Allowlist Management

Primitive	Description
allowlist.list	List allowlist entries
allowlist.add	Add to allowlist
allowlist.remove	Remove from allowlist
allowlist.deny	Add to denylist
allowlist.undeny	Remove from denylist

Configuration

Primitive	Description
config.get	Read a configuration value
config.set	Set a configuration value

MCP (Model Context Protocol)

Primitive	Description
mcp.list	List connected MCP servers
mcp.connect	Connect to an MCP server
mcp.disconnect	Disconnect from an MCP server
mcp.tool	Invoke an MCP tool

Hive (Swarm Orchestration)

Primitive	Description
hive.create	Create a hive
hive.recruit	Recruit a worker into a hive
hive.disband	Disband a hive
hive.task_create	Create a task on the board
hive.task_claim	Claim a task
hive.task_complete	Mark a task complete
hive.task_fail	Mark a task failed
hive.task_review	Review a completed task
hive.task_list	List tasks on the board
hive.signal	Send a signal to hive members
hive.board_read	Read the hive task board
hive.propose	Propose a decision for voting
hive.vote	Vote on a proposal
hive.resolve_proposal	Resolve a voted proposal
hive.assign	Assign a task to a worker
hive.aggregate	Aggregate results from workers

Reply

Primitive	Description
reply	Send a reply in the current conversation

Invocation

Agents invoke primitives through standard LLM tool_use/function calling. The LLM provider returns structured tool call requests, and the gateway's Executor dispatches them to the appropriate primitive handler.

There is no custom XML invoke format. Primitives use the native tool calling mechanism of whichever LLM provider is configured (Anthropic, OpenAI, Ollama, or OpenAI-compatible).

Allowlists and Denylists

Each agent has an allowlist.yaml file that controls which primitives it can access:

allowed:
  - fs.read
  - fs.write
  - shell.exec
  - memory.*
denied:
  - vault.delete

Glob patterns are supported (e.g., git.* matches all git primitives). Agents can also modify their own allowlists at runtime via the allowlist.* primitives.

Skills

Skills are Markdown files with YAML frontmatter that define higher-level agent capabilities. Unlike primitives, skills are not code -- they are structured instructions that tell the agent how to compose primitives to accomplish complex tasks.

Skill Format

---
id: code-review
name: Code Review
version: 1.0.0
inputs_schema:
  type: object
  properties:
    repo_path:
      type: string
      description: Path to the repository to review
    focus_areas:
      type: string
      description: Specific areas to focus on (optional)
allowed_primitives:
  - fs.read
  - fs.list
  - git.status
  - shell.exec
  - reply
safety_notes: >
  This skill only reads files and runs safe git/shell commands.
  It does not modify any files.
---

# Code Review

Review the code in the given repository for quality, bugs, and best practices.

## Steps

1. Use `fs.list` to understand the project structure
2. Use `git.status` to check for uncommitted changes
3. Use `fs.read` to examine key source files
4. Analyze the code for:
   - Potential bugs and edge cases
   - Code style and consistency
   - Performance concerns
   - Security issues
5. Use `reply` to provide a structured review report

Key Differences from Primitives

Aspect	Primitives	Skills
Implementation	Rust code in the gateway	Markdown files with YAML frontmatter
Count	85 built-in	Extensible (9 examples included)
Invocation	LLM tool_use/function calling	skill.execute primitive
Approval	Always available (subject to allowlist)	Start quarantined, require approval
Purpose	Atomic operations	Composed workflows with instructions

Quarantine and Approval

All skills start in a quarantined state when installed. A quarantined skill cannot be executed until it is approved. This safety mechanism ensures that skills are reviewed before being used, especially those created by agents or installed from external sources.

Example Skills

Moxxy includes 9 example skills:

Skill	Description
code-review	Review code for quality and bugs
web-researcher	Research topics using web browsing
git-workflow	Standard git branching and PR workflow
And 6 more	Various development and research workflows

Installing Skills

Skills can be installed via the API:

curl -X POST http://127.0.0.1:3000/v1/agents/{id}/skills/install \
  -H "Authorization: Bearer mox_your_token" \
  -H "Content-Type: application/json" \
  -d '{
    "skill_content": "---\nid: my-skill\nname: My Skill\n..."
  }'

Or agents can create skills themselves using the skill.create primitive:

Create a new skill called "deploy-checker" that verifies deployment readiness
by checking git status, running tests, and reviewing environment configuration.

Managing Skills

Skills are managed through primitives:

Primitive	Purpose
skill.create	Create a new skill definition
skill.execute	Run a skill
skill.find	Search for skills by name or description
skill.get	Get full skill details
skill.list	List all installed skills
skill.remove	Remove a skill
skill.validate	Validate a skill's YAML and Markdown structure

MCP Integration

Connect external tools via Model Context Protocol:

# Agents can connect to MCP servers at runtime
# using the mcp.connect primitive

MCP tools are invoked through the mcp.tool primitive, which dispatches to the connected MCP server.

Security Model

Primitive-Level Controls

• Allowlists - Per-agent YAML configuration restricting available primitives
• Domain gating - http.request only reaches approved domains
• Command allowlists - shell.exec only runs approved commands
• PathPolicy - Filesystem primitives are confined to the agent's workspace

Skill-Level Controls

• Quarantine - New skills start disabled until approved
• Allowed primitives - Skills declare which primitives they need in frontmatter
• Safety notes - Skills document their safety characteristics
• Validation - skill.validate checks skill structure before installation