# How the Keyword Detection System Auto-Activates Skills in oh-my-codex AGENTS.md

> Discover how the keyword detection system in oh-my-codex AGENTS.md automatically activates skills. Learn about message scanning, skill command resolution, and instant workflow execution.

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

---

**The keyword detection system in [`AGENTS.md`](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/AGENTS.md) scans user messages for case-insensitive keyword matches, resolves them to specific `$skill` commands via a lookup table, and immediately executes the corresponding workflow without user confirmation.**

The oh-my-codex framework implements a zero-friction automation layer that transforms plain-text conversation into executed agent workflows. According to the source code in [`AGENTS.md`](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/AGENTS.md), the **keyword detection system** operates through a three-stage pipeline that bridges natural language input to skill invocation.

## How Keyword Detection Works in AGENTS.md

The detection engine operates in three distinct stages defined in the **Keyword detection** section of [`AGENTS.md`](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/AGENTS.md) (lines 28-65).

### Stage 1: Scanning for Case-Insensitive Matches

The runtime treats the entire user message as a single string and applies **case-insensitive regex** matching against entries in the **Supported workflow triggers** list (line 128). Matches do not require word boundaries; any substring containing the keyword will trigger detection.

### Stage 2: Resolving Skills via the Keyword-to-Skill Table

When a keyword match occurs, the system consults the **keyword-to-skill table** (line 35) to map the detected term to its corresponding `$skill` command. The resolution follows strict priority rules:

- **Explicit `$name` tokens** (e.g., `$team`, `$analyze`) are parsed first and executed **left-to-right**
- These explicit invocations **override** any implicit keyword matches in the same message
- If multiple non-explicit keywords match, the **most specific** entry wins (e.g., "ralph-plan" takes precedence over "ralph")

### Stage 3: Auto-Activating the Matched Skill

Once resolved, the framework **immediately executes** the `$skill` without prompting for confirmation. As stated in [`AGENTS.md`](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/AGENTS.md) lines 30-33: *"When the user message contains a mapped keyword, activate the corresponding skill immediately."* The system loads the skill definition from `./.codex/skills/<skill_name>/SKILL.md` and initiates the associated workflow.

## Priority and Conflict Resolution Rules

The **Detection rules** block (lines 54-58) establishes three governing policies for handling overlapping matches:

```text
- Keywords are case-insensitive and match anywhere in the user message.
- Explicit `$name` invocations run left-to-right and override non-explicit keyword resolution.
- If multiple non-explicit keywords match, use the most specific match.

```

This specificity rule ensures that longer, more precise keywords take precedence over generic ones. For example, if a message contains both "ralph" and "ralph-plan", the system selects the latter and invokes `$ralplan` rather than `$ralph`.

## Practical Examples of Keyword Activation

### Implicit Keyword Trigger

```text
User: "Can you run a quick analysis on the repo?"

```

The engine detects **"analyze"** (case-insensitive), maps it to `$analyze` via the keyword-to-skill table, and automatically loads [`./.codex/skills/analyze/SKILL.md`](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/./.codex/skills/analyze/SKILL.md) to perform the analysis workflow.

### Explicit Token Override

```text
User: "$team Please generate a PRD for the new feature and also do an ultrawork scan."

```

1. The parser processes `$team` first (left-to-right priority)
2. After `$team` execution, the remaining text contains **"ultrawork"**, which maps to `$ultrawork` and launches subsequently

### Specificity-Based Resolution

```text
User: "I want a ralph run and also a ralph-plan for the test suite."

```

Both keywords match, but **"ralph-plan"** wins due to the specificity rule, invoking `$ralplan` instead of the shorter `$ralph` match.

## Key Files and Architecture

| File | Role in Keyword Detection |
|------|--------------------------|
| [`AGENTS.md`](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/AGENTS.md) (lines 28-65) | Core definition of keyword-to-skill mappings, matching rules, and activation policies |
| `./.codex/skills/<skill>/SKILL.md` | Concrete skill implementations auto-loaded when keywords trigger (e.g., [`./.codex/skills/ralph/SKILL.md`](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/./.codex/skills/ralph/SKILL.md)) |
| `./.codex/skills/` directory | Container for all skill definitions available to the keyword detection system |

## Summary

- The keyword detection system scans messages using **case-insensitive substring matching** against predefined triggers
- **Explicit `$name` tokens** take precedence and execute left-to-right, overriding implicit matches
- When multiple implicit keywords match, the **most specific** (longest) keyword wins
- Matched skills **auto-activate immediately** by loading their [`SKILL.md`](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/SKILL.md) definitions from the `.codex/skills/` directory
- All rules are defined in [`AGENTS.md`](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/AGENTS.md) lines 28-65, with the keyword table at line 35 and detection rules at lines 54-58

## Frequently Asked Questions

### How does the system handle multiple keywords in a single message?

Explicit `$name` tokens are processed first from left to right. After explicit processing, remaining text is scanned for implicit keywords. If multiple implicit keywords match, the most specific (longest) keyword takes precedence according to the detection rules in [`AGENTS.md`](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/AGENTS.md) lines 54-58.

### Does the keyword detection require exact word boundaries?

No. The system uses case-insensitive regex matching that triggers on any substring occurrence. A keyword like "analyze" will match within "analysis", "reanalyze", or standalone "analyze" without requiring whitespace delimiters.

### Where are the skill definitions stored when auto-activation occurs?

The framework loads skill definitions from `./.codex/skills/<skill_name>/SKILL.md`. For example, when the "ralph" keyword triggers, the system reads [`./.codex/skills/ralph/SKILL.md`](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/./.codex/skills/ralph/SKILL.md) and executes the workflow defined within that file.

### Can explicit skill commands override detected keywords?

Yes. When a user includes explicit `$name` tokens (like `$team` or `$analyze`), these are parsed and executed first, overriding any implicit keyword resolution that might conflict with the explicit command.