skill.md format

The SKILL.md specification.

Every Skilski is a Markdown file with YAML frontmatter. This page documents every field, every body section, and every validation rule the pipeline enforces.

Example SKILL.md

Abbreviated example showing frontmatter and all required body sections.

skills/hvac-dispatch-scheduler/SKILL.md

---
name: HVAC Dispatch Scheduler
slug: hvac-dispatch-scheduler
version: "1.2.0"
schema: agentskills.io@v1
sector: hvac-residential
audience: ["dispatcher", "field-supervisor"]
tier: pro
price_usd: 199
verified: true
verified_at: "2026-04-15T10:30:00Z"
summary: >
  Schedules and prioritizes HVAC service dispatch orders by urgency,
  technician availability, and travel zone. Returns a ranked call list
  with ETAs and escalation flags.
bottleneck: Manual prioritization wastes 30-45 min per dispatcher per shift.
business_value_usd: 18000
roi_ratio: 90
human_pass_required: false
tags: ["dispatch", "scheduling", "field-service", "hvac"]
citations:
  - "ACCA Manual J, 9th Edition (load calculations)"
  - "DOE HVAC Best Practices, 2023"
---

## What this skill does

Analyzes an open ticket queue and technician availability to produce a
ranked dispatch list with estimated arrival times. Accounts for job urgency,
travel zone overlap, current tech workload, and SLA windows.

## When to trigger

Use this skill when:
- A dispatcher has 3+ open tickets and needs prioritization guidance
- A field supervisor needs to rebalance mid-day after a callback or emergency
- An automated system needs to suggest routes at shift start

## Inputs

| Field | Type | Required | Description |
|---|---|---|---|
| context | string | yes | Open tickets with urgency, location, and tech availability |

The context string should include ticket IDs, customer addresses, issue descriptions,
urgency levels (urgent / standard / low), and a list of available technicians with
their current locations.

## Outputs

Returns a ranked dispatch list in plain text:
- Priority order with reasoning
- Estimated drive time and arrival window per job
- Escalation flags for SLA-critical tickets
- Suggested tech assignments

## Procedure

1. Parse ticket queue from context — extract urgency, location, and SLA deadline
2. Rank by: (1) urgency class, (2) SLA proximity, (3) travel cluster efficiency
3. Assign techs to minimize total drive time while preserving urgency order
4. Flag any ticket within 90 min of SLA breach for immediate attention
5. Output ranked list with ETAs and brief rationale per assignment

## Citations

- ACCA Manual J, 9th Edition — load calculation basis for urgency classification
- DOE HVAC Best Practices (2023) — field efficiency benchmarks

Frontmatter fields

Field

Type

Required

Description

name

string

yes

Human-readable display name. Max 120 chars.

slug

string

yes

URL-safe identifier. Lowercase, hyphens. Matches the skills/ directory name.

version

string

yes

Semver string. e.g. "1.2.0". Bump minor on content changes, patch on corrections.

schema

string

yes

Always "agentskills.io@v1" for v1 skills.

sector

string

yes

Primary industry sector slug. See /sector for the canonical list.

audience

array

yes

Target roles. e.g. ["dispatcher", "field-supervisor"]. At least one value.

tier

enum

yes

"free" | "pro" | "elite". Determines which plan unlocks this skill.

price_usd

number

yes

Outright purchase price in USD. 0 for free skills.

verified

boolean

yes

true only after all 7 gauntlet gates pass. Do not self-set to true.

verified_at

string

ISO 8601 timestamp set by the verification pipeline.

summary

string

yes

One to three sentence capability description. Used in catalog cards and tool descriptions. Max 500 chars.

bottleneck

string

yes

The pain this skill eliminates. One sentence, buyer-facing.

business_value_usd

number

Estimated annual value delivered. Used in ROI display. Cite the source in Citations.

roi_ratio

number

business_value_usd / price_usd. Computed or provided.

human_pass_required

boolean

yes

true for legal, medical, financial domains. Adds Human Pass Required marker.

tags

array

Search and filter tags. Lowercase, hyphens. Max 10.

citations

array

Source references. Freeform strings. Required for business_value_usd claims.

Body sections

The body follows the closing --- of the frontmatter fence. Sections are identified by exact heading strings — spelling and case must match.

## What this skill does

required

Concise capability statement. 2-5 sentences. Plain English — no jargon unless the audience expects it.

## When to trigger

required

Bullet list of trigger conditions. Helps the AI client decide when to invoke this skill.

## Inputs

required

Markdown table of fields: Field | Type | Required | Description. Context is always the primary required input.

## Outputs

required

What the skill returns. Format, shape, key fields.

## Procedure

required

Step-by-step execution logic. Numbered list. This is the instruction set the AI follows.

## Citations

optional

Sources for claims, standards referenced, data provenance. Required when business_value_usd or ROI is stated.

Validation rules

These checks run in the Quarantine gate — the first gate in the 7-gate verification pipeline. Failure here blocks all downstream gates.

File size

256 KB maximum per SKILL.md file

Schema version

schema: agentskills.io@v1 — only v1 accepted by current pipeline

Slug format

Lowercase a-z, digits, hyphens only. Must match the skills/<slug>/ directory name.

Version format

Semver (major.minor.patch). Non-semver strings will fail schema validation.

Frontmatter fence

Must open and close with ---. Parser strict on whitespace.

Required sections

All five required ## body sections must be present. Parser checks by exact heading string.

verified field

verified: true is set only by the automated gauntlet pipeline. Manually setting it to true will cause the integrity check to fail.

human_pass_required

Legal, medical, and financial skills must set human_pass_required: true or the submission is rejected.

human_pass_required

Legal, medical, and financial skills require human review.

Set human_pass_required: true for any skill touching legal advice, medical documentation, financial decisions, or clinical content. The marker appears on the catalog card and in the MCP tool description. Omitting it on high-stakes skills is a submission rejection reason. See Trust for the responsible AI doctrine.

How verification works →Publish a Skilski →MCP Protocol →

Example SKILL.md

Abbreviated example showing frontmatter and all required body sections.

skills/hvac-dispatch-scheduler/SKILL.md

---
name: HVAC Dispatch Scheduler
slug: hvac-dispatch-scheduler
version: "1.2.0"
schema: agentskills.io@v1
sector: hvac-residential
audience: ["dispatcher", "field-supervisor"]
tier: pro
price_usd: 199
verified: true
verified_at: "2026-04-15T10:30:00Z"
summary: >
  Schedules and prioritizes HVAC service dispatch orders by urgency,
  technician availability, and travel zone. Returns a ranked call list
  with ETAs and escalation flags.
bottleneck: Manual prioritization wastes 30-45 min per dispatcher per shift.
business_value_usd: 18000
roi_ratio: 90
human_pass_required: false
tags: ["dispatch", "scheduling", "field-service", "hvac"]
citations:
  - "ACCA Manual J, 9th Edition (load calculations)"
  - "DOE HVAC Best Practices, 2023"
---

## What this skill does

Analyzes an open ticket queue and technician availability to produce a
ranked dispatch list with estimated arrival times. Accounts for job urgency,
travel zone overlap, current tech workload, and SLA windows.

## When to trigger

Use this skill when:
- A dispatcher has 3+ open tickets and needs prioritization guidance
- A field supervisor needs to rebalance mid-day after a callback or emergency
- An automated system needs to suggest routes at shift start

## Inputs

| Field | Type | Required | Description |
|---|---|---|---|
| context | string | yes | Open tickets with urgency, location, and tech availability |

The context string should include ticket IDs, customer addresses, issue descriptions,
urgency levels (urgent / standard / low), and a list of available technicians with
their current locations.

## Outputs

Returns a ranked dispatch list in plain text:
- Priority order with reasoning
- Estimated drive time and arrival window per job
- Escalation flags for SLA-critical tickets
- Suggested tech assignments

## Procedure

1. Parse ticket queue from context — extract urgency, location, and SLA deadline
2. Rank by: (1) urgency class, (2) SLA proximity, (3) travel cluster efficiency
3. Assign techs to minimize total drive time while preserving urgency order
4. Flag any ticket within 90 min of SLA breach for immediate attention
5. Output ranked list with ETAs and brief rationale per assignment

## Citations

- ACCA Manual J, 9th Edition — load calculation basis for urgency classification
- DOE HVAC Best Practices (2023) — field efficiency benchmarks

Frontmatter fields

Field

Type

Required

Description

name

string

yes

Human-readable display name. Max 120 chars.

slug

string

yes

URL-safe identifier. Lowercase, hyphens. Matches the skills/ directory name.

version

string

yes

Semver string. e.g. "1.2.0". Bump minor on content changes, patch on corrections.

schema

string

yes

Always "agentskills.io@v1" for v1 skills.

sector

string

yes

Primary industry sector slug. See /sector for the canonical list.

audience

array

yes

Target roles. e.g. ["dispatcher", "field-supervisor"]. At least one value.

tier

enum

yes

"free" | "pro" | "elite". Determines which plan unlocks this skill.

price_usd

number

yes

Outright purchase price in USD. 0 for free skills.

verified

boolean

yes

true only after all 7 gauntlet gates pass. Do not self-set to true.

verified_at

string

ISO 8601 timestamp set by the verification pipeline.

summary

string

yes

One to three sentence capability description. Used in catalog cards and tool descriptions. Max 500 chars.

bottleneck

string

yes

The pain this skill eliminates. One sentence, buyer-facing.

business_value_usd

number

Estimated annual value delivered. Used in ROI display. Cite the source in Citations.

roi_ratio

number

business_value_usd / price_usd. Computed or provided.

human_pass_required

boolean

yes

true for legal, medical, financial domains. Adds Human Pass Required marker.

tags

array

Search and filter tags. Lowercase, hyphens. Max 10.

citations

array

Source references. Freeform strings. Required for business_value_usd claims.

Body sections

The body follows the closing --- of the frontmatter fence. Sections are identified by exact heading strings — spelling and case must match.

## What this skill does

required

Concise capability statement. 2-5 sentences. Plain English — no jargon unless the audience expects it.

## When to trigger

required

Bullet list of trigger conditions. Helps the AI client decide when to invoke this skill.

## Inputs

required

Markdown table of fields: Field | Type | Required | Description. Context is always the primary required input.

## Outputs

required

What the skill returns. Format, shape, key fields.

## Procedure

required

Step-by-step execution logic. Numbered list. This is the instruction set the AI follows.

## Citations

optional

Sources for claims, standards referenced, data provenance. Required when business_value_usd or ROI is stated.

Validation rules

These checks run in the Quarantine gate — the first gate in the 7-gate verification pipeline. Failure here blocks all downstream gates.

File size

256 KB maximum per SKILL.md file

Schema version

schema: agentskills.io@v1 — only v1 accepted by current pipeline

Slug format

Lowercase a-z, digits, hyphens only. Must match the skills/<slug>/ directory name.

Version format

Semver (major.minor.patch). Non-semver strings will fail schema validation.

Frontmatter fence

Must open and close with ---. Parser strict on whitespace.

Required sections

All five required ## body sections must be present. Parser checks by exact heading string.

verified field

verified: true is set only by the automated gauntlet pipeline. Manually setting it to true will cause the integrity check to fail.

human_pass_required

Legal, medical, and financial skills must set human_pass_required: true or the submission is rejected.