SKILL.md - ezForge AI

Overview

SKILL.md is a structured capability manifest auto-generated for every MCP server listed on Hub. It’s the portable discovery artifact that describes what your server can do — whether an agent discovers it through Hub’s API, a direct URL, or a third-party registry.

SKILL.md generation is automatic for all Platform and Ready customers listed on Hub.

What’s in a SKILL.md?

Every SKILL.md includes:

Identity — Server name, description, publisher, version
Capabilities — List of MCP tools and resources with descriptions
Authentication — Auth method and endpoint
Vertical & location — Business category and geographic coverage
Hours — Operating schedule (weekly + special hours)
Attributes — Vertical-specific business metadata (cuisine types, walk-ins, delivery, etc.)
Catalog summary — Aggregate stats about available items (counts, categories, highlights)
Trust signals — Verification tier, health score, uptime

Example

name: Mario's Pizzeria
description: Family-owned Italian restaurant in downtown Detroit
publisher: mario-pizzeria
version: 1.2.0
vertical: restaurant
location:
  city: Detroit
  state: MI
  country: US
  coordinates:
    lat: 42.3314
    lng: -83.0458

capabilities:
  - tool: search_menu
    description: Search menu items by name, category, or dietary restriction (vegan, gluten-free, halal)
  - tool: get_hours
    description: Get current hours of operation and holiday schedule
  - tool: check_availability
    description: Check table availability for a party size and date
  - tool: request_reservation
    description: Submit a reservation request

hours:
  monday: "11:00-22:00"
  tuesday: "11:00-22:00"
  wednesday: "11:00-22:00"
  thursday: "11:00-23:00"
  friday: "11:00-23:00"
  saturday: "12:00-23:00"
  sunday: closed

attributes:
  cuisine_types: ["Italian", "Pizza"]
  delivery_available: true
  outdoor_seating: true
  price_range: "$$"
  alcohol_served: true

catalog_summary:
  total_items: 47
  categories: 6
  highlights:
    - "12 vegan options"
    - "Gluten-free menu available"
    - "Daily specials"

auth:
  method: oauth2.1
  endpoint: https://mario-pizzeria.mcp.ezforge.ai/.well-known/oauth-authorization-server

verification: business_verified
health_score: 97

Hub-specific extensions

Hub-generated SKILL.md files include additional fields for discovery optimization:

hub:listing_id: "01JQXYZ..."
hub:listing_tier: "featured"
hub:verification_tier: 3          # integer rank used by Hub (1=unverified, 2=phone_verified, 3=business_verified, 4=premium_verified)
hub:health_score: 97
hub:hub_url: "https://hub.ezforge.ai/listings/detroiteats"
hub:referral_endpoint: "https://hub.ezforge.ai/api/v1/hub/listings/01JQXYZ.../referral"

Field Reference

Core fields

Field	Required	Source (Ready)	Description
`name`	Yes	`businesses.name`	Display name
`description`	Yes	`business_profiles.description`	Human-readable summary
`publisher`	Yes	`businesses.slug`	Publisher identifier
`version`	Yes	`templates.version`	Template/server version
`vertical`	Yes	`businesses.vertical`	Business category (`restaurant`, `salon`, `home_services`, `retail`, `professional_services`)
`location`	Yes	`business_profiles.{city,state,country,lat,lng}`	Geographic location with optional coordinates

Capabilities

The capabilities list describes the MCP tools the server exposes. For Ready servers, this is generated by cross-referencing:

Template tool manifest — the full list of tools the vertical template supports (stored in templates.tool_manifest)
Business capabilities — which tools the business owner has enabled (from business_capabilities)
Metadata enrichment — tool descriptions are enhanced with actual catalog data (e.g., if a restaurant has items with dietary_tags, the search_menu description mentions dietary filtering)

capabilities:
  - tool: search_menu
    description: Search 47 menu items by name, category, or dietary restriction (vegan, gluten-free, halal)
  - tool: get_hours
    description: Get current hours of operation and holiday schedule

Hours

Operating schedule sourced from business_hours and business_special_hours tables. Agents use this to filter businesses by current availability.

hours:
  monday: "11:00-22:00"
  tuesday: "11:00-22:00"
  sunday: closed
special_hours:
  - date: "2026-12-25"
    label: "Christmas Day"
    hours: closed

Attributes

Vertical-specific business metadata from businesses.metadata JSONB. These are the business-level characteristics that agents use for filtering and comparison — distinct from catalog item metadata.

# Restaurant example
attributes:
  cuisine_types: ["Italian", "Pizza"]
  delivery_available: true
  outdoor_seating: true
  price_range: "$$"

# Salon example
attributes:
  walk_ins_accepted: true
  cancellation_policy: "24 hours"

# Home services example
attributes:
  licensed: true
  insured: true
  emergency_available: true
  service_radius_miles: 25

# Retail example
attributes:
  online_store_url: "https://example.com/shop"
  return_policy: "30 days"
  shipping_available: true
  curbside_pickup: true

# Professional Services example
attributes:
  specializations: ["Tax Preparation", "Business Advisory"]
  consultation_fee_cents: 15000
  accepts_insurance: false

Catalog Summary

Aggregate statistics about the business’s catalog, generated from catalog_items and catalog_categories. Gives agents a quick overview without requiring a tool call.

catalog_summary:
  total_items: 47
  categories: 6
  highlights:
    - "12 vegan options"
    - "Gluten-free menu available"

The highlights array is auto-generated from catalog metadata analysis (e.g., counting items with specific dietary_tags, in_stock status, etc.).

Authentication & Trust

auth:
  method: oauth2.1
  endpoint: https://example.mcp.ezforge.ai/.well-known/oauth-authorization-server

verification: business_verified    # VerificationLevel: unverified | phone_verified | business_verified | premium_verified
health_score: 97                   # 0-100, from Platform health checks

verification reflects the publisher’s VerificationLevel — the public-facing string returned by the Directory API. See Business Verification for how each tier is earned.

Hub-specific fields

Fields injected by Hub when serving a listing’s SKILL.md via GET /api/v1/hub/listings/:id/skill.md. These use flat colon-prefixed keys and are not present in self-hosted SKILL.md files.

Field	Type	Description
`hub:listing_id`	string (ULID)	Hub listing identifier
`hub:listing_tier`	string	Listing tier (`basic`, `featured`, `premium`)
`hub:verification_tier`	integer	Numeric verification rank (1 = unverified, 2 = phone_verified, 3 = business_verified, 4 = premium_verified)
`hub:health_score`	integer	Platform health score, 0–100
`hub:hub_url`	string (URL)	Canonical Hub listing URL (`https://hub.ezforge.ai/listings/<slug>`)
`hub:referral_endpoint`	string (URL)	Hub referral tracking endpoint for this listing

Auto-generation

SKILL.md is auto-generated from your server’s metadata:

Platform servers — Generated from your ezforge.toml config and MCP server introspection
Ready servers — Generated from business profile, template tool manifest, enabled capabilities, catalog data, and business metadata
Featured/Premium listings — You can customize the description, keywords, and tags

Ready SKILL.md generation flow

business_profiles ──┐
business_hours ─────┤
businesses.metadata ┤──→ generateReadySkillDoc() ──→ SKILL.md
catalog_items ──────┤
business_capabilities┤
templates.tool_manifest┘

The generator runs on every deployment and whenever business data changes. The generated SKILL.md is cached in the Hub listing’s skill_md JSONB column and served at /.well-known/skill.md on the business’s MCP server.

Uploading a capability document

Hub listing owners can supplement auto-generated SKILL.md data by uploading a custom capability document — a SKILL.md or JSON file that describes the tools and skills their MCP server exposes.

POST /api/v1/hub/listings/:id/capability-doc

The request uses multipart/form-data with a single file field. Pass your listing’s ULID in the path and an authenticated user session token in the Authorization header. Accepted formats:

MIME type	Stored as	Notes
`text/markdown`	`skill_md`	Standard SKILL.md format
`text/plain`	`skill_md`	Treated as Markdown
`text/x-markdown`	`skill_md`	Alternative Markdown MIME type
`application/json`	`json`	Structured JSON capability document

Constraints:

Maximum file size: 512 KB
Only one capability document is stored per listing — uploading replaces any existing document
The listing must not be delisted; uploading to a delisted listing returns 422

Example:

curl -X POST https://ezforge.ai/api/v1/hub/listings/01JQXYZ.../capability-doc \
  -H "Authorization: Bearer <user-token>" \
  -F "file=@SKILL.md;type=text/markdown"

What happens on upload

Parsing — The file is parsed into a structured ParsedCapabilityDoc representation (name, description, tools list).
Storage — The raw file is stored in object storage and a public capability_doc_url is recorded on the listing.
Re-indexing — The listing is re-indexed in Typesense with the capability_doc_url field, making the document discoverable via Hub search.
Public availability — The capability document is immediately available via:
- GET /api/v1/hub/listings/:id/capability-doc — fetch the parsed document for a single listing
- GET /.well-known/mcp-skills — the Hub-level skills discovery registry, which enumerates all active listings with uploaded capability docs

For the complete endpoint schemas — including the full response shape, all error codes, and pagination on GET /.well-known/mcp-skills — see Capability documents in the Hub API Reference.

Using SKILL.md externally

SKILL.md is designed to be portable. You can:

Host it at /.well-known/skill.md on any domain
Include it in your GitHub repository
Submit it to third-party MCP registries
Reference it from WebMCP metadata tags

​Overview

​What’s in a SKILL.md?

​Example

​Hub-specific extensions

​Field Reference

​Core fields

​Capabilities

​Hours

​Attributes

​Catalog Summary

​Authentication & Trust

​Hub-specific fields

​Auto-generation

​Ready SKILL.md generation flow

​Uploading a capability document

​What happens on upload

​Using SKILL.md externally

Overview

What’s in a SKILL.md?

Example

Hub-specific extensions

Field Reference

Core fields

Capabilities

Hours

Attributes

Catalog Summary

Authentication & Trust

Hub-specific fields

Auto-generation

Ready SKILL.md generation flow

Uploading a capability document

What happens on upload

Using SKILL.md externally