> ## Documentation Index
> Fetch the complete documentation index at: https://comis-feature-skill-archive-import.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# 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:
```yaml theme={}
---
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
```yaml theme={}
---
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`:
```yaml theme={}
---
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:
```json theme={}
{
"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:
```json theme={}
{
"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:
```json theme={}
{
"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:
```yaml theme={}
---
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](/skills/importing) 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](/skills/security-scanning#import-time-scanning) and installs at the `imported` [trust tier](/skills/importing#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.
Step-by-step guide to creating your first prompt skill
What Comis checks before loading your skill
Complete skill examples with walkthroughs