> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ezforge.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# SKILL.md
> The portable capability manifest for every MCP server
## 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
```yaml theme={null}
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:
```yaml theme={null}
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:
1. **Template tool manifest** — the full list of tools the vertical template supports (stored in `templates.tool_manifest`)
2. **Business capabilities** — which tools the business owner has enabled (from `business_capabilities`)
3. **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)
```yaml theme={null}
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.
```yaml theme={null}
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.
```yaml theme={null}
# 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.
```yaml theme={null}
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
```yaml theme={null}
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](/ready/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/`) |
| `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:**
```bash theme={null}
curl -X POST https://ezforge.ai/api/v1/hub/listings/01JQXYZ.../capability-doc \
-H "Authorization: Bearer " \
-F "file=@SKILL.md;type=text/markdown"
```
### What happens on upload
1. **Parsing** — The file is parsed into a structured `ParsedCapabilityDoc` representation (name, description, tools list).
2. **Storage** — The raw file is stored in object storage and a public `capability_doc_url` is recorded on the listing.
3. **Re-indexing** — The listing is re-indexed in Typesense with the `capability_doc_url` field, making the document discoverable via Hub search.
4. **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](/hub/api-reference#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