How to Write OMP Skills Using the SKILL.md Format

An OMP skill is a self-contained knowledge pack that requires a YAML front-matter block with name and description in a SKILL.md file placed within its own directory under a configured skills/ root.

The oh-my-pi (OMP) coding agent loads specialized capabilities through modular units called skills. To create these extensions, you must follow the SKILL.md format, which uses a specific directory layout and YAML front-matter metadata to define how the agent discovers and applies each skill.

Directory and File Structure Requirements

To be discovered automatically, each skill must reside in its own directory containing a file named exactly SKILL.md. The runtime scans for the pattern */SKILL.md one level deep under any configured skills/ root directory.

Valid scan locations include:

• The built-in user directory at ~/.omp/agent/skills/
• Project-local directories at .omp/skills/

As documented in docs/skills.md (lines 27‑31), the required layout follows the pattern <skills-root>/<skill-name>/SKILL.md. The scanner is non-recursive—it only examines immediate subdirectories of the configured roots, ignoring nested paths unless you explicitly add parent directories to skills.customDirectories.

SKILL.md Front-Matter Specification

Every SKILL.md file must start with a YAML front-matter block containing at least two fields:

• name – The unique identifier used to invoke the skill via skill://<name>
• description – A brief summary explaining the skill's purpose (mandatory for native and custom-directory skills per docs/skills.md lines 62‑66)

Optional fields control runtime behavior:

• globs – An array of file patterns (e.g., ["**/*.pdf"]) that trigger auto-application when matching files are present
• alwaysApply – Boolean flag that forces injection into the context even without explicit requests
• hide – Boolean that keeps the skill reachable but omits it from the system-prompt skills list

These specifications are defined in docs/skills.md (lines 52‑58) and mapped to the internal Skill object shape in packages/coding-agent/src/extensibility/skills.ts (lines 78‑88).

Creating a Minimal OMP Skill

The simplest valid skill requires only the mandatory front-matter fields followed by Markdown content:

---
name: greet
description: Sends a friendly greeting.
---

# Greet Skill

The agent can use this skill to produce a short greeting message.

Place this file at ~/.omp/agent/skills/greet/SKILL.md. This example follows the exact structure used in the test suite at packages/coding-agent/test/fixtures/skills/valid-skill/SKILL.md.

Advanced Skill Configuration

For skills that need automatic file association or visibility control, include the optional front-matter fields:

---
name: pdf
description: Helpers for PDF manipulation.
globs: ["**/*.pdf"]
alwaysApply: true
hide: false
---

# PDF Skill

Provides commands to extract text, split pages, and merge PDFs.

The globs array enables automatic activation when the workspace contains matching files. Setting alwaysApply to true ensures the skill content is always available in the agent's context, while hide set to true removes it from the displayed skills list without disabling the skill:// invocation endpoint.

Programmatic Skill Usage

Internally, the agent constructs skill prompts using the buildSkillPromptMessage function from @oh-my-pi/agent. This utility strips the YAML front-matter and appends metadata lines:

import { buildSkillPromptMessage } from "@oh-my-pi/agent";

const skill = { 
  name: "greet", 
  filePath: "/home/user/.omp/agent/skills/greet/SKILL.md" 
};
const { message, details } = await buildSkillPromptMessage(skill, "Alice");

// message contains the skill body plus meta information
// details can be inspected by the UI or logger

As implemented in packages/coding-agent/src/extensibility/skills.ts (lines 92‑104), this function processes the raw markdown and prepares it for injection into the conversation context.

Skill Discovery and Collision Handling

The discovery mechanism in packages/coding-agent/src/extensibility/skills.ts (lines 87‑95 and 124‑133) implements a first-found-wins strategy. When multiple skills share the same name, the first discovered instance is loaded while subsequent duplicates generate warning logs. This prevents namespace collisions while alerting you to configuration conflicts across the user and project skill directories.

Summary

• Each skill lives in its own directory as <skills-root>/<skill-name>/SKILL.md
• The SKILL.md file must contain YAML front-matter with name and description fields
• Optional fields globs, alwaysApply, and hide control auto-application and visibility
• Discovery is non-recursive, scanning only one level deep under configured roots
• Duplicate skill names trigger warnings, with the first found taking precedence
• Use buildSkillPromptMessage to programmatically render skill content

Frequently Asked Questions

What is the required directory structure for an OMP skill?

Each skill must occupy its own subdirectory immediately under a configured skills/ root, containing a single file named SKILL.md. The runtime scans one level deep for the pattern */SKILL.md, matching directories like ~/.omp/agent/skills/my-skill/SKILL.md or .omp/skills/my-skill/SKILL.md.

Which fields are mandatory in the SKILL.md front-matter?

The YAML front-matter must include name (the skill identifier) and description (the human-readable summary). These fields are enforced during discovery as documented in docs/skills.md (lines 62‑66) and mapped to the internal Skill interface in the TypeScript implementation.

How does OMP handle duplicate skill names?

When multiple skills share the same name field across different directories, the first skill discovered in the scan order is loaded and subsequent duplicates are skipped with a warning log. This first-found-wins logic is implemented in packages/coding-agent/src/extensibility/skills.ts (lines 124‑133).

Can I nest skills in subdirectories?

No, the scanner is non-recursive by design and only examines immediate subdirectories of the configured skill roots. To include skills from nested paths, add the specific parent directory to the skills.customDirectories configuration array.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}