Skip to main content
skill CX Codex

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

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add ZaxbyHub/opencode-swarm --skill engineering-conventions -a claude-code
Open on GitHub

What 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_runner before 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-code

2Manually: put the files in place

~/.claude/skills/engineering-conventions/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/engineering-conventions/

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.

engineering-conventions ZaxbyHub engineering-conventions enforces non-negotiable engineering invariants for opencode-swarm development. It prevents initialization hangs, Bun mock leakage, and Node ESM runtime failures. CX Codex +1 ★ 539repo stars principal-engineering riekelt principal-engineering enforces core engineering discipline for AI agents: mandates pre-change checkpoints, bans silent error suppression, and requires evidence from real code. CX Codex +1 25,700installs ai-first-engineering affaan-m ai-first-engineering sets team process, review gates and architecture rules for codebases where AI agents produce most of the implementation. CX Codex +1 6,300installs nestjs-professional-software-engineering amirtaherkhani nestjs-professional-software-engineering — a skill for Claude Code and Cursor designs, implements, refactors, and tests production-quality NestJS and TypeScript software. Runs during feature development, API creation, and bug fixes. CX Codex +1 556installs engineering-code-review agentara engineering-code-review applies Google engineering practices to review pull requests and local diffs. Focuses on overall code health, tests, and risk without nitpicking style. CX Codex +1 131installs 1-conventions ai-driven-dev The 1-conventions rule sets conventions for TypeScript files under src/ and tests/, covering module structure, file names, and test tiers. Use it when adding code or tests to a project. CX Codex +1 ★ 571repo stars chaos-engineering kindlmann chaos-engineering plans hypothesis-driven fault injection experiments to test system resilience. Useful when preparing game days or verifying fallbacks against network and service outages. CX Codex +1 1,300installs

From the same set121

The whole set →
codebase-review-swarm codebase-review-swarm executes quote-grounded codebase audits across security, QA, and performance. Suitable for full-repository assessments where no source files may be touched. CX Codex +1 ★ 539repo stars add-path-type-assertions-or-realpath-resolve-calls-in-path-joini add-path-type-assertions-or-realpath-resolve-calls-in-path-joini is a Claude Code skill that adds path-type checks or realpath/resolve calls to path-joining utilities. It activates around path.join, realpath, and fs path work. CX Codex +1 ★ 539repo stars run-failing-tests-immediately-after-test-gate-failure run-failing-tests-immediately-after-test-gate-failure is a Claude Code skill that makes the agent rerun failing tests when test_gate fails and repair the root cause before claiming the task is done. CX Codex +1 ★ 539repo stars run-tests-on-the-unmodified-codebase-before-starting-to-establis run-tests-on-the-unmodified-codebase-before-starting-to-establis is a Claude Code skill that requires running tests on untouched code before edits, recording failures to distinguish them from new regressions. CX Codex +1 ★ 539repo stars include-test-files-that-assert-on-behavior-being-changed-in-decl include-test-files-that-assert-on-behavior-being-changed-in-decl is a Claude Code skill that puts tests for changed behaviour in scope, so an agent fixes code alongside its checks. CX Codex +1 ★ 539repo stars run-relevant-tests-after-logic-changes run-relevant-tests-after-logic-changes enforces running target test suites after code changes and forbids reporting completion until all checks pass. CX Codex +1 ★ 539repo stars pr-review-fix The pr-review-fix skill checks PR review findings against the current branch and fixes confirmed issues. Use it to work through reviewer comments, bot feedback, or a CI review summary. CX Codex +1 ★ 539repo stars verify-skill-mirror-pairs-exist-in-both-opencode-skills-and-clau verify-skill-mirror-pairs-exist-in-both-opencode-skills-and-clau is a Claude Code skill that checks generated skill trees for missing mirrors and folder-slug mismatches. CX Codex +1 ★ 539repo stars

Project sponsors

Companies that keep this analytics open