claudecode-omc 4.3.6 → 4.4.0

package/README.md

@@ -2,285 +2,166 @@ English | [한국어](README.ko.md) | [中文](README.zh.md) | [日本語](READM
 
 # oh-my-claudecode
 
-[![npm version](https://img.shields.io/npm/v/oh-my-claude-sisyphus?color=cb3837)](https://www.npmjs.com/package/oh-my-claude-sisyphus)
-[![npm downloads](https://img.shields.io/npm/dm/oh-my-claude-sisyphus?color=blue)](https://www.npmjs.com/package/oh-my-claude-sisyphus)
+[![npm version](https://img.shields.io/npm/v/claudecode-omc?color=cb3837)](https://www.npmjs.com/package/claudecode-omc)
+[![npm downloads](https://img.shields.io/npm/dm/claudecode-omc?color=blue)](https://www.npmjs.com/package/claudecode-omc)
 [![GitHub stars](https://img.shields.io/github/stars/Yeachan-Heo/oh-my-claudecode?style=flat&color=yellow)](https://github.com/Yeachan-Heo/oh-my-claudecode/stargazers)
 [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
-[![Sponsor](https://img.shields.io/badge/Sponsor-❤️-red?style=flat&logo=github)](https://github.com/sponsors/Yeachan-Heo)
+[![Sponsor](https://img.shields.io/badge/Sponsor-%E2%9D%A4%EF%B8%8F-red?style=flat&logo=github)](https://github.com/sponsors/Yeachan-Heo)
 
-> **For Codex users:** Check out [oh-my-codex](https://github.com/Yeachan-Heo/oh-my-codex) — the same orchestration experience for OpenAI Codex CLI.
+> **For Codex users:** [oh-my-codex](https://github.com/Yeachan-Heo/oh-my-codex) provides a similar orchestration experience for OpenAI Codex CLI.
 
-**Multi-agent orchestration for Claude Code. Zero learning curve.**
+Multi-agent orchestration for Claude Code with zero-friction setup.
 
-*Don't learn Claude Code. Just use OMC.*
+[Quick Start](#quick-start) • [Reference](docs/REFERENCE.md) • [Architecture](docs/ARCHITECTURE.md) • [Migration](docs/MIGRATION.md)
 
-[Get Started](#quick-start) • [Documentation](https://yeachan-heo.github.io/oh-my-claudecode-website) • [Migration Guide](docs/MIGRATION.md)
+---
+
+## What Changed
+
+This project is branded as **oh-my-claudecode**, and the npm package is published as **`claudecode-omc`**.
+
+- Legacy plugin-marketplace install flow is no longer the primary path in this README.
+- Use npm package installation and OMC CLI setup commands.
+- Multiple executable entrypoints are provided from the same package.
 
 ---
 
 ## Quick Start
 
-**Step 1: Install**
-```bash
-/plugin marketplace add https://github.com/Yeachan-Heo/oh-my-claudecode
-/plugin install oh-my-claudecode
-```
+### 1. Install
 
-**Step 2: Setup**
 ```bash
-/omc-setup
-```
-
-**Step 3: Build something**
-```
-autopilot: build a REST API for managing tasks
+npm install -g claudecode-omc
 ```
 
-That's it. Everything else is automatic.
-
-## Team Mode (Recommended)
-
-Starting in **v4.1.7**, **Team** is the canonical orchestration surface in OMC. Legacy entrypoints like **swarm** and **ultrapilot** are still supported, but they now **route to Team under the hood**.
+### 2. Bootstrap Claude Code Integration
 
 ```bash
-/team 3:executor "fix all TypeScript errors"
+omc install
+omc setup
 ```
 
-Team runs as a staged pipeline:
+### 3. Start Working
 
-`team-plan → team-prd → team-exec → team-verify → team-fix (loop)`
+```text
+autopilot: build a REST API for managing tasks
+```
 
-Enable Claude Code native teams in `~/.claude/settings.json`:
+---
 
-```json
-{
-  "env": {
-    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
-  }
-}
-```
+## Package and CLI Entrypoints
 
-> If teams are disabled, OMC will warn you and fall back to non-team execution where possible.
+`claudecode-omc` exposes multiple command names:
 
-> **Note: Package naming** — The project is branded as **oh-my-claudecode** (repo, plugin, commands), but the npm package is published as [`oh-my-claude-sisyphus`](https://www.npmjs.com/package/oh-my-claude-sisyphus). If you install the CLI tools via npm/bun, use `npm install -g oh-my-claude-sisyphus`.
+- `omc` (primary)
+- `oh-my-claudecode` (alias)
+- `omc-cli` (alias)
+- `omc-analytics` (analytics-focused entry)
 
-### Updating
+Check installed version:
 
 ```bash
-# 1. Update the marketplace clone
-/plugin marketplace update omc
-
-# 2. Re-run setup to refresh configuration
-/omc-setup
+omc version
 ```
 
-> **Note:** If marketplace auto-update is not enabled, you must manually run `/plugin marketplace update omc` to sync the latest version before running setup.
+---
 
-If you experience issues after updating, clear the old plugin cache:
+## Update
 
 ```bash
-/omc-doctor
+npm install -g claudecode-omc@latest
+omc setup
 ```
 
-<h1 align="center">Your Claude Just Have been Steroided.</h1>
+If needed, run diagnostics:
 
-<p align="center">
-  <img src="assets/omc-character.jpg" alt="oh-my-claudecode" width="400" />
-</p>
-
----
-
-## Why oh-my-claudecode?
-
-- **Zero configuration required** - Works out of the box with intelligent defaults
-- **Team-first orchestration** - Team is the canonical multi-agent surface (swarm/ultrapilot are compatibility facades)
-- **Natural language interface** - No commands to memorize, just describe what you want
-- **Automatic parallelization** - Complex tasks distributed across specialized agents
-- **Persistent execution** - Won't give up until the job is verified complete
-- **Cost optimization** - Smart model routing saves 30-50% on tokens
-- **Learn from experience** - Automatically extracts and reuses problem-solving patterns
-- **Real-time visibility** - HUD statusline shows what's happening under the hood
+```bash
+omc doctor
+```
 
 ---
 
-## Features
-
-### Orchestration Modes
-Multiple strategies for different use cases — from Team-backed orchestration to token-efficient refactoring. [Learn more →](https://yeachan-heo.github.io/oh-my-claudecode-website/docs.html#execution-modes)
-
-| Mode | What it is | Use For |
-|------|------------|---------|
-| **Team (recommended)** | Canonical staged pipeline (`team-plan → team-prd → team-exec → team-verify → team-fix`) | Coordinated agents working on a shared task list |
-| **Autopilot** | Autonomous execution (single lead agent) | End-to-end feature work with minimal ceremony |
-| **Ultrawork** | Maximum parallelism (non-team) | Burst parallel fixes/refactors where Team isn't needed |
-| **Ralph** | Persistent mode with verify/fix loops | Tasks that must complete fully (no silent partials) |
-| **Pipeline** | Sequential, staged processing | Multi-step transformations with strict ordering |
-| **Swarm / Ultrapilot (legacy)** | Compatibility facades that route to **Team** | Existing workflows and older docs |
-
-### Enhanced Code Review (4-Layer Deep Analysis)
-
-Multi-layer AI code review with MBTI-driven personas and confidence scoring:
-
-| Layer | Engine | MBTI Persona | Focus |
-|-------|--------|-------------|-------|
-| **Layer 1** | 5 parallel Claude agents | INTJ/ISTJ/INTP/ENTP/ISFJ | CLAUDE.md compliance, bug detection, git history, related PRs, code comments |
-| **Layer 2** | Gemini CLI (`gemp`) | INTJ Architect | Architecture review, security, performance |
-| **Layer 3** | Codex CLI (`codex exec`) | ISTJ Engineer | Best practices, maintainability, pattern adherence |
-| **Layer 4** | Synthesis | All personas | Combined findings, final confidence scoring, comprehensive report |
+## Team Mode (Recommended)
 
-- **Confidence scoring** (0-100) with false positive filtering (threshold: 80+)
-- **3 modes**: `--quick` (single-pass), standard (5 agents), `--deep` (full 4-layer)
-- **Chinese output** by default
+Team is the canonical orchestration surface.
 
-### Intelligent Orchestration
+```text
+team 3:executor "fix all TypeScript errors"
+```
 
-- **32 specialized agents** for architecture, research, design, testing, data science
-- **Smart model routing** - Haiku for simple tasks, Opus for complex reasoning
-- **Automatic delegation** - Right agent for the job, every time
+Pipeline:
 
-### Developer Experience
+`team-plan -> team-prd -> team-exec -> team-verify -> team-fix (loop)`
 
-- **Magic keywords** - `ralph`, `ulw`, `plan` for explicit control
-- **HUD statusline** - Real-time orchestration metrics in your status bar
-- **Skill learning** - Extract reusable patterns from your sessions
-- **Analytics & cost tracking** - Understand token usage across all sessions
+To enable Claude Code native teams, add this to `~/.claude/settings.json`:
 
-[Full feature list →](docs/REFERENCE.md)
+```json
+{
+  "env": {
+    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
+  }
+}
+```
 
 ---
 
-## Magic Keywords
-
-Optional shortcuts for power users. Natural language works fine without them.
-
-| Keyword | Effect | Example |
-|---------|--------|---------|
-| `team` | Canonical Team orchestration | `/team 3:executor "fix all TypeScript errors"` |
-| `autopilot` | Full autonomous execution | `autopilot: build a todo app` |
-| `ralph` | Persistence mode | `ralph: refactor auth` |
-| `ulw` | Maximum parallelism | `ulw fix all errors` |
-| `plan` | Planning interview | `plan the API` |
-| `ralplan` | Iterative planning consensus | `ralplan this feature` |
-| `swarm` | Legacy keyword (routes to Team) | `swarm 5 agents: fix lint errors` |
-| `ultrapilot` | Legacy keyword (routes to Team) | `ultrapilot: build a fullstack app` |
-
-**Notes:**
-- **ralph includes ultrawork**: when you activate ralph mode, it automatically includes ultrawork's parallel execution.
-- `swarm N agents` syntax is still recognized for agent count extraction, but the runtime is Team-backed in v4.1.7+.
-
-## Utilities
-
-### Rate Limit Wait
+## Core Features
 
-Auto-resume Claude Code sessions when rate limits reset.
+- Team-first orchestration
+- Autopilot, Ralph, Ultrawork, Pipeline execution modes
+- Specialized agent delegation with tiered model routing
+- Hook-driven automation and verification loops
+- Built-in analytics and cost tracking
 
-```bash
-omc wait          # Check status, get guidance
-omc wait --start  # Enable auto-resume daemon
-omc wait --stop   # Disable daemon
-```
-
-**Requires:** tmux (for session detection)
+See full details in [docs/REFERENCE.md](docs/REFERENCE.md).
 
-### Notification Tags (Telegram/Discord/Slack)
+---
 
-You can configure who gets tagged when stop callbacks send session summaries.
+## Useful Commands
 
 ```bash
-# Set/replace tag list
-omc config-stop-callback telegram --enable --token <bot_token> --chat <chat_id> --tag-list "@alice,bob"
-omc config-stop-callback discord --enable --webhook <url> --tag-list "@here,123456789012345678,role:987654321098765432"
-omc config-stop-callback slack --enable --webhook <url> --tag-list "<!here>,<@U1234567890>"
-
-# Incremental updates
-omc config-stop-callback telegram --add-tag charlie
-omc config-stop-callback discord --remove-tag @here
-omc config-stop-callback discord --clear-tags
+omc --help
+omc install
+omc setup
+omc update
+omc wait
+omc config-stop-callback --help
+omc hud
 ```
 
-Tag behavior:
-- Telegram: `alice` becomes `@alice`
-- Discord: supports `@here`, `@everyone`, numeric user IDs, and `role:<id>`
-- Slack: supports `<@MEMBER_ID>`, `<!channel>`, `<!here>`, `<!everyone>`, `<!subteam^GROUP_ID>`
-- `file` callbacks ignore tag options
-
----
-
-## Documentation
-
-- **[Full Reference](docs/REFERENCE.md)** - Complete feature documentation
-- **[Performance Monitoring](docs/PERFORMANCE-MONITORING.md)** - Agent tracking, debugging, and optimization
-- **[Website](https://yeachan-heo.github.io/oh-my-claudecode-website)** - Interactive guides and examples
-- **[Migration Guide](docs/MIGRATION.md)** - Upgrade from v2.x
-- **[Architecture](docs/ARCHITECTURE.md)** - How it works under the hood
-
 ---
 
 ## Requirements
 
+- Node.js 20+
 - [Claude Code](https://docs.anthropic.com/claude-code) CLI
-- Claude Max/Pro subscription OR Anthropic API key
+- Claude Max/Pro subscription or Anthropic API key
 
-### Optional: Multi-AI Orchestration
+Optional multi-AI orchestration:
 
-OMC can optionally orchestrate external AI providers via **CLI invocation** (not MCP) for cross-validation and deep analysis. These are **not required** — OMC works fully without them.
+- [Gemini CLI](https://github.com/google-gemini/gemini-cli)
+- [Codex CLI](https://github.com/openai/codex)
 
-| Provider | Install | CLI Usage | What it enables |
-|----------|---------|-----------|-----------------|
-| [Gemini CLI](https://github.com/google-gemini/gemini-cli) | `npm install -g @google/gemini-cli` | `gemp` / `gemini --yolo` | Architecture review, design consistency (1M token context) |
-| [Codex CLI](https://github.com/openai/codex) | `npm install -g @openai/codex` | `codex exec` | Quality audit, code review cross-check |
+---
 
-**Invocation method:** Prompt piped via stdin to CLI tools — no MCP server dependency, no timeout limits.
+## Documentation
 
-```bash
-# Gemini (preferred: gemp with long task support)
-cat /tmp/prompt.txt | node ~/.gemini/long_task_runner.js 2>&1
+- [Reference](docs/REFERENCE.md)
+- [Architecture](docs/ARCHITECTURE.md)
+- [Performance Monitoring](docs/PERFORMANCE-MONITORING.md)
+- [Migration Guide](docs/MIGRATION.md)
+- [Local Plugin Installation (for local plugin development)](docs/LOCAL_PLUGIN_INSTALL.md)
+- [Changelog](CHANGELOG.md)
 
-# Gemini (fallback)
-cat /tmp/prompt.txt | gemini --yolo 2>&1
+---
 
-# Codex
-cat /tmp/prompt.txt | codex exec --dangerously-bypass-approvals-and-sandbox - 2>&1
-```
+## Support
 
-**Cost:** 3 Pro plans (Claude + Gemini + ChatGPT) cover everything for ~$60/month.
+- [GitHub Issues](https://github.com/Yeachan-Heo/oh-my-claudecode/issues)
+- [GitHub Sponsors](https://github.com/sponsors/Yeachan-Heo)
 
 ---
 
 ## License
 
 MIT
-
----
-
-<div align="center">
-
-**Inspired by:** [oh-my-opencode](https://github.com/code-yeongyu/oh-my-opencode) • [claude-hud](https://github.com/ryanjoachim/claude-hud) • [Superpowers](https://github.com/NexTechFusion/Superpowers) • [everything-claude-code](https://github.com/affaan-m/everything-claude-code)
-
-**Zero learning curve. Maximum power.**
-
-</div>
-
-## Star History
-
-[![Star History Chart](https://api.star-history.com/svg?repos=Yeachan-Heo/oh-my-claudecode&type=date&legend=top-left)](https://www.star-history.com/#Yeachan-Heo/oh-my-claudecode&type=date&legend=top-left)
-
-## 💖 Support This Project
-
-If Oh-My-ClaudeCode helps your workflow, consider sponsoring:
-
-[![Sponsor on GitHub](https://img.shields.io/badge/Sponsor-❤️-red?style=for-the-badge&logo=github)](https://github.com/sponsors/Yeachan-Heo)
-
-### Why sponsor?
-
-- Keep development active
-- Priority support for sponsors
-- Influence roadmap & features
-- Help maintain free & open source
-
-### Other ways to help
-
-- ⭐ Star the repo
-- 🐛 Report bugs
-- 💡 Suggest features
-- 📝 Contribute code

package/docs/CLAUDE.md

@@ -158,19 +158,41 @@ Code Intelligence:
 
 ---
 
+<passive-behaviors>
+These behaviors apply unconditionally — no skill invocation required:
+- ALWAYS delegate source code edits (.ts/.py/.go/.js/.tsx etc.) to `executor`; never write them directly
+- ALWAYS run `verifier` before claiming a task complete
+- "build me" / "I want a [project]" / "create a [app]" → start autopilot workflow immediately
+- "don't stop" / "must complete" → ralph mode, loop until verified complete
+- broad request (vague verb, no target file/function, touches 3+ areas) → explore first, then plan skill
+- project has AGENTS.md files → read them as authoritative passive context before any codebase work
+</passive-behaviors>
+
 <skills>
-Skills are user-invocable commands (`/oh-my-claudecode:<name>`). When you detect trigger patterns, invoke the corresponding skill.
+Trigger words below fire deterministically — no deliberation about whether to invoke. The summaries below are sufficient for direct execution; invoke the Skill tool for full protocol detail when needed.
+
+**Core Workflow Skills (inline summaries):**
+
+`autopilot` ("autopilot", "build me", "I want a"):
+  Expansion: analyst+architect expand idea into spec → Planning: planner+critic create plan → Execution: ultrawork implements → QA: ultraqa cycles → Validation: verifier+security-reviewer validate. Invoke skill for full 6-phase protocol.
+
+`ralph` ("ralph", "don't stop", "must complete"):
+  Persistent loop: execute task → verifier checks completeness → if incomplete, identify gaps, fix, retry. Never stops until verifier confirms complete. Includes ultrawork for parallelism. Invoke skill for loop configuration.
+
+`team` ("team", "coordinated team", "team ralph"):
+  Pipeline: team-plan (explore+planner) → team-prd (analyst) → team-exec (executor+specialists) → team-verify (verifier+reviewers) → team-fix (loop). TeamCreate → TaskCreate×N → spawn agents → claim tasks → shutdown → TeamDelete. Invoke skill for full stage protocol.
+
+`plan` ("plan this", "plan the"):
+  EnterPlanMode → explore codebase with Glob/Grep/Read → design approach → AskUserQuestion if ambiguous → ExitPlanMode for approval. `--consensus`: Planner+Architect+Critic iterate until agreement. Invoke skill for full protocol.
+
+`ultrawork` ("ulw", "ultrawork"):
+  Maximum parallelism: decompose into independent subtasks, spawn 3-10 executor agents simultaneously with run_in_background. Invoke skill for task decomposition protocol.
 
-Workflow Skills:
-- `autopilot` ("autopilot", "build me", "I want a"): full autonomous execution from idea to working code
-- `ralph` ("ralph", "don't stop", "must complete"): self-referential loop with verifier verification; includes ultrawork
-- `ultrawork` ("ulw", "ultrawork"): maximum parallelism with parallel agent orchestration
+**Other Workflow Skills:**
 - `swarm` ("swarm"): **deprecated compatibility alias** over Team; use `/team` (still routes to Team staged pipeline for now)
 - `ultrapilot` ("ultrapilot", "parallel build"): compatibility facade over Team; maps onto Team's staged runtime
-- `team` ("team", "coordinated team", "team ralph"): N coordinated agents using Claude Code native teams with stage-aware agent routing; supports `team ralph` for persistent team execution
 - `pipeline` ("pipeline", "chain agents"): sequential agent chaining with data passing
 - `ultraqa` (activated by autopilot): QA cycling -- test, verify, fix, repeat
-- `plan` ("plan this", "plan the"): strategic planning; supports `--consensus` and `--review` modes
 - `ralplan` ("ralplan", "consensus plan"): alias for `/plan --consensus` -- iterative planning with Planner, Architect, Critic until consensus
 - `sciomc` ("sciomc"): parallel scientist agents for comprehensive analysis
 - `external-context`: invoke parallel document-specialist agents for web searches

package/docs/plans/2026-02-26-skill-optimization-design.md

@@ -0,0 +1,158 @@
+# Skill Ecosystem Optimization Design
+
+**Date:** 2026-02-26
+**Scope:** oh-my-claudecode — full skill quality overhaul (description + structure + quality pipeline)
+**Inspiration:** oh-my-codex skill-development, skill-debugger, skill-quality-analyzer, skill-create patterns
+
+---
+
+## Problem Statement
+
+The oh-my-claudecode skill ecosystem has three interconnected issues:
+
+1. **Weak trigger descriptions** — YAML `description` fields are one-liner jargon (e.g., "Full autonomous execution from idea to working code") with no specific trigger phrases. When Claude reads the system-reminder skill list, these descriptions don't tell it _when_ to invoke the skill.
+
+2. **Progressive disclosure violations** — The `skill` management skill is 838 lines; all content is loaded into context every time. The oh-my-codex standard requires ≤200 lines in SKILL.md, with detailed content in `references/`.
+
+3. **Codex-branded ported skills** — `skill-quality-analyzer` and `skill-tester` still reference "Codex CLI" and "Codex skill quality", which is confusing and slightly broken in the Claude Code context.
+
+4. **No writing standard for new skills** — No equivalent of oh-my-codex's `skill-development` guide exists for OMC. New skills get written ad hoc with inconsistent quality.
+
+---
+
+## Architecture
+
+### Trigger System in Claude Code (vs Codex)
+
+Unlike oh-my-codex where descriptions drive auto-triggering, OMC's skills work in two modes:
+
+- **Core workflow skills** (autopilot, ralph, plan, ultrawork, team…): Triggered by `CLAUDE.md` `<skills>` block keyword matching — descriptions are supplementary
+- **User-created skills** (`~/.claude/skills/`, `.omc/skills/`): Triggered by description semantic matching — descriptions are critical
+
+**System-reminder display format:**
+```
+- skill-name: [description content shown verbatim to Claude]
+```
+
+Therefore, descriptions should read like a natural "use when" statement, not a capability tagline.
+
+---
+
+## Three-Layer Optimization
+
+### Layer 1: Description Standardization (~30 files, frontmatter edits only)
+
+**Standard format:**
+```yaml
+description: "Use when user wants [specific scenario] ('[trigger phrase 1]', '[trigger phrase 2]'). [One-sentence capability summary]."
+```
+
+**Transformation examples:**
+
+| Skill | Before | After |
+|-------|--------|-------|
+| `autopilot` | "Full autonomous execution from idea to working code" | "Use when user wants full-auto development ('build me', 'autopilot', 'I want a'). Handles spec→plan→code→QA→validation end-to-end." |
+| `plan` | "Strategic planning with optional interview workflow" | "Use when user wants to plan before coding ('plan this', 'plan the', 'let's plan'). Supports interview, direct, consensus, and review modes." |
+| `ralph` | "Self-referential loop until task completion with architect verification" | "Use when task must complete guaranteed ('ralph', 'don't stop', 'must complete'). Persistence loop with architect verification." |
+| `ultrawork` | "Parallel execution engine for high-throughput task completion" | "Use when multiple independent tasks need parallel execution ('ulw', 'ultrawork', 'run in parallel'). Routes tasks to tiered agents simultaneously." |
+| `skill-quality-analyzer` | "Analyzes Codex skill quality with 6-dimension scoring…" | "Use when checking a Claude Code skill's quality ('analyze skill', 'score skill', 'skill quality'). 6-dimension scoring: clarity, structure, examples, triggers, practices, maintainability." |
+| `skill-tester` | "Tests Codex skill functionality with TDD approach…" | "Use when verifying a Claude Code skill works correctly ('test skill', 'verify skill behavior'). TDD workflow with trigger tests and functional validation." |
+
+**All skills to update:** autopilot, build-fix, deepinit, learner, note, skill, trace, ultraqa, conductor, skill-tester, skill-quality-analyzer, skill-debugger, analyze, cancel, ccg, code-review, configure-notifications, external-context, hud, learn-about-omc, mcp-setup, omc-doctor, omc-help, omc-setup, pipeline, plan, ralph, ralph-init, ralplan, release, review, sciomc, security-review, tdd, team, ultrapilot, ultrawork, ai-commenting, writing-skills (new)
+
+### Layer 2: Progressive Disclosure for `skill` Management Skill
+
+**Current:** `skills/skill/SKILL.md` — 838 lines, all loaded at invocation
+
+**Target structure:**
+```
+skills/skill/
+├── SKILL.md            (~150 lines — commands overview + core workflow)
+├── references/
+│   ├── templates.md    (4 skill templates: Error/Workflow/Pattern/Integration)
+│   └── setup-guide.md  (setup wizard detail + bash scan scripts)
+```
+
+**What stays in SKILL.md:**
+- Subcommand overview table (list/add/remove/search/edit/sync/setup/scan)
+- Core behavior for each command (condensed, pointer to references/ for detail)
+- Error handling format
+- Skill quality guidelines (condensed to 4 bullets)
+
+**What moves to references/:**
+- All 4 full skill templates (Error Solution, Workflow, Code Pattern, Integration) → `references/templates.md`
+- Full bash scripts for directory scanning → `references/setup-guide.md`
+- Complete example session → `references/setup-guide.md`
+
+### Layer 3: `writing-skills` Skill (New)
+
+**OMC's equivalent of oh-my-codex's `skill-development`.**
+
+```
+skills/writing-skills/
+├── SKILL.md                          (~120 lines)
+└── references/
+    ├── format-guide.md               (XML tag structure, size targets, style rules)
+    └── description-patterns.md       (Good/Bad description catalog)
+```
+
+**SKILL.md content:**
+- When to use (trigger: "write a skill", "create a skill", "new skill")
+- OMC Hybrid Workflow: Hard Steps (file creation, frontmatter) + Soft Steps (description quality judgment)
+- 6-step process: Understand → Plan → Create structure → Write SKILL.md → Quality-analyze → Test
+- Integration: triggers skill-quality-analyzer, skill-debugger, skill-tester
+- Validation checklist
+- References to `references/format-guide.md` and `references/description-patterns.md`
+
+**`references/format-guide.md` content:**
+- XML tag structure: `<Purpose>`, `<Use_When>`, `<Do_Not_Use_When>`, `<Why_This_Exists>`, `<Execution_Policy>`, `<Steps>`, `<Tool_Usage>`, `<Examples>`, `<Escalation_And_Stop_Conditions>`, `<Final_Checklist>`, `<Advanced>`
+- When to use XML vs markdown headers (workflow skills → XML; utility skills → markdown)
+- Size targets: SKILL.md ≤200 lines, references/ files ≤300 lines each
+- Description standard with trigger phrase format
+
+**`references/description-patterns.md` content:**
+- Side-by-side catalog of all 30+ skill descriptions (before/after with rationale)
+- Pattern library: workflow triggers, delegation triggers, utility triggers
+- Anti-patterns with explanations
+
+### Bonus: Adapt Ported Skills
+
+**`skill-quality-analyzer/SKILL.md`:**
+- Replace all "Codex" references with "Claude Code"
+- Update Agent Workflow section: replace `python3 analyzer.py` with Glob/Read/Grep tool sequence as primary hard-metrics step (keep analyzer.py as optional enhancement)
+- Update skill location paths: `~/.codex/skills/` → `~/.claude/skills/` and `.agents/skills/` → `.claude/skills/`
+
+**`skill-tester/SKILL.md`:**
+- Replace all "Codex" references with "Claude Code"
+- Remove JSON-based test case format (more Codex-native) — replace with scenario-based format
+- Simplify: this skill is mainly used for "does the skill trigger?" and "does it produce the right output?" — remove performance testing and coverage metrics (overkill for prompt-based skills)
+
+---
+
+## What We Are NOT Doing
+
+- No changes to body content of autopilot/ralph/plan/ultrawork/team — XML structure is well-designed
+- No rewrite of `analyzer.py` Python script — functional, keep as optional tool
+- No `version` field added to frontmatter — no versioning system in OMC
+- No changes to `project-session-manager/` shell scripts — not a skill content issue
+- No changes to `CLAUDE.md` skill trigger keywords — those work correctly
+
+---
+
+## Acceptance Criteria
+
+1. All skill descriptions follow "Use when user [scenario] ('[trigger]'). [Summary]." format
+2. `skill/SKILL.md` is ≤200 lines; templates and scripts moved to `references/`
+3. `writing-skills/` skill exists with SKILL.md + 2 references files
+4. `skill-quality-analyzer/SKILL.md` and `skill-tester/SKILL.md` contain no "Codex" references
+5. Running `skill-quality-analyzer` on `writing-skills` returns score ≥80
+6. No existing skill functionality is removed — only descriptions and structure change
+
+---
+
+## Implementation Order
+
+1. Create `writing-skills/` skill (establishes the standard we'll apply)
+2. Update all descriptions (Layer 1) — mechanical, high volume
+3. Refactor `skill/` (Layer 2) — structural surgery on largest skill
+4. Update `skill-quality-analyzer` and `skill-tester` (ported skill adaptation)