SKILL.md Frontmatter Specification

Complete reference for SKILL.md YAML frontmatter and skillbase.json workspace manifest.

Overview

Every skill is a single SKILL.md file with YAML frontmatter (metadata) and a Markdown body (instructions).

For workspace-level dependency management, use skillbase.json — the project manifest analogous to package.json.

SKILL.md Frontmatter

Required fields

Field	Type	Description
`name`	`string`	URL-safe slug (lowercase alphanumeric + hyphens)
`version`	`string`	Semver version (e.g., `1.0.0`)
`author`	`string`	Author name
`license`	`string`	SPDX license identifier
`description`	`string`	Short description for humans

Required for publishable skills

Field	Type	Description
`language`	`string`	Language code (e.g., `en`)
`trigger`	`object`	When the AI should use this skill

Name format

Names must be URL-safe slugs matching ^[a-z0-9][a-z0-9-]*$:

Lowercase letters, digits, and hyphens only
Must start with a letter or digit
Skills are namespaced by the author field

Trigger

The trigger object controls when and how the AI model selects this skill.

trigger:
  description: "Use when creating Word documents (.docx)"
  tags: [docx, word, document]
  file_patterns: ["*.docx"]
  priority: 50

Field	Type	Description
`description`	`string`	Required. Natural language — embedded in MCP instructions so the model matches tasks to skills
`tags`	`string[]`	Required. Keywords for `skill_search` matching
`file_patterns`	`string[]`	Glob patterns for file-based matching
`priority`	`number`	0–100, higher wins conflicts (default: 50)

Writing good trigger descriptions

The description is the primary signal the model uses to decide whether to load a skill. It is embedded directly into the MCP server instructions.

Be comprehensive — list all task types the skill covers
Include technology names — models match on specific keywords like "React", "Tailwind", "wagmi"
Avoid vague phrases — "React/Vue components, Tailwind styling, Web3 wallet integration" beats "Helps with frontend"
Keep it concise — repeated in every session's context

Priority levels

Range	Use case
0–19	Demos and examples
20–39	General community skills
40–59	Specialized skills (default)
60–79	Domain-specific with strict requirements
80–100	Core/system skills

Dependencies

Declare dependencies on other skills with semver ranges:

dependencies:
  core/data-utils: ^1.0.0
  user/xlsx-parser: ~2.1.0

Dependencies are automatically resolved and installed. Circular dependencies are detected and rejected.

Compatibility

compatibility:
  min_context_tokens: 4000
  requires: [bash, file_system]
  models: []

Field	Description
`min_context_tokens`	Minimum tokens needed to load this skill
`requires`	Capabilities needed (`bash`, `file_system`, `web_search`)
`models`	Restrict to specific models (empty = all)

Security permissions

security:
  permissions: [file:read, file:write, bash:execute]

Permission	Description
`file:read`	Read files
`file:write`	Create/modify files
`file:delete`	Delete files
`bash:execute`	Run shell commands
`network:none`	No network access
`network:allowlist`	Restricted network access
`tool:web_search`	Web search capability
`tool:*`	All tools

Skill composition

The works_with field declares relationships with other skills:

works_with:
  - skill: core/xlsx
    relationship: input
    description: "Can use data from Excel spreadsheets"

Type	Description
`input`	This skill consumes output from the referenced skill
`output`	This skill produces data for the referenced skill
`parallel`	Both skills work together on the same task

Optional fields

Field	Type	Description
`repository`	`string`	Source code URL

Full example

---
name: report-generator
version: 1.0.0
author: your-name
license: MIT
description: "Generate structured reports from data files"
language: en
 
trigger:
  description: "Use when creating reports from CSV, JSON, or database data"
  tags: [report, data, analysis, csv]
  file_patterns: ["*.csv", "*.json"]
  priority: 50
 
dependencies:
  core/data-utils: ^1.0.0
 
compatibility:
  min_context_tokens: 3000
  requires: [file_system]
  models: []
 
security:
  permissions: [file:read, file:write]
 
works_with:
  - skill: core/xlsx
    relationship: input
    description: "Can read data from Excel files"
 
repository: https://github.com/user/report-generator
---

skillbase.json — Workspace Manifest

skillbase.json is the project-level dependency manifest, analogous to package.json. It lives at the project root and is created by spm init.

{
  "schema_version": 1,
  "name": "my-project",
  "version": "1.0.0",
  "skills": {
    "@core/docx": "^1.2.0",
    "@core/xlsx": "^1.0.0"
  },
  "personas": {
    "@evseevnn/defi-analyst": "^1.0.0"
  },
  "registry": "https://registry.skillbase.space",
  "spm": {
    "default_instance": "corp-prod"
  }
}

Fields

Field	Required	Description
`schema_version`	Yes	Always `1`
`name`	Yes	Project identifier
`version`	Yes	Semver version
`skills`	No	Skill dependencies as `"@author/name": "semver"`
`personas`	No	Persona dependencies as `"@author/name": "semver"`
`registry`	No	Override default registry URL
`spm.default_instance`	No	Default OpenClaw remote instance name

CLI workflow

spm init                    # Creates skillbase.json
spm install                 # Installs all deps from skillbase.json
spm add @core/docx          # Installs + adds to skillbase.json
spm add @author/persona --persona  # Adds to personas section
spm remove @core/docx       # Removes from skillbase.json + disk

Migration

If you have a legacy skill.json from an older version, run spm migrate run to convert it to skillbase.json.

PreviousCreating Skills

NextPersonas