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

The keyword detection system in 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, 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 (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 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:

- 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

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 to perform the analysis workflow.

Explicit Token Override

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

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 (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)
./.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 definitions from the .codex/skills/ directory
• All rules are defined in 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 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 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.

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