AGENTS.md

1# shared-skills — Cross-Harness SKILL.md Bundle (Skills)
2 
3**Generated:** 2026-07-17 (7d664b96b)
4 
5## OVERVIEW
6 
7Hand-authored, cross-harness skill bundle shared between the OpenCode and Codex editions. Mostly authored skill data, with skill-owned scripts/assets when required and no transform inside the package. `index.mjs` exports `sharedSkillsRootPath()` returning the absolute path to `skills/`. Package: `@oh-my-opencode/shared-skills` (`files`: `index.mjs`, `index.d.ts`, `skills`).
8 
9## SKILLS (16 under `skills/<name>/`)
10 
11`programming`, `debugging`, `frontend`, `visual-qa`, `ast-grep`, `coding-agent-sessions`, `git-master`, `refactor`, `review-work`, `start-work`, `ulw-plan`, `ulw-research`, `init-deep`, `remove-ai-slops`, `lsp-setup`, `ultimate-browsing`.
12 
13The Codex-only `lcx-report-bug`, `lcx-contribute-bug-fix`, and `lcx-doctor` skills live under `packages/omo-codex/plugin/components/lcx/skills/`; they are no longer authored in this package.
14 
15Per-skill layout: `SKILL.md` (YAML frontmatter `name:` + single-line `description:` with triggers) + optional `references/` (the real content; SKILL.md is a router/index) + optional `scripts/` + optional `agents/openai.yaml` (3 skills carry the Codex agent role declaration).
16 
17## PIPELINE
18 
19```
20skills/ (source)
21  ├─ build:shared-skills-assets (root) → cp -R skills dist/skills          # literal copy, no transform
22  ├─ skills-loader-core → loadSkillsFromDir(sharedSkillsRootPath(), scope:"shared")   # OpenCode runtime
23  └─ omo-codex/plugin/scripts/sync-skills.mjs → plugin/skills/             # the only transformer
24        1. copies 10 omo-codex COMPONENT skills FIRST (comment-checker, lcx-*, lsp, rules,
25           teammode, ulw-loop, ulw-plan, ultrawork from plugin/components/*/skills/*); same-named
26           shared skills are skipped → ulw-plan/ultrawork in Codex come from components, NOT from here
27        2. copies remaining shared skills
28        3. adaptSkillForCodex(): inserts Codex Harness Tool Compatibility sections; overlays
29           start-work/review-work; writes agents/openai.yaml display metadata with the "(OmO) "
30           prefix; filters out tests, caches, and source metadata
31        → ships to ~/.codex/.../skills/
32```
33 
34## FRONTEND THIRD-PARTY REFS — SUBMODULE-ONLY + BUILD-MATERIALIZE (DMCA-safe)
35 
36The `frontend` skill's brand / taste-skill / ui-ux-db / designpowers references are third-party content. Under the DMCA-safe model the repo holds ZERO committed copies; each upstream is a pinned git submodule under `upstreams/<name>` (NOT under `skills/`, so it never lands in the tarball), and the build materializes the referenced files path-mapped into `skills/frontend/references/{design,ui-ux-db,designpowers/vendor}`. File bodies are copied verbatim, except materialized `SKILL.md` frontmatter may normalize an unquoted single-line `description:` scalar into a JSON-quoted YAML string so Codex/OpenCode frontmatter parsing stays deterministic; the description text itself is unchanged.
37 
38```
39upstreams/{open-design,taste-skill,ui-ux-pro-max,designpowers}   # pinned submodules (provenance, build input)
40  └─ packages/shared-skills/scripts/frontend-refs-manifest.mjs   # single source of truth: partition + upstream path map
41       └─ packages/shared-skills/scripts/materialize-frontend-refs.mjs   # path-mapped copy + SKILL.md description quoting → references/{design,ui-ux-db}
42            └─ chokepoint: packages/omo-codex/plugin/scripts/materialize-shared-upstreams.mjs  (submodule init + materialize)
43                 • PREPENDED to the codex plugin build chain BEFORE sync-skills.mjs (every ship path runs it)
44                 • root build:shared-skills-assets + root prepack also run it
45```
46 
47- The materialized files are GITIGNORED (`skills/frontend/.gitignore`) so they are never committed; a `skills/frontend/.npmignore` overrides that `.gitignore` for npm pack so the materialized refs DO ship. The lazycodex marketplace sync is a raw file copy and ships whatever is on disk after the plugin build materialized it.
48- The §5 project-original design docs (`README.md`, `_INDEX.md`, `aside.md`, `design-system-architecture.md`, `react-dev-tooling-skill.md`) and all of `references/perfection/*` stay committed (un-ignored in `.gitignore`).
49- ATTRIBUTION pins each upstream's SHA (`Pinned upstream commit:`); `script/update-frontend-upstreams.mjs` bumps the submodules + rewrites the pins (`--check` verifies pins == submodule HEAD, no network). `provenance-gate.test.ts` fails CI if any third-party path is committed, the materialize set is missing, or a pin drifts. `materialize-frontend-refs.test.ts` covers the allowed `SKILL.md` description quoting normalization.
50- Submodule init is non-fatal ONLY in `script/agent/setup.sh` (offline devs get a working tree minus brand refs); the plugin build chain runs it `--strict` so CI/publish ship a complete package.
51 
52## CONSUMERS
53 
54- `skills-loader-core` (`workspace:*`) — default `skillsRootPath` for builtin/shared skill loading.
55- `omo-opencode/src/cli/install-ast-grep-sg.ts` — finds the ast-grep skill dir for binary install.
56- `omo-codex/plugin` (`file:` dep) — `sync-skills.mjs` is the only transformer.
57 
58## NOTES
59 
60- **No generator builds the skills** — they are authored by hand; the build step is a plain `cp -R`.
61- **Test files, caches, and source metadata are excluded** when Codex copies skills.
62- **`lcx-` prefix = Codex-only** (no OpenCode counterpart). Frontmatter has NO `location:` field (unlike `.agents/skills/`).
63- **Packaging is pinned** by `omo-opencode/src/shared-skills-package.test.ts` (workspace inclusion + `files` entries + every skill parses).
64- **Skill CONTENT is PROSE — do NOT pin its wording with a test.** A skill body is instructions the model reads; asserting what it *says* (`toContain` a sentence, `not.toContain` old wording, word/char counts) guards a diff, not behavior, and blocks every legitimate edit — see `.omo/rules/test-discipline.md` §PROMPT TESTS. Guard only what a MACHINE consumes: packaging (`omo-opencode/src/shared-skills-package.test.ts`, above), personal-token scrubbing (`depersonalization-gate.test.ts` — a security exclusion), the third-party manifest (`frontend-thirdparty-manifest.test.ts`), and `upstreams.test.ts`. A pure-prose skill edit ships on review with NO new test; the prose-pinning contract tests that used to sit here were removed as pretend-coverage.
65- **ulw-plan is dual-maintained by hand** (here AND `omo-codex/plugin/components/ultrawork/skills/ulw-plan/`) — sync-skills does NOT copy the shared version to Codex; keep both in step.
66- Parent: [`packages/AGENTS.md`](../AGENTS.md).
67