Local Skills Setup

Local Skills Setup

Native Subagent Protocol (Codex)

Codex supports native subagents. Delegate with spawn_agent, coordinate with send_input, collect via wait_agent, and clean up with close_agent.

Execution preference:

1. Use native subagents first for independent workstreams (parallel when possible).
2. Merge results in main thread and run final verification.
3. Fallback only when delegation is blocked: use the [ANALYST]/[ARCHITECT]/[EXECUTOR]/[REVIEWER] structure in a single response.

Minimal orchestration pattern:

spawn_agent -> send_input (optional) -> wait_agent -> close_agent

Codex invocation: use $local-skills-setup ... or local-skills-setup: ...

This skill provides a guided wizard for setting up and managing your local learned skills. Skills are reusable problem-solving patterns that Codex automatically applies when it detects matching triggers.

Why Local Skills?

Local skills allow you to capture hard-won insights and solutions that are specific to your codebase or workflow:

• Project-level skills (.omc/skills/) - Version-controlled with your repo
• User-level skills (~/.codex/skills/omc-learned/) - Portable across all your projects

When you solve a tricky bug or discover a non-obvious workaround, you can extract it as a skill. Codex will automatically detect and apply these skills in future conversations when it sees matching triggers.

Interactive Workflow

Step 1: Directory Check and Setup

First, check if skill directories exist and create them if needed:

# Check and create user-level skills directory
USER_SKILLS_DIR="$HOME/.codex/skills/omc-learned"
if [ -d "$USER_SKILLS_DIR" ]; then
  echo "User skills directory exists: $USER_SKILLS_DIR"
else
  mkdir -p "$USER_SKILLS_DIR"
  echo "Created user skills directory: $USER_SKILLS_DIR"
fi

# Check and create project-level skills directory
PROJECT_SKILLS_DIR=".omc/skills"
if [ -d "$PROJECT_SKILLS_DIR" ]; then
  echo "Project skills directory exists: $PROJECT_SKILLS_DIR"
else
  mkdir -p "$PROJECT_SKILLS_DIR"
  echo "Created project skills directory: $PROJECT_SKILLS_DIR"
fi

Step 2: Skill Scan and Inventory

Scan both directories and show a comprehensive inventory:

# Scan user-level skills
echo "=== USER-LEVEL SKILLS (~/.codex/skills/omc-learned/) ==="
if [ -d "$HOME/.codex/skills/omc-learned" ]; then
  USER_COUNT=$(find "$HOME/.codex/skills/omc-learned" -name "*.md" 2>/dev/null | wc -l)
  echo "Total skills: $USER_COUNT"

  if [ $USER_COUNT -gt 0 ]; then
    echo ""
    echo "Skills found:"
    find "$HOME/.codex/skills/omc-learned" -name "*.md" -type f -exec sh -c '
      FILE="$1"
      NAME=$(grep -m1 "^name:" "$FILE" 2>/dev/null | sed "s/name: //")
      DESC=$(grep -m1 "^description:" "$FILE" 2>/dev/null | sed "s/description: //")
      MODIFIED=$(stat -c "%y" "$FILE" 2>/dev/null || stat -f "%Sm" "$FILE" 2>/dev/null)
      echo "  - $NAME"
      [ -n "$DESC" ] && echo "    Description: $DESC"
      echo "    Modified: $MODIFIED"
      echo ""
    ' sh {} \;
  fi
else
  echo "Directory not found"
fi

echo ""
echo "=== PROJECT-LEVEL SKILLS (.omc/skills/) ==="
if [ -d ".omc/skills" ]; then
  PROJECT_COUNT=$(find ".omc/skills" -name "*.md" 2>/dev/null | wc -l)
  echo "Total skills: $PROJECT_COUNT"

  if [ $PROJECT_COUNT -gt 0 ]; then
    echo ""
    echo "Skills found:"
    find ".omc/skills" -name "*.md" -type f -exec sh -c '
      FILE="$1"
      NAME=$(grep -m1 "^name:" "$FILE" 2>/dev/null | sed "s/name: //")
      DESC=$(grep -m1 "^description:" "$FILE" 2>/dev/null | sed "s/description: //")
      MODIFIED=$(stat -c "%y" "$FILE" 2>/dev/null || stat -f "%Sm" "$FILE" 2>/dev/null)
      echo "  - $NAME"
      [ -n "$DESC" ] && echo "    Description: $DESC"
      echo "    Modified: $MODIFIED"
      echo ""
    ' sh {} \;
  fi
else
  echo "Directory not found"
fi

# Summary
TOTAL=$((USER_COUNT + PROJECT_COUNT))
echo "=== SUMMARY ==="
echo "Total skills across all directories: $TOTAL"

Step 3: Quick Actions Menu

After scanning, offer these options in plain text with numbered choices:

Question: "What would you like to do with your local skills?"

Options:

1. Add new skill - Start the skill creation wizard
2. List all skills with details - Show comprehensive skill inventory with triggers
3. Scan conversation for patterns - Analyze current conversation for skill-worthy patterns
4. Import skill - Import a skill from URL or paste content
5. Done - Exit the wizard

Option 1: Add New Skill

If user chooses "Add new skill", invoke the learner skill:

Use the Skill tool to invoke: learner

This will guide them through the extraction process with quality validation.

Option 2: List All Skills with Details

Show detailed information including trigger keywords:

echo "=== DETAILED SKILL INVENTORY ==="
echo ""

# Function to show skill details
show_skill_details() {
  FILE="$1"
  LOCATION="$2"

  echo "---"
  echo "Location: $LOCATION"
  echo "File: $(basename "$FILE")"

  # Extract frontmatter
  NAME=$(grep -m1 "^name:" "$FILE" 2>/dev/null | sed "s/name: //")
  DESC=$(grep -m1 "^description:" "$FILE" 2>/dev/null | sed "s/description: //")
  TRIGGERS=$(grep -m1 "^triggers:" "$FILE" 2>/dev/null | sed "s/triggers: //")
  QUALITY=$(grep -m1 "^quality:" "$FILE" 2>/dev/null | sed "s/quality: //")

  [ -n "$NAME" ] && echo "Name: $NAME"
  [ -n "$DESC" ] && echo "Description: $DESC"
  [ -n "$TRIGGERS" ] && echo "Triggers: $TRIGGERS"
  [ -n "$QUALITY" ] && echo "Quality: $QUALITY"

  # Last modified
  MODIFIED=$(stat -c "%y" "$FILE" 2>/dev/null | cut -d. -f1 || stat -f "%Sm" "$FILE" 2>/dev/null)
  echo "Last modified: $MODIFIED"
  echo ""
}

# Export function for subshell
export -f show_skill_details

# Show user-level skills
if [ -d "$HOME/.codex/skills/omc-learned" ]; then
  echo "USER-LEVEL SKILLS:"
  find "$HOME/.codex/skills/omc-learned" -name "*.md" -type f -exec bash -c 'show_skill_details "$0" "user-level"' {} \;
fi

# Show project-level skills
if [ -d ".omc/skills" ]; then
  echo "PROJECT-LEVEL SKILLS:"
  find ".omc/skills" -name "*.md" -type f -exec bash -c 'show_skill_details "$0" "project-level"' {} \;
fi

Option 3: Scan Conversation for Patterns

Analyze the current conversation context to identify potential skill-worthy patterns. Look for:

• Recent debugging sessions with non-obvious solutions
• Tricky bugs that required investigation
• Codebase-specific workarounds discovered
• Error patterns that took time to resolve

Report findings and ask if user wants to extract any as skills.

Option 4: Import Skill

Ask user to provide either:

• URL: Download skill from a URL (e.g., GitHub gist)
• Paste content: Paste skill markdown content directly

Then ask for scope:

• User-level (~/.codex/skills/omc-learned/) - Available across all projects
• Project-level (.omc/skills/) - Only for this project

Validate the skill format and save to the chosen location.

Step 4: Skill Templates

Provide quick templates for common skill types. When user wants to create a skill, offer these starting points:

Error Solution Template

---
id: error-[unique-id]
name: [Error Name]
description: Solution for [specific error in specific context]
source: conversation
triggers: ["error message fragment", "file path", "symptom"]
quality: high
---

# [Error Name]

## The Insight
What is the underlying cause of this error? What principle did you discover?

## Why This Matters
What goes wrong if you don't know this? What symptom led here?

## Recognition Pattern
How do you know when this applies? What are the signs?
- Error message: "[exact error]"
- File: [specific file path]
- Context: [when does this occur]

## The Approach
Step-by-step solution:
1. [Specific action with file/line reference]
2. [Specific action with file/line reference]
3. [Verification step]

## Example
\`\`\`typescript
// Before (broken)
[problematic code]

// After (fixed)
[corrected code]
\`\`\`

Workflow Skill Template

---
id: workflow-[unique-id]
name: [Workflow Name]
description: Process for [specific task in this codebase]
source: conversation
triggers: ["task description", "file pattern", "goal keyword"]
quality: high
---

# [Workflow Name]

## The Insight
What makes this workflow different from the obvious approach?

## Why This Matters
What fails if you don't follow this process?

## Recognition Pattern
When should you use this workflow?
- Task type: [specific task]
- Files involved: [specific patterns]
- Indicators: [how to recognize]

## The Approach
1. [Step with specific commands/files]
2. [Step with specific commands/files]
3. [Verification]

## Gotchas
- [Common mistake and how to avoid it]
- [Edge case and how to handle it]

Code Pattern Template

---
id: pattern-[unique-id]
name: [Pattern Name]
description: Pattern for [specific use case in this codebase]
source: conversation
triggers: ["code pattern", "file type", "problem domain"]
quality: high
---

# [Pattern Name]

## The Insight
What's the key principle behind this pattern?

## Why This Matters
What problems does this pattern solve in THIS codebase?

## Recognition Pattern
When do you apply this pattern?
- File types: [specific files]
- Problem: [specific problem]
- Context: [codebase-specific context]

## The Approach
Decision-making heuristic, not just code:
1. [Principle-based step]
2. [Principle-based step]

## Example
\`\`\`typescript
[Illustrative example showing the principle]
\`\`\`

## Anti-Pattern
What NOT to do and why:
\`\`\`typescript
[Common mistake to avoid]
\`\`\`

Integration Skill Template

---
id: integration-[unique-id]
name: [Integration Name]
description: How [system A] integrates with [system B] in this codebase
source: conversation
triggers: ["system name", "integration point", "config file"]
quality: high
---

# [Integration Name]

## The Insight
What's non-obvious about how these systems connect?

## Why This Matters
What breaks if you don't understand this integration?

## Recognition Pattern
When are you working with this integration?
- Files: [specific integration files]
- Config: [specific config locations]
- Symptoms: [what indicates integration issues]

## The Approach
How to work with this integration correctly:
1. [Configuration step with file paths]
2. [Setup step with specific details]
3. [Verification step]

## Gotchas
- [Integration-specific pitfall #1]
- [Integration-specific pitfall #2]

Usage Modes

Direct Command Mode

When invoked with an argument, skip the interactive wizard:

• $local-skills-setup list - Show detailed skill inventory
• $local-skills-setup add - Start skill creation (invoke learner)
• $local-skills-setup scan - Scan both skill directories

Interactive Mode

When invoked without arguments, run the full guided wizard (Steps 1-4).

Skill Quality Guidelines

Remind users that good skills are:

1. Non-Googleable - Can't easily find via search

   • BAD: "How to read files in TypeScript" ❌
   • GOOD: "This codebase uses custom path resolution requiring fileURLToPath" ✓

2. Context-Specific - References actual files/errors from THIS codebase

   • BAD: "Use try/catch for error handling" ❌
   • GOOD: "The aiohttp proxy in server.py:42 crashes on ClientDisconnectedError" ✓

3. Actionable with Precision - Tells exactly WHAT to do and WHERE

   • BAD: "Handle edge cases" ❌
   • GOOD: "When seeing 'Cannot find module' in dist/, check tsconfig.json moduleResolution" ✓

4. Hard-Won - Required significant debugging effort

   • BAD: Generic programming patterns ❌
   • GOOD: "Race condition in worker.ts - Promise.all at line 89 needs await" ✓

Benefits of Local Skills

When introducing the skill system, explain these benefits:

Automatic Application: Codex detects triggers and applies skills automatically - no need to remember or search for solutions.

Version Control: Project-level skills (.omc/skills/) are committed with your code, so the whole team benefits.

Evolving Knowledge: Skills improve over time as you discover better approaches and refine triggers.

Reduced Token Usage: Instead of re-solving the same problems, Codex applies known patterns efficiently.

Codebase Memory: Preserves institutional knowledge that would otherwise be lost in conversation history.

Related Skills

• $learner - Extract a skill from current conversation
• $note - Save quick notes (less formal than skills)
• $deepinit - Generate AGENTS.md codebase hierarchy

Example Session

Show users what a typical session looks like:

> $local-skills-setup

Checking skill directories...
✓ User skills directory exists: ~/.codex/skills/omc-learned/
✓ Project skills directory exists: .omc/skills/

Scanning for skills...

=== USER-LEVEL SKILLS ===
Total skills: 3
  - async-network-error-handling
    Description: Pattern for handling independent I/O failures in async network code
    Modified: 2026-01-20 14:32:15

  - esm-path-resolution
    Description: Custom path resolution in ESM requiring fileURLToPath
    Modified: 2026-01-19 09:15:42

=== PROJECT-LEVEL SKILLS ===
Total skills: 5
  - session-timeout-fix
    Description: Fix for sessionId undefined after restart in session.ts
    Modified: 2026-01-22 16:45:23

  - build-cache-invalidation
    Description: When to clear TypeScript build cache to fix phantom errors
    Modified: 2026-01-21 11:28:37

=== SUMMARY ===
Total skills: 8

What would you like to do?
1. Add new skill
2. List all skills with details
3. Scan conversation for patterns
4. Import skill
5. Done

Tips for Users

• Run $local-skills-setup scan periodically to review your skill library
• After solving a tricky bug, immediately run learner to capture it
• Use project-level skills for codebase-specific knowledge
• Use user-level skills for general patterns that apply everywhere
• Review and refine triggers over time to improve matching accuracy