oh-my-pi/packages/coding-agent/docs/skills.md

omp can create skills. Ask it to build one for your use case.

Skills

Skills are self-contained capability packages that the agent loads on-demand. A skill provides specialized workflows, setup instructions, helper scripts, and reference documentation for specific tasks.

OMP follows the Agent Skills SKILL.md format (YAML frontmatter + markdown body) and exposes skills via skill:// URLs.

Example use cases:

• Web search and content extraction (Brave Search API)
• Browser automation via Chrome DevTools Protocol
• Google Calendar, Gmail, Drive integration
• PDF/DOCX processing and creation
• Speech-to-text transcription
• YouTube transcript extraction

See Skill Repositories for ready-to-use skills.

When to Use Skills

Need	Solution
Always-needed context (conventions, commands)	AGENTS.md
User triggers a specific prompt template	Slash command
Additional tool directly callable by the LLM (like read/write/edit/bash)	Custom tool
On-demand capability package (workflows, scripts, setup)	Skill

Skills are loaded when:

• The agent decides the task matches a skill's description
• The user explicitly asks to use a skill (e.g., "use the pdf skill to extract tables")

Good skill examples:

• Browser automation with helper scripts and CDP workflow
• Google Calendar CLI with setup instructions and usage patterns
• PDF processing with multiple tools and extraction patterns
• Speech-to-text transcription with API setup

Not a good fit for skills:

• "Always use TypeScript strict mode" → put in AGENTS.md
• "Review my code" → make a slash command
• Need user confirmation dialogs or custom TUI rendering → make a custom tool

Skill Structure

A skill is a directory with a SKILL.md file. Everything else is freeform. Example structure:

my-skill/
├── SKILL.md              # Required: frontmatter + instructions
├── scripts/              # Helper scripts (bash, python, node)
│   └── process.sh
├── references/           # Detailed docs loaded on-demand
│   └── api-reference.md
└── assets/               # Templates, images, etc.
    └── template.json

SKILL.md Format

---
name: my-skill
description: What this skill does and when to use it. Be specific.
---

# My Skill

## Setup

Run once before first use:
\`\`\`bash
cd /path/to/skill && npm install
\`\`\`

## Usage

\`\`\`bash
./scripts/process.sh <input>
\`\`\`

## Workflow

1. First step
2. Second step
3. Third step

Frontmatter Fields

Field	Required	Notes
name	No	Defaults to the skill directory name. Use lowercase + hyphens for compatibility.
description	Yes (OMP/custom), recommended everywhere	Used for skill matching and shown in the system prompt.

OMP ignores additional frontmatter fields, but other tooling may use them.

Naming Guidance

OMP does not enforce naming rules, but skill names must match exactly for skill://<name> and /skill:<name> lookups. For cross-tool compatibility, keep names lowercase, hyphenated, and aligned with the directory name.

File References

Use skill:// URLs to reference files inside a skill directory:

Read the full skill:
\`\`\`
skill://my-skill
\`\`\`

Read a reference file:
\`\`\`
skill://my-skill/references/api-reference.md
\`\`\`

Skill Locations

Skills are discovered from these sources (first match wins on name collisions):

• OMP user: ~/.omp/agent/skills/<skill>/SKILL.md (legacy alias: ~/.pi/agent/skills/...)
• OMP project: <cwd>/.omp/skills/<skill>/SKILL.md (legacy alias: <cwd>/.pi/skills/...)
• Claude Code: ~/.claude/skills/<skill>/SKILL.md and <cwd>/.claude/skills/<skill>/SKILL.md
• Agents standard: ~/.agents/skills/<skill>/SKILL.md
• Codex CLI: ~/.codex/skills/<skill>/SKILL.md and <cwd>/.codex/skills/<skill>/SKILL.md
• Custom directories from skills.customDirectories (scanned recursively)

Discovery skips hidden directories and node_modules, and respects .gitignore, .ignore, and .fdignore rules.

Configuration

Global settings live in ~/.omp/agent/config.yml (migrated from legacy settings.json). Project overrides live in <cwd>/.omp/settings.json or <cwd>/.pi/settings.json.

skills:
  enabled: true
  enableSkillCommands: true
  enableCodexUser: true
  enableClaudeUser: true
  enableClaudeProject: true
  enablePiUser: true
  enablePiProject: true
  customDirectories: []
  ignoredSkills: []
  includeSkills: []

Setting	Default	Description
enabled	true	Master toggle for all skills
enableSkillCommands	true	Register /skill:<name> commands in interactive mode
enableCodexUser	true	Load from ~/.codex/skills/
enableClaudeUser	true	Load from ~/.claude/skills/
enableClaudeProject	true	Load from <cwd>/.claude/skills/
enablePiUser	true	Load from ~/.omp/agent/skills/ (or ~/.pi/agent/skills/)
enablePiProject	true	Load from <cwd>/.omp/skills/ (or <cwd>/.pi/skills/)
customDirectories	[]	Additional directories to scan recursively (use absolute paths)
ignoredSkills	[]	Glob patterns to exclude (e.g., "deprecated-*")
includeSkills	[]	Glob patterns to include (empty = all)

Note: ignoredSkills takes precedence over both includeSkills and the --skills CLI flag.

CLI Filtering

Use --skills to filter skills for a specific invocation:

# Only load specific skills
omp --skills git,docker

# Glob patterns
omp --skills "git-*,docker-*"

# All skills matching a prefix
omp --skills "aws-*"

This overrides the includeSkills setting for the current session.

How Skills Work

1. At startup, omp scans enabled skill locations and filters them by settings and CLI flags.
2. If the read tool is available, skill names + descriptions are injected into the system prompt as XML.
3. When a task matches a skill, the agent loads it with read skill://<name> or skill://<name>/<path>.
4. When skills are preloaded (e.g., Task tool with explicit skills), their full contents are inlined under <preloaded_skills> and no read call is needed.

This is progressive disclosure: only descriptions are always in context, full instructions load on-demand unless explicitly preloaded.

Warnings

OMP emits warnings when:

• A skill directory or file cannot be read
• Two skills share the same name (the first loaded wins; later ones are skipped)

Example: Web Search Skill

brave-search/
├── SKILL.md
├── search.js
└── content.js

SKILL.md:

---
name: brave-search
description: Web search and content extraction via Brave Search API. Use for searching documentation, facts, or any web content.
---

# Brave Search

## Setup

\`\`\`bash
cd /path/to/brave-search && npm install
\`\`\`

## Search

\`\`\`bash
./search.js "query"              # Basic search
./search.js "query" --content    # Include page content
\`\`\`

## Extract Page Content

\`\`\`bash
./content.js https://example.com
\`\`\`

Skill Repositories

For inspiration and ready-to-use skills:

• Anthropic Skills - Official skills for document processing (docx, pdf, pptx, xlsx), web development, and more
• Pi Skills - Skills for web search, browser automation, Google APIs, transcription

Disabling Skills

CLI:

omp --no-skills

Settings:

skills:
  enabled: false

Use the granular enable* flags to disable individual sources (e.g., enableClaudeUser: false to skip ~/.claude/skills).