engineering-conventions · zaxbyhub — Codex skill: purpose and setup
The engineering-conventions skill sets a workflow for changes that could affect opencode-swarm’s engineering invariants. Use it when editing architecture, tests, or session state.
MIT ★ 539 updated 2026-10-29
npx skills add ZaxbyHub/opencode-swarm --skill engineering-conventions -a claude-codeWhat engineering-conventions does
Before changing code that touches repository invariants, read AGENTS.md, then docs/engineering-invariants.md, followed by .opencode/skills/engineering-conventions/SKILL.md. Edits to agent prompt strings or escaped templates call for an extra look at the escaping guidance in the skill instructions.
For Codex, the skill recommends apply_patch for manual edits and shell execution for searches, builds, smoke checks, and tests. Independent file reads and searches can run in parallel. Each invariant affected by a change needs concrete evidence that the change respects it.
AGENTS.md takes precedence over an imported skill if their instructions conflict. That makes the repository’s own guidance the final authority.
What it helps with
- Check repository rules before changing architecture
- Follow the required order for reading engineering guidance
- Show evidence that a change respects affected invariants
- Avoid escaping mistakes in agent prompt strings
Example prompts for the agent
- Before changing plugin initialization, check the repository's engineering rules.
- Review the expected workflow for tests and
test_runnerbefore editing them. - Tell me what to read before I change agent prompt strings.
How to install engineering-conventions
1Skills CLI (Vercel)
npx skills add ZaxbyHub/opencode-swarm --skill engineering-conventions -a claude-code2Manually: put the files in place
~/.claude/skills/engineering-conventions/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/engineering-conventions/
1Skills CLI (Vercel)
npx skills add ZaxbyHub/opencode-swarm --skill engineering-conventions -a codex2Manually: put the files in place
.agents/skills/engineering-conventions/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add ZaxbyHub/opencode-swarm --skill engineering-conventions -a cursor2Manually: put the files in place
.cursor/skills/engineering-conventions/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install ZaxbyHub/opencode-swarm .agents/skills/engineering-conventions2Manually: put the files in place
.github/skills/engineering-conventions/SKILL.md1Skills CLI (Vercel)
npx skills add ZaxbyHub/opencode-swarm --skill engineering-conventions -a gemini-cli2Platform CLI
gemini skills install https://github.com/ZaxbyHub/opencode-swarm --path .agents/skills/engineering-conventionsManually: put the files in place
.devin/skills/engineering-conventions/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add ZaxbyHub/opencode-swarm --skill engineering-conventions -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about engineering-conventions
How do I install engineering-conventions in Codex?
Run npx skills add ZaxbyHub/opencode-swarm --skill engineering-conventions -a codex. The skill is installed at .agents/skills/engineering-conventions/SKILL.md.
What does engineering-conventions do?
It sets a reading order for repository guidance and gives Codex instructions for changes that may affect engineering invariants. Changes should include concrete evidence that those invariants were respected.
Which files should I read before making a change?
Read AGENTS.md first, then docs/engineering-invariants.md, followed by .opencode/skills/engineering-conventions/SKILL.md. If guidance conflicts, AGENTS.md takes precedence.
Source text
SKILL.md · MIT
--- name: engineering-conventions description: Codex adapter for opencode-swarm engineering invariants. Use before modifying plugin initialization, subprocesses, runtime portability, .swarm containment, plan durability, test_runner behavior, test-writing patterns, session/global state, guardrails/retry semantics, chat/system hooks, tool registration, release/cache hygiene, or related architecture. metadata: audience: swarm-plugin --- # Engineering Conventions Use this adapter before any change that can touch a repository invariant. Read, in order: 1. `AGENTS.md` 2. `docs/engineering-invariants.md` 3. `.opencode/skills/engineering-conventions/SKILL.md` If editing agent prompt strings or escaped template text, pay attention to the "Agent prompt strings — escaping pitfalls" section, which is now carried in both the `.opencode` summary (item 3 above) and `.claude/skills/engineering-conventions/SKILL.md`. Codex-specific execution notes: - Use `apply_patch` for manual edits. - Use the available shell execution tool for `rg`, `git`, build, smoke, and test commands. - Use the runtime's parallel-execution capability for independent file reads and searches. - Keep changes scoped and produce concrete invariant evidence for every touched invariant. The source of truth is always `AGENTS.md`. If an imported skill conflicts with it, `AGENTS.md` wins.
© ZaxbyHub · MIT · ZaxbyHub/opencode-swarm
Similar skills
All skills for Agent setup: memory, context, orchestration →engineering-conventions by other authors comes first.