# How to Write OMP Skills Using the SKILL.md Format

> Learn how to write OMP skills using the SKILL.md format for your Oh My Pi repository. Follow this guide to create effective knowledge packs with YAML front matter.

- Repository: [Can Bölük/oh-my-pi](https://github.com/can1357/oh-my-pi)
- Tags: how-to-guide
- Published: 2026-05-21

---

**An OMP skill is a self-contained knowledge pack that requires a YAML front-matter block with `name` and `description` in a [`SKILL.md`](https://github.com/can1357/oh-my-pi/blob/main/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`](https://github.com/can1357/oh-my-pi/blob/main/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`](https://github.com/can1357/oh-my-pi/blob/main/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`](https://github.com/can1357/oh-my-pi/blob/main/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`](https://github.com/can1357/oh-my-pi/blob/main/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`](https://github.com/can1357/oh-my-pi/blob/main/docs/skills.md) (lines 52‑58) and mapped to the internal `Skill` object shape in [`packages/coding-agent/src/extensibility/skills.ts`](https://github.com/can1357/oh-my-pi/blob/main/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:

```markdown
---
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`](https://github.com/can1357/oh-my-pi/blob/main/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:

```markdown
---
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:

```typescript
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`](https://github.com/can1357/oh-my-pi/blob/main/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`](https://github.com/can1357/oh-my-pi/blob/main/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`](https://github.com/can1357/oh-my-pi/blob/main/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`](https://github.com/can1357/oh-my-pi/blob/main/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`](https://github.com/can1357/oh-my-pi/blob/main/.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`](https://github.com/can1357/oh-my-pi/blob/main/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`](https://github.com/can1357/oh-my-pi/blob/main/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.