Skip to main content

​
Overview

Skills are markdown files with YAML frontmatter that inject additional context, instructions, or tools into the agent loop when a message matches. They let you extend an agent’s capabilities for specific topics without modifying its core persona. When a message matches a skill, the skill’s markdown body is appended to the system prompt for that turn.

​
Skill File Format

Skills are stored in the agent’s skills/ directory. Two layouts are supported:
  • Flat file: skills/my-skill.md
  • Directory (preferred): skills/my-skill/SKILL.md — allows bundling reference files alongside the skill

​
Basic Structure

---
name: "Go Expert"
description: "Expert knowledge for Go programming questions"
triggers:
  - "golang"
  - "go code"
  - "goroutine"
tools:
  - shell
  - read_file
---

You are an expert Go developer. When helping with Go:

- Prefer idiomatic Go patterns
- Use `go vet` and `staticcheck` for code quality
- Explain goroutine safety when relevant

## Go Version
The project uses Go 1.24 with the standard library preferred over third-party packages.

​
Frontmatter Fields

​
name
string
required
Human-readable skill name shown in skill listings.
​
description
string
required
One-line description shown in the Captain Dashboard and skill catalog.
​
triggers
array
Keywords or phrases that trigger this skill via keyword matching. Case-insensitive substring match against the incoming message.
triggers:
  - "golang"
  - "go code"
  - "goroutine"
​
tools
array
Tool names this skill is allowed to use. Restricts tool access to only these tools when the skill is active. Empty means no additional restriction.
tools:
  - shell
  - read_file
  - web_search
​
homepage
string
Optional URL to the skill’s upstream source or documentation.
​
license
string
Optional SPDX license identifier (e.g. "MIT", "Apache-2.0").
​
user-invocable
boolean
default:"true"
Whether users can explicitly invoke this skill by name. When false, the skill can only be matched automatically.
​
model-invocable
boolean
default:"false"
When true, the skill is never auto-matched — it can only be selected by the model itself.

​
Skill Matching

When a message arrives, the skill registry checks all loaded skills. The first match wins.

​
Keyword Matching

Each string in triggers is checked as a case-insensitive substring of the incoming message. This is the primary matching mechanism and requires no embeddings. 
triggers:
  - "kubernetes"
  - "k8s"
  - "helm chart"

​
Semantic Matching

When embeddings are available, cosine similarity between the message embedding and skill embeddings is used as a fallback or secondary ranking. Similarity scores range from -1.0 to 1.0; a higher score means a closer match.

​
No Match

If no skill matches, the agent runs with only SOUL.md as its system context.

​
Managing Skills

​
Via CLI

# List skills for an agent
meepagateway agent skill list meepa

# Add a skill from a local file
meepagateway agent skill add meepa ./my-skill.md

# Remove a skill
meepagateway agent skill remove meepa go-expert

# Browse the skill catalog
meepagateway agent skill catalog

# Install a skill from the catalog
meepagateway agent skill install meepa go-expert
All ID arguments are optional — omitting them shows an interactive picker.

​
Via Captain Dashboard

Navigate to Agents → → Skills to view, add, edit, and remove skills through the web UI.

​
Via API

# List skills
curl -H "Authorization: Bearer $API_KEY" \
  http://localhost:63372/api/agents/meepa/skills

# Upload a skill file
curl -X POST -H "Authorization: Bearer $API_KEY" \
  -F "file=@my-skill.md" \
  http://localhost:63372/api/agents/meepa/skills

# Delete a skill
curl -X DELETE -H "Authorization: Bearer $API_KEY" \
  http://localhost:63372/api/agents/meepa/skills/go-expert

​
Skill Catalog

The skill catalog is a curated library of ready-made skills. Browse and install from the catalog: 
# Browse available skills
meepagateway agent skill catalog

# Install a skill by name
meepagateway agent skill install meepa code-runner
The catalog is also browsable from the Captain Dashboard under Skills → Catalog.

​
Examples

​
Flat File: skills/devops.md

---
name: "DevOps Helper"
description: "Infrastructure and deployment assistance"
triggers:
  - "deploy"
  - "docker"
  - "kubernetes"
  - "ci/cd"
tools:
  - shell
  - read_file
  - web_fetch
---

You are a DevOps expert. When helping with infrastructure:

- Prefer immutable deployments
- Always check `docker ps` and logs before suggesting restarts
- Kubernetes resources should include resource limits

​
Directory Format: skills/agent-browser/SKILL.md

---
name: "Web Browser"
description: "Browse and summarize web pages"
triggers:
  - "browse"
  - "visit url"
  - "fetch page"
tools:
  - web_fetch
  - web_search
---

You can browse the web. When given a URL:
1. Use `web_fetch` to retrieve the page
2. Summarize the relevant content
3. Include the source URL in your response

See `REFERENCE.md` in this directory for supported URL patterns.

​
How Skills Integrate Into the System Prompt

When a skill matches, its markdown body is appended after SOUL.md and before the auto-generated tool/memory reference (AGENTS.md). The final system prompt structure is: 
[SOUL.md content]

[Matched skill body]

[AGENTS.md — tools, memory, skill list]

[Injected memory facts]