# Omx Setup

> Install or refresh the oh-my-workbuddy skill package into user or project scope. Trigger "omx setup", "install skills", "set up oh-my-workbuddy", "refresh skills".

- Skill: `mrzhangguoguo/omx-setup` (Agent Skill)
- Install (CLI): `npx skillmds@latest add mrzhangguoguo/omx-setup`
- Raw SKILL.md: https://api.skillmd.com/api/skills/mrzhangguoguo/omx-setup/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: mrzhangguoguo (https://skillmd.com/u/mrzhangguoguo)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/mrzhangguoguo/omx-setup

---


> Ported from oh-my-codex `omx-setup`. OMX runtime conventions (`$macro` invocation,
> `omx` CLI, `.omx/` state directory) are replaced with WorkBuddy idioms
> (Skill tool, Agent tool, task list, `.workbuddy/memory`).

# oh-my-workbuddy Setup

Use this skill when the user wants to install or refresh the oh-my-workbuddy skill
package for the **current project and/or the user-level skill root**.

## Command

```bash
./omw setup [--force] [--merge-agents] [--dry-run] [--verbose] [--scope <user|project>]
```

If you only want lightweight `AGENTS.md` scaffolding for an existing repo or subtree,
edit/seed `AGENTS.md` directly instead of running full setup.

Supported setup flags:

- `--force`: overwrite/reinstall managed artifacts where applicable.
- `--merge-agents`: if `AGENTS.md` already exists, preserve user-authored content and
  only insert/refresh oh-my-workbuddy-managed sections between explicit
  `<!-- OMW:AGENTS:START -->` / `<!-- OMW:AGENTS:END -->` markers.
- `--dry-run`: print actions without mutating files.
- `--verbose`: print per-file/per-step details.
- `--scope`: choose install scope (`user` or `project`).

## Canonical skill roots

WorkBuddy loads skills from:

- **User scope (recommended):** `~/.workbuddy/skills/`
- **Project scope:** `.workbuddy/skills/` (repo-relative)

Legacy paths from other tools (e.g. `~/.codebuddy/skills`, `~/.agents/skills`) are
not valid WorkBuddy roots; if they exist alongside the canonical root, remove them to
avoid duplicate skill entries (see the `doctor` skill).

## What setup actually does

1. **Resolve scope:**
   - explicit `--scope` value, else
   - a persisted preference (when present), else
   - interactive prompt on TTY (default `user`), else default `user` (safe for CI).
   On a TTY with a persisted choice, summarize it and ask **keep / review-change /
   reset** before proceeding.
2. Create the target skill-root directories if missing.
3. Copy/refresh the bundled skills into the resolved root:
   - user scope → `~/.workbuddy/skills/<name>/`
   - project scope → `.workbuddy/skills/<name>/`
4. Optionally seed `AGENTS.md` / project guidance (only when selected/allowed, or
   with `--merge-agents` to refresh managed sections idempotently).
5. Create the memory directory (`.workbuddy/memory/`) if missing so skills that use
   durable notes have a home.

## Important behavior notes

- Setup prompts for scope when none is provided and stdin/stdout are a TTY. In
  non-interactive (CI) runs it stays deterministic and never blocks.
- If `AGENTS.md` exists and neither `--force` nor `--merge-agents` is used:
  - interactive TTY runs ask whether to overwrite;
  - non-interactive runs preserve the file.
- Use `--merge-agents` to keep existing project guidance while letting setup refresh
  oh-my-workbuddy-managed `AGENTS.md` sections.
- Project orchestration file is `./AGENTS.md` (project root). Do not delete unrelated
  project documentation when refreshing.

## Setup-owned surfaces (for debugging a confusing install)

| Surface | Owner | Notes |
| --- | --- | --- |
| `~/.workbuddy/skills/` / `.workbuddy/skills/` | setup | The canonical user/project skill roots. |
| `AGENTS.md` | setup (overwrite-safe) | Generated defaults or managed refreshes guarded by force/merge checks. |
| `.workbuddy/memory/` | setup / skills | Durable cross-session notes used by `note`/`hud` idioms. |
| scope preference | setup | Persisted choice summarized on rerun (keep/review/reset). |

OMX/Codex surfaces such as `~/.codex/config.toml`, `~/.codex/hooks.json`, and
`.omx/setup-scope.json` do **not** exist in WorkBuddy and are intentionally dropped.

## If this skill is missing or stale

Treat a missing `omx-setup` as an installation/discovery problem, not a missing source
file:

1. Run `./omw setup --verbose` in the intended scope.
2. Run the `doctor` skill and check the reported skill root, scope, and AGENTS.md
   status.
3. If using project scope, confirm `.workbuddy/skills/omx-setup/SKILL.md` exists.
4. If using user scope, confirm `~/.workbuddy/skills/omx-setup/SKILL.md` exists.
5. If duplicate/stale skills appear, check for legacy root overlap (`~/.codebuddy`,
   `~/.agents`) and remove the legacy tree.

## Recommended workflow

1. Install/refresh:
   ```bash
   ./omw setup --force --verbose
   ```
2. Verify the install:
   ```bash
   # run the doctor skill
   ```
   (invoke the `doctor` skill).
3. Reload skills / restart the WorkBuddy session for the new skills to be available.

## Expected verification indicators

After setup, expect:
- Skills present in the resolved root (`~/.workbuddy/skills/` or `.workbuddy/skills/`).
- `AGENTS.md` found in the project root (when seeded/merged).
- `.workbuddy/memory/` present.
- No duplicate entries from leftover legacy skill roots.

## Troubleshooting

- If using local source changes, build first per the package's build instructions, then
  run `./omw setup --force --verbose`.
- If a global `omw` points elsewhere, run the local entrypoint:
  ```bash
  node lib/cli.js setup --force --verbose
  # then verify with the doctor skill
  ```
- If `AGENTS.md` was not overwritten during `--force`, stop any active session holding
  the file and rerun setup.
- If `AGENTS.md` was not merged during `--merge-agents`, stop the active session and
  rerun.