skill.md Format

TL;DR

skill.md is the core skill definition file. It has YAML frontmatter (metadata) and a Markdown body (LLM system prompt). The frontmatter defines name, version, model override, required binaries/env vars, and runtime constraints.

Full format


---
name: my-skill
description: "Short description of what the skill does"
author: "Author Name"
version: "1.2.0"
model: "@smart"
requires:
  bins:
    - git
    - kubectl
  env:
    - MY_API_KEY
    - DATABASE_URL
runtime:
  python: ">=3.11"
  node: ">=18"
---
 
Markdown body — this becomes the LLM system prompt.

Frontmatter fields

`name` (required)

Skill identifier. Must match ^[a-z0-9][a-z0-9-]*$ — lowercase letters, digits, and hyphens.

Reserved names that cannot be used: chat, connect, login, logout, version, help, config, update, skills, monitor, debug, logs, agent, daemon, serve, mcp, os, models, auth, completion.

If omitted, the name is derived from the filename.

`description`

Short description displayed in skill listings and the marketplace. Recommended but not required.

`author`

Skill author name or organization.

`version`

Semver version string. Format: MAJOR.MINOR.PATCH (e.g., 1.2.3). CalVer is also supported (e.g., 2026.3.1).

Validated as a warning — an invalid format will not prevent the skill from loading but will be flagged during validation.

`model`

Override the default LLM model for this skill. Accepts two formats:

Tier aliases (recommended):

Alias	Description
`@cheap`	Cheapest available model
`@budget`	Budget-friendly model
`@fast`	Fastest response time
`@standard`	General purpose
`@balanced`	Balance of cost and quality
`@smart`	High-quality reasoning
`@premium`	Best available model

Modifiers can be added with +: @smart+agents, @balanced+vision+tools.

Available modifiers: vision, tools, agents, json, streaming, long, code, reasoning, creative, analysis, chat.

Direct model IDs: anthropic/claude-opus-4, claude-opus-4-6, openai/gpt-4o.

`requires`

Declare dependencies that must be present before the skill can run.


requires:
  bins:
    - git          # must be in PATH
    - docker
  env:
    - OPENAI_API_KEY    # must be set
    - DATABASE_URL

The agent checks requirements before executing the skill. Missing binaries or env vars produce a clear error message.

`runtime`

Minimum runtime versions:


runtime:
  python: ">=3.11"
  node: ">=18"

Used by the installer to set up the correct environment.

Body (system prompt)

Everything after the frontmatter closing --- is the LLM system prompt. This is what the agent reads to understand the skill.

Guidelines

Write as instructions to an AI assistant
Keep under 4000 characters (longer prompts produce a validation warning)
Include a Commands section with exact CLI syntax
Include an Output Format section
Close all code fences (unclosed ``` produces a validation warning)

Example


---
name: ssl-cert-checker
description: "Check SSL certificate expiry dates"
version: "0.1.4"
runtime:
  python: ">=3.11"
---
 
# SSL Certificate Checker
 
You help users check SSL/TLS certificate expiry dates for domains.
 
When the user provides domain names, run the check command
and report the results clearly.
 
## Commands
 
- `ssl-cert-checker check github.com` — Check single domain
- `ssl-cert-checker check github.com google.com` — Check multiple domains
- `ssl-cert-checker check github.com --timeout 30` — Custom timeout
 
## Output Format
 
Present results as a table:
| Domain | Expiry Date | Days Left | Issuer |

Skill loading

Skills are loaded from three locations in priority order:

Priority	Origin	Location
Highest	Workspace	`.cmdop/skills/` in current directory
Middle	Global	`~/.cmdop/skills/`
Lowest	Builtin	Embedded in binary

If two skills have the same name, the higher-priority one wins.

Directory-based skills (preferred)


~/.cmdop/skills/
  my-skill/
    skill.md
    requirements.txt    # auto-generated on install
    meta.json           # install metadata

Flat file skills (legacy)


~/.cmdop/skills/
  my-skill.md

A plain .md file at the top level is treated as a single-file skill. Directory-based skills are preferred.

Validation

Run validation locally with cmdop-skill validate or programmatically:

Errors (skill will not load):

Missing name
Invalid name format
Reserved name
Empty body

Warnings (skill loads but should be fixed):

Missing description
Invalid version format
Body over 4000 characters
Unclosed code fence