Prompt Skills

Create custom Markdown instruction files that teach your agents new behaviors

Prompt skills are Markdown files that teach your agents new behaviors. You write instructions in plain English, and your agent follows them when the skill is invoked. Think of them as custom training documents — except they take effect immediately.

How prompt skills work

The lifecycle of a prompt skill is straightforward:

1. You create a SKILL.md file with a frontmatter header and an instruction body
2. Comis discovers it from your skills directory on startup (or via file watching)
3. Users invoke it with /skill:name in chat, or the agent picks it up automatically when relevant
4. Instructions are injected into the agent’s context for that conversation turn

The agent reads your instructions and follows them just like a human would follow a checklist. There is no compilation, no deployment step — save the file and the skill is live.

Creating your first prompt skill

1. Create the skill file

   Create a file called SKILL.md in a new directory under your skills path:

   ~/.comis/skills/greeting/SKILL.md
   

   The directory name does not matter — Comis uses the name field inside the file to identify the skill.

2. Add the frontmatter

   Open the file and add a YAML frontmatter block at the top:

   ---
   name: greeting
   description: "A friendly greeting skill that welcomes new users"
   ---
   

   Only two fields are required:

   • name — A lowercase identifier using letters, numbers, and hyphens (1-64 characters). This is what users type after /skill:.
   • description — A short explanation of what the skill does (up to 1024 characters). The agent uses this to decide when to apply the skill automatically.
3. Write the instructions

   Below the frontmatter, write your instructions in plain Markdown:

   When greeting a new user:
   
   1. Welcome them warmly by name if provided
   2. Briefly explain what you can help with
   3. Ask what they'd like to do first
   4. Keep the tone friendly and encouraging
   

   You can use any Markdown formatting — headings, lists, bold, code blocks. The agent receives the entire body as part of its context.

4. Test it

   Send a message in chat to invoke the skill:

   /skill:greeting
   

   The agent will follow your greeting instructions for that conversation turn. If the skill has userInvocable: true (the default), the agent may also pick it up automatically when a greeting seems appropriate.

Template variables

Skill bodies support template substitution, so you can create reusable skills that accept different inputs each time they are invoked.

Named placeholders

Use curly braces to define named placeholders. They are mapped by position when invoking the skill:

---
name: review
description: "Code review skill"
argumentHint: "[language] [focus-area]"
---
Review the code for {language} best practices.
Focus especially on: {focus-area}

Invoke it with:

/skill:review python error-handling

The agent receives: “Review the code for python best practices. Focus especially on: error-handling.”

Positional placeholders

You can also use numbered positions directly:

• $1, $2, $3 — Individual arguments (1-indexed)
• $@ or $ARGUMENTS — All arguments as a single string
• ${@:2} — All arguments from position 2 onwards

---
name: translate
description: "Translate text to a target language"
argumentHint: "[language] [text to translate]"
---
Translate the following text to $1:

${@:2}

Invoke it with:

/skill:translate Spanish Hello, how are you today?

Use argumentHint in the frontmatter to show users what inputs your skill expects. This hint appears in help listings and auto-complete suggestions.

Skill discovery

Comis finds skills by scanning directories on startup and (optionally) watching for file changes.

Where Comis looks

• Default path: ./skills (configurable via the discoveryPaths setting in your config). For named agents, Comis automatically prepends the agent’s workspace skills directory (~/.comis/workspace-{agentId}/skills/) at startup.
• Root .md files in the skills directory (e.g., skills/my-skill.md)
• SKILL.md files in subdirectories (searched recursively, e.g., skills/greeting/SKILL.md)

Source categories

Each discovered skill is tagged with a source category derived from its position in the resolved discoveryPaths list:

Category	When assigned	Typical location
bundled	First entry in discoveryPaths (highest priority)	The agent’s workspace skills directory, prepended automatically (~/.comis/workspace-{agentId}/skills/, or ~/.comis/workspace/skills/ for the default agent)
workspace	Any middle entry (when there are 3+ paths)	Custom discovery paths added in your config
local	Last entry (when there are 2+ paths)	The configured ./skills path (resolves to ~/.comis/skills/ by default)

If two skills have the same name, the first one loaded wins. Because the agent’s own workspace skills directory is prepended to discoveryPaths at startup, it takes precedence over ~/.comis/skills/ and any other discovery path.

The “shared” pool at ~/.comis/skills/ is not a built-in concept — it exists because the default discoveryPaths is ["./skills"], and ./skills resolves against ~/.comis. Replacing discoveryPaths removes that pool unless you add it back explicitly.

File watching

By default, Comis watches your skill directories for changes. When you save a SKILL.md file, the skill reloads automatically within a few hundred milliseconds. You can disable this with the watchEnabled config setting.

Per-agent skill discovery

When you configure multiple agents, each named agent automatically gets its own skills directory inside its workspace folder. You do not need to set this up manually — Comis creates it at startup.

For example, an agent named researcher looks for skills in:

1. ~/.comis/workspace-researcher/skills/ (agent workspace — private to this agent)
2. ~/.comis/skills/ (shared — visible to all agents)
3. Any paths listed in discoveryPaths in the agent’s config

The default agent (set via routing.defaultAgentId) uses ~/.comis/workspace/skills/ as its workspace directory instead of a named one.

Skill scoping

Skill mutations (upload, import, delete) use a scope parameter that controls where the skill is written:

• "local" (default) — writes to the calling agent’s workspace skills directory
• "shared" — writes to the shared skills directory (~/.comis/skills/), making the skill visible to all agents

Only the default agent (configured via routing.defaultAgentId) can use scope: "shared". Non-default agents that attempt shared mutations receive an error.

Here is a multi-agent configuration example with skill isolation:

agents:
  coordinator:
    provider: anthropic
    model: claude-sonnet-4-5-20250929
    skills:
      discoveryPaths: ["./skills"]
      toolPolicy:
        profile: supervisor

  researcher:
    provider: anthropic
    model: claude-sonnet-4-5-20250929
    skills:
      discoveryPaths: ["./skills"]
      toolPolicy:
        profile: coding

routing:
  defaultAgentId: coordinator
  rules:
    - channelType: telegram
      agentId: coordinator
    - channelType: discord
      agentId: researcher

In this setup, the coordinator agent sees skills from ~/.comis/workspace/skills/ (as the default agent) plus ~/.comis/skills/. The researcher agent sees skills from ~/.comis/workspace-researcher/skills/ plus ~/.comis/skills/. Neither agent sees the other’s workspace skills.

You can manage skills per agent from the web dashboard using the agent selector and scope toggle in the Skills view.

Skills shipped with Comis

Comis comes with seven prompt skills out of the box, in the /skills/ directory at the repo root. They double as working reference manifests — copy any of them as a starting point for your own skill. Each declares the external prerequisites it needs via comis.requires, so the loader skips them gracefully when those bins or env vars are missing.

Skill	What it does	Requires
chart-visualization	Generate 26 chart types (bar, line, pie, sankey, treemap, mind maps…) via a bundled Node script	bins: [node]
deep-research	Multi-phase web research methodology — broad exploration, deep dive, source validation	None (uses web_search + web_fetch)
find-skills	Discover and install skills from the open skills.sh ecosystem	bins: [git]
image-generation	Image generation via Gemini (structured prompts, optional reference images, aspect-ratio control)	bins: [python3], env: [GEMINI_API_KEY]
log-troubleshooting	Parse and summarise NDJSON daemon logs from ~/.comis/logs/	bins: [python3]
podcast-generation	Two-host conversational podcast audio via VolcEngine TTS	bins: [python3], env: [VOLCENGINE_TTS_APPID, VOLCENGINE_TTS_ACCESS_TOKEN]
video-generation	Video generation via Gemini Video API	bins: [python3], env: [GEMINI_API_KEY]

The fastest way to learn the SKILL.md format is to read one of these. They are short, real, and exercised by every Comis install. See Examples for a walkthrough that builds on log-troubleshooting.

Advanced options

Once you are comfortable with the basics, these options give you more control:

• Tool restrictions: Use allowedTools in the frontmatter to limit which tools the agent can use while this skill is active. For example, a research skill might only allow web_search and web_fetch. See Manifest Reference for the full field list.

• Input validation: Use inputSchema to define a JSON Schema that validates arguments before the skill runs. Invalid input is rejected with a clear error message. See Manifest Reference for details.

• Dynamic context: Enable the promptSkills.enableDynamicContext config option to allow shell commands embedded in skill bodies. This lets skills pull in live data (like git status or system info) at invocation time.

  Dynamic context executes shell commands from skill files. Only enable this if you trust all skill sources. See Security Scanning for what gets scanned and blocked.

• Auto-injection: Skills can be automatically injected into conversations without explicit invocation. The agent selects relevant skills based on their descriptions. You can control how many are injected per request with the maxAutoInject config setting (default: 3).

• Model invocation control: Set disableModelInvocation: true in the frontmatter to hide a skill from the agent’s automatic selection. The skill can still be invoked explicitly with /skill:name.

Related

Manifest Reference

All SKILL.md frontmatter fields explained

Security Scanning

What gets scanned and blocked in skill files

Examples

Complete skill walkthroughs you can follow step by step