| name | omg-sync-back |
| description | Push .agents/ skill/agent/rule edits back to their origin kit repos as PRs. Use after fixing a skill locally, updating a gotcha, or improving agent definitions. |
Codex Port Notice
This skill was ported from upstream reference material. Interpret command names, paths, and agent-routing guidance as Codex/Oh My Game Kit equivalents. Prefer active Codex tools and local project instructions over Codex-specific mechanics when they conflict.
Oh My Game Kit Sync-Back — Push Changes to Kit Repos
Push .agents/ changes (skills, agents, rules) back to their origin kit repos as PRs.
Uses GitHub MCP tools — no local clone needed.
Usage
omg-sync-back # Interactive: show diff, ask confirmation, create PR
omg-sync-back --dry-run # Show what would change without creating PR
omg-sync-back --force # Skip confirmation. Diff is ALWAYS shown.
Scope — Consumer Projects Only (MANDATORY)
Do NOT invoke when CWD is a kit source repo (oh-my-game-kit-core, oh-my-game-kit-unity, oh-my-game-kit-cli, oh-my-game-kit-designer, oh-my-game-kit-cocos, oh-my-game-kit-rn, oh-my-game-kit-web, oh-my-game-kit-nakama, oh-my-game-kit-release-action, omg-telemetry-worker). Those repos ARE the origin — commit directly. See references/consumer-guard.md.
Invocation Mode (MANDATORY — Background Sub-Agent)
This skill MUST run as a background sub-agent via the Task tool, NEVER inline.
Exception: explicit user request ("sync this now") → run inline so the diff is visible.
See references/sub-agent-invocation.md for the required Task call template, required fields (kitVersion, moduleVersion, cliVersion, platform, rationale), and the auto-lesson writeback protocol (submitted: true, prUrl, fingerprint).
Decision tree — which reference do I load?
Load only the reference you need (each is self-contained):
| Intent | Load |
|---|
| Check if CWD is a consumer project (first step, always) | references/consumer-guard.md |
| Sub-agent invocation template + auto-lesson writeback contract | references/sub-agent-invocation.md |
| Pre-flight checks (MCP, repo access, staleness detection) | references/preflight-checks.md |
| Resolve file origin + compute target path in kit repo | references/routing-and-paths.md |
| Open the PR (branch → push → create, fork flow, PR body template) | references/open-pr.md |
Writeback submitted: true to the lesson queue | references/queue-writeback.md |
| Error table, cross-platform notes, what gets synced / excluded | references/error-handling.md |
Operational notes
- Scan BOTH user-scope and project-scope. Walk
$HOME/.agents/ AND <cwd>/.agents/ when collecting candidate files. Project-scope modules/skills (e.g., a wiki repo shipping its own module) are invisible if you only scan user-scope. See references/routing-and-paths.md Step 0 for the rules. Originating incident: #168.
- Pre-flight: requires omg CLI v4.17.0+. The
require-current-cli.cjs PreToolUse hook will block stale-CLI invocations of omg sync-back (and other state-mutating commands) when the cached latest version is newer than the local binary. Run omg self-update first if the gate fires; override (NOT recommended) is OMG_REQUIRE_CURRENT_CLI=0.
- Run pre-flight checks BEFORE any file write — verify GitHub MCP is connected.
- Staleness check is MANDATORY. Never push a stale branch silently.
- Module-registry-sync: if the edit touches
module.json, the sub-agent must also regenerate omg-modules.json in the kit repo (gate #validate-modules-registry-sync).
- Skill-rename + activation-fragment sync (2026-05-11) — when a sync-back diff includes a skill directory rename (e.g.,
omg-rn-rn-base-old → omg-rn-rn-base-new), the sub-agent must ALSO update every omg-activation-*.json fragment whose sessionBaseline[] or mappings[].skills[] references the old slug. Bare-slug refs (old) and full-prefixed refs (omg-rn-rn-base-old) both need to swap. The release-action prefixer's buildSelfHealMap() will catch the rename on the next CI run, but shipping the activation update in the same PR keeps the SSOT consistent and avoids the per-PR drift safety-net gate (validate-activation-skill-resolution.cjs) firing on subsequent unrelated PRs against the kit. If unsure which fragments reference the renamed skill, grep: grep -rE '"(old-slug|omg-...-old-slug)"' .agents/.
- PR is created; NOT automerged. End every invocation by reporting the PR URL and noting "review + merge in the kit repo."
- Security: never sync
.env, settings.local.json, memory files, or files with secrets. Sanitize absolute paths before writing.
- Skill-touching syncs MUST consult
omg-skill-creator. If any path in the diff matches .agents/skills/*/SKILL.md or .agents/skills/*/references/*.md, the sub-agent invokes omg-skill-creator to validate Skillmark structure (frontmatter shape, line-count cap from gate 2, description cap from gate 3, decision-tree pattern) BEFORE opening the PR. Validation failures block the PR; warnings surface in the PR body so the maintainer reviewer sees them.
- Naming-prefix gate on creates AND renames. If the diff CREATES or RENAMES a skill directory or agent file, the sub-agent MUST verify the new name conforms to the universal
omg- prefix rule (rules/naming-convention.md): core = omg-{slug}, kit-wide = omg-{kit}-{slug}, module-scoped = omg-{kit}-{module}-{slug}. Frontmatter name: MUST match the directory/file basename. Non-conforming names will fail validate-skill-prefix.cjs / validate-agent-prefix.cjs at PR time — catch them here and reject the sync-back with a clear error message instead of opening a PR that will block on CI. Agent rename gap (2026-05-08): auto-prefix-agents.cjs does NOT rewrite per-module module.json agents/routingOverlay fields, so the sync-back sub-agent must hand-update both manifests when renaming agents.
Contribution Scoring
After successful PR creation, invoke omg-contribution-score with type=sync-back-pr, the resolved ref_url (the PR URL returned by gh pr create), the PR title + description, and the target kit/repo. Fire-and-forget — never block on the result.
See .agents/skills/omg-contribution-score/SKILL.md for the full invocation contract (rubric, endpoint resolution, POST contract). Do NOT inline rubric or POST logic here — the SSOT lives in that skill.
