Skills

Markdown skill files that inject context and instructions into the agent when triggered

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

Users can request skills on the fly. During a conversation, a user can say “install the code-runner skill” and the agent will pull it from the catalog and load it immediately — no restart or CLI needed.

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]