# How to Create and Register Custom Skills in oh-my-claudecode's .omc/skills/ Directory

> Easily create and register custom skills in oh-my-claudecode by adding a SKILL.md file to your .omc/skills/ directory. OMC automatically discovers and integrates your new skills without extra setup.

- Repository: [Bellman/oh-my-claudecode](https://github.com/Yeachan-Heo/oh-my-claudecode)
- Tags: how-to-guide
- Published: 2026-03-27

---

**Create a directory under `.omc/skills/`, add a [`SKILL.md`](https://github.com/Yeachan-Heo/oh-my-claudecode/blob/main/SKILL.md) file with required front-matter (id, name, description, triggers, source), and commit the folder—OMC automatically discovers and registers the skill without additional configuration.**

Oh-my-claudecode (OMC) treats project-level skills as first-class citizens by auto-discovering them from the `.omc/skills/` directory. When you create a skill folder containing a properly formatted [`SKILL.md`](https://github.com/Yeachan-Heo/oh-my-claudecode/blob/main/SKILL.md) file, the skill-loader ([`src/hooks/learner/finder.ts`](https://github.com/Yeachan-Heo/oh-my-claudecode/blob/main/src/hooks/learner/finder.ts)) parses the metadata and immediately makes the skill available via the `/skill` CLI and magic-keyword detection.

## Understanding the .omc/skills/ Directory Structure

OMC defines the canonical project skills location through the `PROJECT_SKILLS_SUBDIR` constant in [`src/hooks/learner/constants.ts`](https://github.com/Yeachan-Heo/oh-my-claudecode/blob/main/src/hooks/learner/constants.ts), which resolves to `.omc/skills/`. This directory is automatically created if missing when you run skill-related commands via `ensureSkillsDir`, and it is explicitly preserved in version control through git exclude rules in [`scripts/setup-claude-md.sh`](https://github.com/Yeachan-Heo/oh-my-claudecode/blob/main/scripts/setup-claude-md.sh) (lines 81-82).

The skill-loader scans this directory recursively, looking for [`SKILL.md`](https://github.com/Yeachan-Heo/oh-my-claudecode/blob/main/SKILL.md) files. Each discovered skill is validated against `REQUIRED_METADATA_FIELDS` defined in [`src/hooks/learner/constants.ts`](https://github.com/Yeachan-Heo/oh-my-claudecode/blob/main/src/hooks/learner/constants.ts) (lines 40-42), which mandates the keys `id`, `name`, `description`, `triggers`, and `source` in the front-matter.

## Step-by-Step Guide to Creating a Custom Skill

### 1. Create the Skill Directory

Create a new folder under `.omc/skills/` using lowercase, hyphenated naming conventions:

```bash
mkdir -p .omc/skills/my-logger

```

If the directory does not exist, OMC creates it automatically when you invoke `/skill add` or any skill management command.

### 2. Write the SKILL.md File

Inside your skill folder, create a [`SKILL.md`](https://github.com/Yeachan-Heo/oh-my-claudecode/blob/main/SKILL.md) file with YAML front-matter followed by markdown content. The front-matter must include all required fields:

- **id**: Unique identifier (usually matching the folder name)
- **name**: Human-readable name
- **description**: Brief explanation of purpose
- **triggers**: Array of keywords that activate the skill
- **source**: Set to `project` to indicate local scope

The body should detail usage, examples, and any bundled resources.

### 3. Add Supporting Resources

Place any additional files (scripts, templates, configuration files) next to [`SKILL.md`](https://github.com/Yeachan-Heo/oh-my-claudecode/blob/main/SKILL.md) in the same directory. OMC automatically detects these assets via [`src/utils/skill-resources.ts`](https://github.com/Yeachan-Heo/oh-my-claudecode/blob/main/src/utils/skill-resources.ts) and renders a *Skill Resources* section in the skill documentation.

### 4. Verify Registration

Run the built-in skill listing tool to confirm discovery:

```bash
omc /skill list

```

Your skill should appear under **PROJECT SKILLS**, indicating successful registration via `loadLocalTool` ([`src/tools/skills-tools.ts`](https://github.com/Yeachan-Heo/oh-my-claudecode/blob/main/src/tools/skills-tools.ts)).

## Minimal SKILL.md Example

Place this file at [`.omc/skills/my-logger/SKILL.md`](https://github.com/Yeachan-Heo/oh-my-claudecode/blob/main/.omc/skills/my-logger/SKILL.md):

```yaml
---
id: my-logger
name: my-logger
description: Simple structured logger for Node.js projects
triggers:
  - log
  - logger
  - logging
source: project
---

# My Logger Skill

## Purpose

Provides a helper function `logInfo(message: string)` that writes JSON-lines
to `stdout` with timestamps.

## When to Activate

Use the trigger keywords `log`, `logger` or `logging` in your prompt.

## Usage

```ts
import { logInfo } from './my-logger';

logInfo('Server started');

```

```

Any files like [`helper.ts`](https://github.com/Yeachan-Heo/oh-my-claudecode/blob/main/helper.ts) or [`templates/logger-config.md`](https://github.com/Yeachan-Heo/oh-my-claudecode/blob/main/templates/logger-config.md) placed in the same directory will be automatically listed as skill resources.

## Using the Interactive Wizard (Optional)

Instead of manual creation, use the built-in wizard documented in [`skills/skill/SKILL.md`](https://github.com/Yeachan-Heo/oh-my-claudecode/blob/main/skills/skill/SKILL.md) (lines 50-66):

```bash
omc /skill add my-logger

```

The wizard prompts for:
1. Skill name (validated as lowercase-hyphenated)
2. Description
3. Comma-separated trigger keywords
4. Scope (select **project** to target `.omc/skills/`)

It then scaffolds the directory structure and populates a starter [`SKILL.md`](https://github.com/Yeachan-Heo/oh-my-claudecode/blob/main/SKILL.md) with the correct front-matter template.

## How OMC Discovers and Prioritizes Skills

When OMC initializes, `findSkillFiles` in [`src/hooks/learner/finder.ts`](https://github.com/Yeachan-Heo/oh-my-claudecode/blob/main/src/hooks/learner/finder.ts) (lines 64-76) walks multiple locations:

- `projectRoot/.omc/skills/` (project scope)
- `projectRoot/.agents/skills/` (compatibility read-only)
- `$HOME/.omc/skills/` and `$HOME/.claude/skills/omc-learned/` (user scope)

Project-level skills receive **priority** over user-level skills. If duplicate `id` values exist, the project version wins according to the resolution logic in [`src/hooks/learner/loader.ts`](https://github.com/Yeachan-Heo/oh-my-claudecode/blob/main/src/hooks/learner/loader.ts) (lines 24-30).

The loader parses each [`SKILL.md`](https://github.com/Yeachan-Heo/oh-my-claudecode/blob/main/SKILL.md), validates required metadata, and registers valid skills in the learned-skill cache, making them instantly accessible via `/skill <name>`, trigger keywords, or slash-command injection.

## Summary

- **Create** a directory under `.omc/skills/<skill-name>/` to establish the skill location.
- **Write** a [`SKILL.md`](https://github.com/Yeachan-Heo/oh-my-claudecode/blob/main/SKILL.md) with valid YAML front-matter including `id`, `name`, `description`, `triggers`, and `source: project`.
- **Bundle** additional resources in the same folder; OMC auto-generates resource listings.
- **Commit** the `.omc/skills/` directory—git tracking is preserved by the setup script.
- **Verify** using `omc /skill list` to see your skill under PROJECT SKILLS.

## Frequently Asked Questions

### What happens if I forget a required front-matter field in SKILL.md?

OMC validates skills against `REQUIRED_METADATA_FIELDS` in [`src/hooks/learner/constants.ts`](https://github.com/Yeachan-Heo/oh-my-claudecode/blob/main/src/hooks/learner/constants.ts). If any required key (`id`, `name`, `description`, `triggers`, `source`) is missing, the skill-loader skips the file and the skill will not appear in `/skill list` or trigger detection.

### Can I override a user-level skill with a project-level skill?

Yes. According to the resolution logic in [`src/hooks/learner/loader.ts`](https://github.com/Yeachan-Heo/oh-my-claudecode/blob/main/src/hooks/learner/loader.ts), project-level skills take precedence over user-level skills when `id` conflicts occur. Place your custom version in `.omc/skills/` to override global definitions stored in `$HOME/.omc/skills/`.

### How do I activate a custom skill during a Claude session?

Use the explicit slash command `omc /skill <skill-id>` or include any of the trigger keywords defined in your [`SKILL.md`](https://github.com/Yeachan-Heo/oh-my-claudecode/blob/main/SKILL.md) front-matter within your prompt. OMC's magic-keyword detection scans for these triggers and automatically injects the skill context.

### Is the .omc/skills/ directory safe to commit to git?

Yes. The setup script ([`scripts/setup-claude-md.sh`](https://github.com/Yeachan-Heo/oh-my-claudecode/blob/main/scripts/setup-claude-md.sh) lines 81-82) explicitly un-ignores `.omc/skills/` and its contents in the local git exclude block, ensuring your custom skills are tracked with your repository and shared across team environments.