Skill File Format

Skills are markdown files with YAML frontmatter. This page defines the complete format specification for creating skill files.

File Structure

---
name: Skill Name
version: "1.0.0"
description: What this skill teaches the agent
category: Category Name
tags:
  - tag1
  - tag2
---

# Skill Title

Content goes here...

Frontmatter Fields

Field	Type	Required	Description
name	string	Yes	Human-readable skill name
version	string	No	Semantic version (default: "1.0.0")
description	string	No	Brief description of the skill's purpose
category	string	No	Category for grouping (e.g., "Marketing", "Customer Service")
tags	string[]	No	Tags for filtering and discovery

Version Format

Use semantic versioning: MAJOR.MINOR.PATCH

• MAJOR — incompatible changes (rewrite)
• MINOR — new sections or significant additions
• PATCH — fixes, small updates

Content Structure

The markdown content after the frontmatter contains the skill's knowledge. Use these recommended sections:

Tone Section

Define the communication style the agent should use:

## Tone

- Professional but approachable
- Use active voice
- Keep sentences concise (under 25 words)
- Address the reader as "you"

Rules Section

Hard rules the agent must follow when this skill is active:

## Rules

- Always include a meta description under 155 characters
- Use the brand name "HelixNode" (one word, capital H and N)
- Never mention competitor products by name
- All prices must include currency symbol (e.g., $79/month)

Examples Section

Show the agent what good and bad output looks like:

## Examples

### Good
"Get started in under 5 minutes with our one-command installer."

### Bad
"The installation process can be initiated by executing the provided shell script."

Do / Don't Lists

Quick-reference guidelines:

## Do

- Use contractions (we're, you'll, it's)
- Lead with benefits, not features
- Include specific numbers

## Don't

- Use passive voice
- Say "please" excessively
- Use exclamation marks in body copy

Templates Section

Reusable output templates the agent should follow:

## Templates

### Blog Post Template

Title: [Keyword-rich title, 50-60 characters]
Meta: [Description, under 155 characters]
Intro: [Hook + what the reader will learn, 2-3 sentences]
Body: [3-5 sections with H2 headings]
CTA: [Call to action with link]

Reference Section

Background information, data, and context:

## Reference

### Product Pricing

| Plan | Price | Agents | Skills |
|------|-------|--------|--------|
| Starter | $29/mo | 5 | 10 |
| Pro | $79/mo | 20 | 50 |
| Enterprise | Custom | Unlimited | Unlimited |

Activation Configuration

When assigning a skill to an agent, you configure when it activates:

Always Active

The skill is included in the agent's context for every task:

{
  "activation_mode": "always"
}

Board-Specific

The skill activates only for tasks on specific boards:

{
  "activation_mode": "board_specific",
  "activation_boards": [3, 4, 7]
}

Tag-Specific

The skill activates only for tasks with specific tags:

{
  "activation_mode": "tag_specific",
  "activation_tags": ["urgent", "vip"]
}

Attachments

Skills can have file attachments that provide additional reference material.

Supported File Types

• Documents: PDF, TXT, DOCX
• Images: PNG, JPG, SVG, WebP
• Spreadsheets: CSV, XLSX
• Other: JSON, XML

Attachment Usage

Attachments are stored on the server and referenced by the agent. Use them for:

• Brand style guide PDFs
• Product image catalogs
• Pricing spreadsheets
• Example documents the agent should reference

Complete Example

---
name: CS Email Templates
version: "1.2.0"
description: Standard response templates for customer service emails
category: Customer Service
tags:
  - email
  - templates
  - customer-service
---

# CS Email Templates

## Tone

- Empathetic and solution-oriented
- Professional but warm
- Never blame the customer
- Acknowledge the issue before providing the solution

## Rules

- Always greet by name if available
- Include order number in responses about orders
- Offer escalation if the first solution doesn't resolve the issue
- End with a clear next step or confirmation
- Response time SLA: acknowledge within 2 hours, resolve within 24 hours

## Templates

### Order Status Inquiry

Subject: Re: Order #{order_number} Status Update

Hi {customer_name},

Thank you for reaching out about your order #{order_number}.

{status_update}

If you have any other questions, feel free to reply to this email.

Best regards,
{agent_name}
{org_name} Support

### Refund Request

Subject: Re: Refund Request - Order #{order_number}

Hi {customer_name},

I understand you'd like a refund for order #{order_number}. I'm sorry
for any inconvenience.

{refund_details}

The refund will be processed within 5-7 business days.

Best regards,
{agent_name}
{org_name} Support

## Do

- Personalize responses with customer details
- Proactively provide tracking links
- Follow up on unresolved issues

## Don't

- Use canned responses without personalization
- Promise specific resolution times you can't guarantee
- Share internal process details with customers