Skill Manifest

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.

Required Fields

Every manifest must include these two fields:

Field	Type	Description
`name`	string	Unique skill name. Lowercase letters, numbers, and hyphens only. 1-64 characters.
`description`	string	Human-readable description shown to users and agents. 1-1024 characters.

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

---
name: my-skill
description: "A brief description of what this skill does"
---
Your instructions here...

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

Optional Fields

These fields give you more control over how the skill behaves:

Field	Type	Default	Description
`type`	string	`"prompt"`	Always “prompt” for Markdown instruction skills.
`version`	string	—	Semver version string (e.g., “1.0.0”). Useful for tracking changes to your skill over time.
`license`	string	—	SPDX license identifier (e.g., “MIT”, “Apache-2.0”). Declares the license for shared skills.
`userInvocable`	boolean	`true`	Registry metadata for invocation-capable consumers. The current chat daemon does not wire `/skill:name` dispatch.
`disableModelInvocation`	boolean	`false`	When `true`, hides the skill from the model-facing capability index.
`allowedTools`	string[]	`[]`	Restriction metadata returned with loaded skill content. Enforce agent access separately with tool policy; this field is not an OS sandbox.
`argumentHint`	string	—	Input hint metadata for invocation-capable consumers. It does not enable chat dispatch.
`inputSchema`	object	—	A JSON Schema that validates the input parameters passed to this skill. Useful for skills that expect structured input.
`metadata`	object	—	Arbitrary key-value pairs for your own use. Comis does not interpret these — they are available for custom tooling or organizational tags.

Example with Optional Fields

---
name: translate
description: "Translate text between languages"
version: "1.2.0"
license: "MIT"
userInvocable: true
argumentHint: "[text] [target-language]"
allowedTools:
  - web_fetch
metadata:
  category: "utilities"
  author: "team"
---
Translate the following text to {target-language}:

{text}

Permissions

The permissions block declares resources a skill expects. The manifest parser preserves these values, but the block is not a kernel permission boundary and does not, by itself, grant or deny the daemon’s access. Enforce filesystem, network, environment, and tool access through the relevant runtime controls.

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

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

Keep declarations accurate for review and custom consumers, then mirror the least-privilege decision in agent tool policy, safe paths, exec isolation, and host permissions.

Comis Namespace

The comis: block contains fields specific to the Comis platform. These control runtime requirements and platform-level behavior.

Field	Type	Description
`comis.os`	string[]	Target operating systems (e.g., `["linux", "darwin"]`). The skill will only load on matching systems.
`comis.requires.bins`	string[]	Required binary executables that must be available on the system (e.g., `["git", "ffmpeg"]`). The skill will not load if any are missing.
`comis.requires.env`	string[]	Required environment variables. The skill will not load if any are unset.
`comis.skill-key`	string	Override the auto-generated skill slug. By default, the slug is derived from the `name` field.
`comis.primary-env`	string	Display and grouping hint for the primary runtime environment. Used for organizational purposes in the dashboard.
`comis.command-dispatch`	string	Metadata tag for command routing. Used by advanced automation to direct invocations to specific handlers.

comis:
  os: ["linux"]
  requires:
    bins: ["ffmpeg", "git"]
    env: ["OPENAI_API_KEY"]
  skill-key: "video-processor"

The comis.requires fields are checked at startup using 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, you can attach a JSON Schema in the inputSchema field. The schema is stored alongside the manifest and surfaced as documentation — agents can read it to understand what arguments the skill expects.

---
name: generate-report
description: "Generate a formatted report from data"
inputSchema:
  type: object
  properties:
    format:
      type: string
      enum: ["pdf", "html", "markdown"]
    title:
      type: string
  required: ["format"]
---
Generate a {format} report titled "{title}" from the provided data.

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 fields from every section:

---
name: daily-report
description: "Generate a daily activity report from project logs"
type: prompt
version: "2.1.0"
license: "MIT"
userInvocable: true
disableModelInvocation: false
argumentHint: "[project-name]"
allowedTools:
  - read
  - web_fetch
permissions:
  fsRead: ["./logs/*.log", "./config/projects.yaml"]
  fsWrite: ["./reports/"]
  net: ["api.github.com"]
  env: ["GITHUB_TOKEN"]
inputSchema:
  type: object
  properties:
    project-name:
      type: string
  required: ["project-name"]
metadata:
  category: "reporting"
  team: "ops"
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.

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

Agents

Channels

Skills and integrations

Agent tools

Media

Web dashboard

Skill Manifest

Required Fields

Optional Fields

Example with Optional Fields

Permissions

Comis Namespace

Input Schema

Complete Example

Template Substitution

Prompt Skills

Security Scanning

Examples

​Required Fields

​Optional Fields

​Example with Optional Fields

​Permissions

​Comis Namespace

​Input Schema

​Complete Example

​Template Substitution

Prompt Skills

Security Scanning

Examples

Required Fields

Optional Fields

Example with Optional Fields

Permissions

Comis Namespace

Input Schema

Complete Example

Template Substitution