Skill Manifest

Complete reference for the SKILL.md file format and all available fields

Every custom skill starts with a SKILL.md file. This file has two parts: a YAML frontmatter header (between --- markers) that describes the skill, and a Markdown body that contains the instructions or code. This page documents every field available in the frontmatter.

The authored frontmatter carries exactly six top-level fields — name, description, license, compatibility, allowed-tools, and metadata. Every platform-specific extension rides under one metadata.comis key (documented below); nothing else is authored at the top level.

Required Fields

Every manifest must include these two fields:

Field	Type	Description
name	string	Unique skill name. Lowercase letters, numbers, and hyphens only, no leading, trailing, or consecutive hyphens. 1-64 characters.
description	string	Human-readable description shown to users and agents. 1-1024 characters. This is the primary trigger mechanism — include both what the skill does AND when to use it.

Here is a minimal SKILL.md that only uses the required fields:

---
name: my-skill
description: "A brief description of what this skill does and when to use it"
---
Your instructions here...

That is all you need to create a valid skill. Everything below is optional.

Optional Fields

These four top-level fields give you more control over how the skill behaves:

Field	Type	Default	Description
license	string	—	SPDX license identifier (e.g., “MIT”, “Apache-2.0”). Declares the license for shared skills.
compatibility	string	—	Free-prose environment or runtime note, operator-visible. It carries no platform semantics — a note over 500 characters draws an advisory warning. Machine-readable prerequisites live under metadata.comis and are complementary, not a duplicate.
allowed-tools	string	""	Space-separated tool-restriction list; an empty value means no restriction. Restriction-only — it narrows the active tool set while the skill runs, it never grants a tool the agent lacks.
metadata	map string→string	—	Arbitrary string key-value pairs. Also carries metadata.version and the metadata.comis extension carrier (below).

Example with Optional Fields

---
name: translate
description: "Translate text between languages"
license: "MIT"
compatibility: "Needs Node 22+ and network access to the translation API."
allowed-tools: "web_fetch"
metadata:
  version: "1.2.0"
  category: "utilities"
---
Translate the following text to {target-language}:

{text}

Platform Extensions (metadata.comis)

Fields that only apply within Comis ride under a single metadata.comis key. Its value is a JSON string — so metadata stays a plain string→string map — that parses and then validates by the same rules as every other manifest field. The carrier moves, the semantics do not. Hosts that implement only the skill spec ignore this key.

The metadata.comis JSON object may carry:

Field	Type	Description
userInvocable	boolean (default true)	Whether users can invoke this skill with /skill:name in chat. Set to false for background-only skills.
disableModelInvocation	boolean (default false)	When true, the agent cannot select this skill on its own — it must be invoked explicitly by a user or another skill.
argumentHint	string	Hint text shown to users when invoking the skill (e.g., “[name] [language]”).
permissions	object	Required filesystem, network, and environment permissions (see below).
inputSchema	object	JSON Schema for input parameters (see below).
comis	object	The Comis namespace block for runtime requirements and platform behavior (see below).
mcpServers	array or object	Optional bundled MCP servers declaration.

The version is authored as metadata.version (a string in the metadata map), not inside the JSON carrier.

Here is a skill that carries a couple of extensions through metadata.comis:

---
name: my-skill
description: "What this skill does and when to use it"
metadata:
  version: "1.0.0"
  comis: '{"userInvocable": true, "permissions": {"net": ["api.example.com"]}, "comis": {"os": ["linux"], "requires": {"bins": ["ripgrep"]}}}'
---

Malformed metadata.comis JSON fails to load with an error that names the key — fix the JSON string, do not remove the metadata map.

Permissions

The permissions object declares what system resources this skill needs. By default, skills have no access to the filesystem, network, or environment variables. Each permission you add opens a specific door. It is carried inside the metadata.comis JSON string:

{
  "permissions": {
    "fsRead": ["./data/*.csv", "./config/"],
    "fsWrite": ["./output/"],
    "net": ["api.example.com", "cdn.example.com"],
    "env": ["API_KEY", "DATABASE_URL"]
  }
}

Key	Type	Description
fsRead	string[]	Filesystem paths the skill can read. Supports glob patterns (e.g., ./data/*.csv).
fsWrite	string[]	Filesystem paths the skill can write to.
net	string[]	Network domains the skill can access (e.g., api.example.com).
env	string[]	Environment variables the skill can read (e.g., API_KEY).

Only grant the permissions your skill actually needs. Start with none and add them one at a time as required. This follows the principle of least privilege — the less access a skill has, the less damage a bug or malicious skill can cause.

Comis namespace

The comis object controls runtime requirements and platform-level behavior. It is carried inside the metadata.comis JSON string:

{
  "comis": {
    "os": ["linux", "darwin"],
    "requires": {
      "bins": ["ffmpeg", "git"],
      "env": ["OPENAI_API_KEY"]
    },
    "skill-key": "video-processor",
    "primary-env": "discord",
    "command-dispatch": "my-command"
  }
}

Field	Type	Description
os	string[]	Target operating systems (e.g., ["linux", "darwin"]). A bare string is coerced to a one-element list. The skill only loads on matching systems.
requires.bins	string[]	Required binary executables on PATH (e.g., ["git", "ffmpeg"]). The skill does not load if any are missing.
requires.env	string[]	Required environment variables. The skill does not load if any are unset.
skill-key	string	Override the auto-generated skill slug. By default the slug is derived from the name field.
primary-env	string	Display and grouping hint for the primary runtime environment.
command-dispatch	string	Metadata-only tag for command routing.

The comis.requires fields are checked at startup by the runtime eligibility system. If a required binary or environment variable is missing, the skill is skipped with a warning — it does not crash the system. You can disable this check with skills.runtimeEligibility.enabled: false in your config, but that is not recommended.

Input Schema

For skills that expect structured input, attach a JSON Schema under inputSchema inside the metadata.comis carrier. The schema is stored alongside the manifest and surfaced as documentation — agents can read it to understand what arguments the skill expects:

{
  "inputSchema": {
    "type": "object",
    "properties": {
      "format": { "type": "string", "enum": ["pdf", "html", "markdown"] },
      "title": { "type": "string" }
    },
    "required": ["format"]
  }
}

inputSchema is currently advisory: it documents the expected shape but is not enforced at invocation time. Treat it as a contract you and the agent agree to honor in the skill body, not a runtime guard.

Complete Example

Here is a full SKILL.md using the six top-level fields plus a metadata.comis carrier that bundles several extensions:

---
name: daily-report
description: "Generate a daily activity report from project logs"
license: "MIT"
compatibility: "Needs git on PATH and a GITHUB_TOKEN in the environment."
allowed-tools: "read web_fetch"
metadata:
  version: "2.1.0"
  team: "ops"
  comis: '{"userInvocable": true, "argumentHint": "[project-name]", "permissions": {"fsRead": ["./logs/*.log"], "fsWrite": ["./reports/"], "net": ["api.github.com"], "env": ["GITHUB_TOKEN"]}, "inputSchema": {"type": "object", "properties": {"project-name": {"type": "string"}}, "required": ["project-name"]}, "comis": {"os": ["linux", "darwin"], "requires": {"bins": ["git"], "env": ["GITHUB_TOKEN"]}, "skill-key": "daily-report", "primary-env": "node"}}'
---
You are a reporting assistant. Read the project logs for {project-name}
and generate a concise daily activity summary.

Include:
- Commits pushed today
- Issues opened or closed
- Pull requests merged

Format the output as a Markdown document suitable for posting in a team channel.

Read Compatibility

The legacy top-level form — extension fields authored directly at the top level (type, version, userInvocable, disableModelInvocation, allowedTools, argumentHint, permissions, inputSchema, comis, mcpServers) — still loads, emitting a deprecation warning that names each moved key and its new home:

• version maps to metadata.version
• userInvocable / disableModelInvocation / argumentHint / permissions / inputSchema / comis / mcpServers map to metadata.comis
• allowedTools (array) maps to allowed-tools (space-separated string)
• type is dropped — skills are prompt-only

It is read for compatibility only and is never written back. Author new skills in the spec-pure six-field form above.

Foreign-Frontmatter Mapping

When you import a skill authored for another ecosystem — or in the legacy Comis form above — its frontmatter is first converged onto the spec-pure shape, then validated. The internal manifest schema is closed, so an unmapped foreign key would otherwise reject the whole skill outright.

The mapper never silently reinterprets a field. It assigns only a fixed set of known keys and drops everything else with a warning that names the exact key — so an operator can see precisely what was carried across and what was left behind.

Foreign / legacy field	Maps to	Notes
name, description, license, compatibility, allowed-tools, metadata	The same spec-pure field	name is normalized to a valid slug if needed (warned); an allowed-tools list is joined into a space-separated string; a compatibility note over 500 characters draws an advisory warning
metadata.openclaw (a sibling extension namespace some other-ecosystem skills carry)	Folds into metadata.comis	skillKey -> skill-key, primaryEnv -> primary-env, os -> os, requires -> requires.bins / requires.env. Every other key (binary-installer specs, homepage, emoji, and the like) is dropped with a warning
Top-level platforms	metadata.comis -> comis.os	A string or a list of OS strings
Top-level version	metadata.version
Top-level author	metadata.author
Top-level prerequisites	comis.requires	commands -> requires.bins, env_vars -> requires.env
Legacy top-level Comis extension fields (userInvocable, disableModelInvocation, argumentHint, permissions, inputSchema, comis, mcpServers)	Relocated under metadata.comis	The mapper is a writer: it rewrites these onto the spec-pure carrier directly, so the installed SKILL.md is spec-pure and loads without a deprecation warning — the legacy top-level form is never re-emitted
Legacy top-level allowedTools (array)	allowed-tools (space-separated string)	The legacy camelCase tool restriction normalizes onto its spec-pure home
A non-prompt type declaration	Dropped (warned)	Skills import prompt-only; a script/exec type is not carried
Executable entrypoints (entrypoint, main, exec, run, scripts, command, bin, binary, executable)	Dropped (warned)	Import never maps an execution vector — only the prompt body and metadata are imported
__proto__	Refused	A prototype-pollution vector; never copied onto the manifest
Any other field	Dropped (warned)	No internal home means the field is dropped, never reinterpreted

Mapping is a format-compatibility step, not a trust decision. A mapped skill still runs through the fail-closed import scan and installs at the imported trust tier like any other import.

Template Substitution

Prompt skill bodies support placeholder syntax for dynamic content:

• Named placeholders: {placeholder} — mapped by name from the input parameters
• Positional arguments: $1, $2 (1-indexed), $@ or $ARGUMENTS (all arguments), ${@:N} (arguments from position N onwards)

Named placeholders are recommended for clarity. Positional arguments are available for quick one-off skills.

Prompt Skills

Step-by-step guide to creating your first prompt skill

Security Scanning

What Comis checks before loading your skill

Examples

Complete skill examples with walkthroughs