📝 SKILL.md File Format

The heart of HippoX’s skill system is the SKILL.md file. Simply write a markdown file with YAML frontmatter, place it in a subdirectory under your skills folder, and HippoX automatically loads it.

📁 File Structure

Example skills directory layout:

• Folder: skills
  • Subfolder: calculator
    • File: SKILL.md
  • Subfolder: data-analyzer
    • File: SKILL.md
  • Subfolder: email-sender
    • File: SKILL.md
  • Subfolder: weather
    • File: SKILL.md

Each skill lives in its own subdirectory. The directory name becomes the skill identifier.

📝 Basic SKILL.md Template

Every SKILL.md file has two parts: YAML frontmatter (between three dash lines) and markdown instructions.

Start of file:

Three dash lines name: my-skill description: What this skill does in one sentence version: 1.0.0 author: Your Name Three dash lines

Then markdown:

Hash sign Hash sign Hash sign Hash sign Hash sign Hash sign My Skill

Natural language instructions for the AI go here.

Hash sign Hash sign Hash sign Hash sign Instructions

Step 1: Do this first Step 2: Then do that Step 3: Finally return the result

Hash sign Hash sign Hash sign Hash sign Examples

User: “example input” Response: “expected output”

📋 Frontmatter Fields

Required Fields

Optional Fields

📥 Parameters

Define parameters that the skill accepts. The LLM will extract these from user input.

Start of parameters section:

parameters: space hyphen space name: file_path space space space space type: string space space space space description: Path to the file to analyze space space space space required: true space space space space example: ”./data/sales.csv”

space hyphen space name: operation space space space space type: string space space space space description: Analysis operation to perform space space space space required: false space space space space default: “summary” space space space space enum_values: [“summary”, “average”, “count”, “max”, “min”]

Parameter Types

🔌 Allowed Tools

Restrict what atomic skills this skill can use. Useful for security and sandboxing.

Start of allowed tools section:

allowed_tools: space hyphen space file_read space hyphen space file_write space hyphen space math_calculator

If not specified, the skill can use all available atomic skills.

🔗 Dependencies

List other skills this skill depends on. HippoX will ensure they are available.

Start of dependencies section:

dependencies: space hyphen space csv-parser space hyphen space data-validator

🎯 Triggers

Define patterns that automatically activate this skill without LLM selection.

Start of triggers section:

triggers: space space patterns: space space space hyphen space “analyze data” space space space hyphen space “run analysis” space space space hyphen space “process dataset” space space case_sensitive: false

When user input matches any pattern, this skill is selected automatically.

💡 Complete Example: CSV Analyzer

Create a file at skills/csv-analyzer/SKILL.md with the following content:

Start of file:

Three dash lines name: csv-analyzer description: Analyze CSV files and generate statistics version: 1.0.0 author: HippoX Team parameters: space hyphen space name: file space space space space type: string space space space space description: Path to CSV file space space space space required: true space hyphen space name: column space space space space type: string space space space space description: Column to analyze space space space space required: false space hyphen space name: operation space space space space type: string space space space space description: Operation to perform space space space space required: false space space space space default: “summary” space space space space enum_values: [“summary”, “average”, “max”, “min”, “count”] triggers: space space patterns: space space space hyphen space “analyze csv” space space space hyphen space “csv statistics” space space space hyphen space “process csv” Three dash lines

Hash sign Hash sign Hash sign Hash sign CSV Analyzer Skill

You are a data analysis expert. Analyze the CSV file provided by the user.

Hash sign Hash sign Hash sign Hash sign Instructions

Step 1: Read the CSV file using the file_read skill

Step 2: Parse the CSV content to extract data

Step 3: If a column is specified, analyze only that column

Step 4: Perform the requested operation (summary, average, max, min, or count)

Step 5: Return formatted results as a markdown table

Hash sign Hash sign Hash sign Hash sign Output Format

Hash sign Hash sign Hash sign Hash sign Error Handling

If the file does not exist, inform the user and suggest checking the path.

If the column is not found, list available columns.

🚀 Using Your Skill

Once the SKILL.md file is created, you can use it in two ways:

Via natural language: The LLM will automatically select the skill when the user asks to analyze a CSV file.

Direct execution: You can call the skill directly by name with parameters.

📝 Best Practices

1. Write Clear Descriptions The description field is what the LLM uses to decide if your skill is relevant. Be specific and concise.

   Good example: “Analyze CSV files and generate statistical summaries including average, max, min, and count”

   Poor example: “Process data”

2. Provide Examples Include example inputs and outputs in your instructions. This helps the LLM understand expected behavior.

3. Handle Errors Gracefully Describe what the skill should do when things go wrong: missing files, invalid parameters, empty results.

4. Use Variables Reference parameters using double curly braces around the parameter name in your instructions.

5. Keep Focused Each skill should do one thing well. Create multiple small skills rather than one giant skill.

🔍 Debugging Skills

If your skill isn’t working as expected:

1. Check that the file is named exactly SKILL.md (case-sensitive)
2. Verify YAML frontmatter is valid (no syntax errors)
3. Ensure required fields (name, description) are present
4. Check that parameter names match what you reference in instructions
5. Look at HippoX logs for error messages

SKILL.md Template

Copy and paste this template to create a new skill:

---
name: your-skill-name
description: A brief description of what this skill does
version: 1.0.0
author: Your Name
parameters:
  - name: param1
    type: string
    description: Description of first parameter
    required: true
  - name: param2
    type: integer
    description: Description of second parameter
    required: false
    default: 10
allowed_tools:
  - file_read
  - file_write
triggers:
  patterns:
    - "keyword1"
    - "keyword2"
  case_sensitive: false
---
 
# Skill Title
 
Provide natural language instructions for the AI here.
 
## Instructions
 
Step 1: Do this first
Step 2: Then do that
Step 3: Finally return the result
 
## Example
 
User: "example input"
Response: "expected output"
 
## Error Handling
 
Describe what to do when things go wrong.