> ## Documentation Index
> Fetch the complete documentation index at: https://docs.opencompany.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# AI Skills

> The Master Skill node aggregates skills that extend AI Agent and Chat Agent capabilities

# AI Skills

Skills are modular capabilities that guide an agent's behavior. In MachinaOs, you add skills through the **Master Skill** node, which aggregates many individual skills behind a single split-panel editor with enable/disable toggles. The Master Skill node connects to an agent's `input-skill` handle to inject the enabled skills' instructions and tools.

## How Skills Work

Each skill is defined in a Markdown file (`SKILL.md`) with YAML frontmatter that follows the [Agent Skills specification](https://agentskills.io/specification):

```yaml theme={null}
---
name: skill-name
description: Brief description for LLM visibility
allowed-tools: tool1 tool2
metadata:
  author: machina
  version: "1.0"
  category: general
  icon: "🔧"
  color: "#6366F1"
---

# Skill Instructions (Markdown)
Detailed instructions loaded when the skill is activated.
```

When a skill is enabled in a Master Skill node connected to an agent, the skill's instructions are added to the system prompt, and any tools it references (via `allowed-tools`) can be used when the matching Tool nodes are wired to the agent.

### Database as Source of Truth

Skill instructions follow a **DB-first architecture**:

1. **First load** reads from the `SKILL.md` file on disk and seeds it into the database
2. **After seeding**, the database is the single source of truth for all skill content
3. **User edits** in the UI are saved to the database only (not written back to disk)
4. **"Reset to Default"** reloads the original `SKILL.md` content from the filesystem

This ensures your customizations are always preserved in the database while the original `SKILL.md` files remain as defaults.

## The Master Skill Node

The Master Skill node (category: **AI Tools**) is the single node you use to attach skills to an agent. It has no Run button and no input/output data panels; it is a passive aggregator that the connected agent reads during execution.

### Connecting

The Master Skill node's **Skill** output connects to an agent's **input-skill** handle (diamond shape). You can also connect regular Tool nodes and a Simple Memory node to the same agent.

```
[Master Skill] --(skill handle)--> [AI Agent] --> [Output]
```

### Split-Panel Editor

Selecting a Master Skill node opens a split-panel editor:

* **Folder dropdown** at the top selects a skill folder (for example, `assistant`, `web_agent`, `coding_agent`).
* **Left panel** lists the skills in that folder with a checkbox for each. Enabled skills are counted in a badge, and you can search the list.
* **Right panel** shows the selected skill's Markdown instructions in an editor, with a **Reset to Default** button.

Enabled skills persist across all folders, not just the currently selected one, so switching folders never disables skills you turned on elsewhere.

### Parameters

<ParamField path="skill_folder" type="string" default="assistant">
  The skill folder currently shown in the editor's dropdown.
</ParamField>

<ParamField path="skills_config" type="object">
  A map of skill name to its state (`enabled`, `instructions`, `isCustomized`). This is populated by the split-panel editor as you toggle and edit skills.
</ParamField>

***

## Built-in Skill Folders

Skills are organized in subfolders under `server/skills/`. Each top-level folder appears as an option in the Master Skill node's folder dropdown. The current folders are:

<CardGroup cols={2}>
  <Card title="assistant" icon="sparkles">
    General assistant behavior — assistant personality, memory, write-todos, compaction, humanify, agent-builder, subagent
  </Card>

  <Card title="web_agent" icon="globe">
    Web automation — HTTP requests, browser, DuckDuckGo/Brave/Serper/Perplexity search, Apify, Crawlee scraper, proxy config
  </Card>

  <Card title="coding_agent" icon="code">
    Code and files — Python, Monty (sandboxed Python), JavaScript, file read/modify, filesystem search
  </Card>

  <Card title="terminal" icon="terminal">
    Shell and processes — shell (Nushell), process manager, bash, PowerShell, WSL
  </Card>

  <Card title="social_agent" icon="message">
    Social messaging — WhatsApp send, WhatsApp DB, Twitter send/search/user
  </Card>

  <Card title="productivity_agent" icon="briefcase">
    Google Workspace — Gmail, Calendar, Drive, Sheets, Tasks, Contacts
  </Card>

  <Card title="task_agent" icon="list-check">
    Task automation — timer, cron scheduler, task manager
  </Card>

  <Card title="travel_agent" icon="map">
    Location — geocoding, nearby places
  </Card>

  <Card title="android_agent" icon="mobile">
    Android device control — battery, WiFi, Bluetooth, apps, camera, sensors, screen control, location
  </Card>

  <Card title="autonomous" icon="robot">
    Autonomous patterns — agentic loop, code mode, progressive discovery, error recovery, multi-tool orchestration
  </Card>

  <Card title="payments_agent" icon="credit-card">
    Payments — Stripe
  </Card>

  <Card title="rlm_agent" icon="brain">
    Recursive Language Model reasoning
  </Card>
</CardGroup>

<Info>
  The exact skills within each folder evolve over time. Use the folder dropdown in the Master Skill editor to see the live list scanned from disk.
</Info>

***

## Skill Content Editor

The right panel of the Master Skill editor is a built-in Markdown editor for viewing and editing a skill's instructions:

1. Select a Master Skill node and pick a folder
2. Click a skill in the left panel to load its instructions on the right
3. Make changes as needed
4. Changes are saved to the database; click **Reset to Default** to restore the original `SKILL.md`

<Info>
  Edits are saved to the database only. The original `SKILL.md` file on disk is not modified.
</Info>

***

## Custom Skills

You can create your own skills directly from the Master Skill editor.

<Steps>
  <Step title="Open the Master Skill editor">
    Select a Master Skill node connected to your agent.
  </Step>

  <Step title="Create a new skill">
    Click the **+** button in the left panel. Provide a name, display name, and instructions.
  </Step>

  <Step title="Enable and use it">
    Toggle the new skill on. Its enabled state and instructions are saved to the node and persist across panel close and reload.
  </Step>
</Steps>

User-created skills are stored in the database and can be created, edited, and deleted inline. They load through the same path as built-in skills, so their instructions appear in the editor the same way.

### SKILL.md Format for Custom Skills

```yaml theme={null}
---
name: my-custom-skill
description: Description visible to the LLM
allowed-tools: httpRequest calculatorTool
metadata:
  author: your-name
  version: "1.0"
  category: general
  icon: "🔧"
  color: "#6366F1"
---

# Custom Skill Instructions

You are a specialized assistant that...

## Available Actions
- Action 1: Description
- Action 2: Description

## Guidelines
- Guideline 1
- Guideline 2
```

***

## Skills and Tools Work Together

A skill's `allowed-tools` list tells the agent which tools it may use for that skill's tasks. The tools themselves come from Tool nodes wired to the agent's `input-tools` handle. In practice:

* **Skill** — teaches the agent *how* and *when* to act (instructions in the system prompt)
* **Tool** — gives the agent the actual capability to act (the executable node)

```
[Master Skill] --(skill handle)-------+
                                       +---> [AI Agent] --> [Output]
[WhatsApp Send tool] --(tools handle)-+
[HTTP Request tool] --(tools handle)--+
```

<Warning>
  Skills describe capabilities, but the corresponding Tool nodes must be connected to the agent's tools handle for the agent to actually perform those actions.
</Warning>

***

## Tips

<Tip>
  Enable only the skills you need. Too many skills can dilute the agent's focus and grow the system prompt.
</Tip>

<Tip>
  Use custom skills to create domain-specific assistants tailored to your use case.
</Tip>

<Tip>
  Skill instructions should be clear and specific about when to use each capability.
</Tip>

***

## Related

<CardGroup cols={2}>
  <Card title="AI Agents" icon="robot" href="/nodes/ai-agent">
    Connect the Master Skill node to an agent
  </Card>

  <Card title="AI Tools" icon="screwdriver-wrench" href="/nodes/tools">
    Tool nodes that skills reference in allowed-tools
  </Card>

  <Card title="AI Models" icon="brain" href="/nodes/ai-models">
    LLM providers for AI Agent and Chat Agent
  </Card>

  <Card title="WhatsApp" icon="message" href="/nodes/whatsapp">
    WhatsApp messaging nodes
  </Card>
</CardGroup>