Skills

Skills are reusable capabilities that agents can discover and load on demand using the LoadSkill tool.

Skills give agents a way to discover and load detailed capability documentation at runtime, without those details consuming context tokens up front. When you attach a skill to an agent, NexAU registers it in the agent’s skill registry and injects a LoadSkill tool. The agent sees a short description of each available skill and can call LoadSkill whenever it needs the full details.

NexAU supports two types of skills:

• Folder-based skills — a directory with a SKILL.md file and any supporting files (scripts, templates, data).
• Tool-based skills — a regular tool marked with as_skill=True.

Both types work together and are discoverable through the same LoadSkill mechanism.

Folder-based skills

Folder-based skills are self-contained directories. Each skill folder must include a SKILL.md file with YAML frontmatter.

Folder structure

my_project/
└── skills/
    ├── data-analysis/
    │   ├── SKILL.md
    │   ├── scripts/
    │   │   └── analyzer.py
    │   └── templates/
    │       └── report_template.md
    └── web-scraping/
        ├── SKILL.md
        └── utils.py

Writing a SKILL.md file

The SKILL.md file must start with YAML frontmatter containing name and description. Everything after the closing --- becomes the skill’s detailed documentation — the content that LoadSkill returns to the agent.

SKILL.md

---
name: data-analysis
description: Advanced data analysis and visualization capabilities
---

# Data Analysis Skill

This skill provides comprehensive data analysis capabilities including:

## Features

- Statistical analysis
- Data visualization
- Report generation
- Export to multiple formats

## Usage

To use this skill, import the analysis functions from the scripts/ directory:

    from scripts.analyzer import analyze_data
    results = analyze_data(data)

## Files

- scripts/analyzer.py — Main analysis functions
- templates/report_template.md — Report template

## Requirements

- pandas >= 1.5.0
- matplotlib >= 3.5.0

The description field is the short text shown in the skill registry. Keep it to one line — it’s what the agent reads before deciding whether to call LoadSkill.

Attaching folder-based skills to an agent

Python

from nexau import Agent, AgentConfig

agent = Agent(
    config=AgentConfig(
        name="data_analyst",
        llm_config={"model": "gpt-4o-mini"},
        skills=["skills/data-analysis", "skills/web-scraping"],
    )
)

YAML

type: agent
name: data_analyst
llm_config:
  model: gpt-4o-mini
skills:
  - skills/data-analysis
  - skills/web-scraping

Tool-based skills

You can mark any tool as a skill by setting as_skill=True. This makes the tool discoverable through the skill registry, with the skill_description appearing up front and the full description available through LoadSkill.

1. Create the tool with as_skill=True

   from nexau import Tool
   
   code_generator = Tool(
       name="generate_code",
       description="Generates code based on specifications",
       input_schema={
           "type": "object",
           "properties": {
               "language": {"type": "string", "description": "Programming language"},
               "specification": {"type": "string", "description": "Code specification"}
           },
           "required": ["language", "specification"]
       },
       implementation=generate_code_implementation,
       as_skill=True,
       skill_description="Code generation skill for multiple programming languages including Python, JavaScript, Java, and C++"
   )
   

   When as_skill=True, skill_description is required. It serves as the short discovery text in the registry. The full description is what LoadSkill returns.

2. Add the tool to your agent

   from nexau import Agent, AgentConfig
   
   agent = Agent(
       config=AgentConfig(
           name="coding_assistant",
           llm_config={"model": "gpt-4o-mini"},
           tools=[code_generator],
       )
   )
   

   NexAU automatically registers the tool as a skill, adds LoadSkill to the agent’s tool list, and includes the skill in the registry.

Tool-based skills in YAML

generate_code.tool.yaml

type: tool
name: generate_code
description: Generates code based on specifications
input_schema:
  type: object
  properties:
    language:
      type: string
      description: Programming language
    specification:
      type: string
      description: Code specification
  required:
    - language
    - specification
as_skill: true
skill_description: Code generation skill for multiple programming languages

The behavior of tool-based skills differs by tool_call_mode. In xml mode, only skill_description is shown up front. In structured mode, the full JSON Schema is also included in the tool definition, and LoadSkill returns the full description. Treat skill_description as discovery text and description as detailed operational guidance.

Combining both types

You can use folder-based and tool-based skills together in the same agent:

Python

from nexau import Agent, AgentConfig, Tool

web_search = Tool(
    name="web_search",
    description="Search the web for information",
    input_schema={
        "type": "object",
        "properties": {
            "query": {"type": "string", "description": "Search query"}
        },
        "required": ["query"]
    },
    implementation=search_implementation,
    as_skill=True,
    skill_description="Web search capability with advanced filtering"
)

agent = Agent(
    config=AgentConfig(
        name="research_assistant",
        llm_config={"model": "gpt-4o-mini"},
        skills=[
            "skills/data-analysis",    # Folder-based skill
            "skills/report-writing"    # Folder-based skill
        ],
        tools=[
            web_search  # Tool-based skill
        ],
    )
)

YAML

type: agent
name: research_assistant
llm_config:
  model: gpt-4o-mini

# Folder-based skills
skills:
  - skills/data-analysis
  - skills/report-writing

# Tool-based skills (and regular tools)
tools:
  - name: web_search
    yaml_path: tools/web_search.tool.yaml
    binding: my_module:search_implementation

When to use each type

Use folder-based skills when...

• The skill requires extensive documentation that would be wasteful to include in every prompt
• The skill spans multiple files — scripts, templates, reference data
• You want to version-control or share the skill across multiple projects
• The skill documentation is long enough to benefit from lazy loading

Use tool-based skills when...

• The skill is a single, well-defined capability already implemented as a tool
• The tool’s description is sufficient documentation for the agent to use it
• You want the skill to be immediately callable without a separate LoadSkill step
• You’re exposing existing tools for discovery without restructuring your project

Keep skill_description (and the description field in SKILL.md frontmatter) short — one sentence is ideal. The agent uses these to decide whether to load a skill; the full documentation only gets loaded when needed.