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

Create a directory under .omc/skills/, add a 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 file, the skill-loader (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, 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 (lines 81-82).

The skill-loader scans this directory recursively, looking for SKILL.md files. Each discovered skill is validated against REQUIRED_METADATA_FIELDS defined in 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:

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 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 in the same directory. OMC automatically detects these assets via 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:

omc /skill list

Your skill should appear under PROJECT SKILLS, indicating successful registration via loadLocalTool (src/tools/skills-tools.ts).

Minimal SKILL.md Example

Place this file at .omc/skills/my-logger/SKILL.md:

---
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 with the correct front-matter template.

How OMC Discovers and Prioritizes Skills

When OMC initializes, findSkillFiles in 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 (lines 24-30).

The loader parses each 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 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. 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, 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 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 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.

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