Skip to main content
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:
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:
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:
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:
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:
Invoke it with:
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
Invoke it with:
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: 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:
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.
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.

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