Skip to main content
skill CX Codex

contributing · zaxbyhub, opencode — Claude Code skill: what it does, how to install

contributing walks an agent through the full pull-request cycle in the opencode-swarm repo: branch naming, commit format, a release-notes fragment, local checks and the PR template.

MIT ★ 539 updated 2026-10-29

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

What contributing does

Load it before touching git in opencode-swarm. It starts with a branch off a fresh main named <type>/<short-description>, then dependencies via bun install --frozen-lockfile.

Commit subjects follow <type>(<scope>): <description> in lowercase, no trailing period. A feat bumps minor, fix and perf bump patch, while docs, test and chore leave the version alone. Breaking changes take a ! after the type or a BREAKING CHANGE: footer. Every user-visible PR also ships a fragment at docs/releases/pending/<slug>.md; computing a version or creating docs/releases/vX.Y.Z.md is off limits because release-please owns that.

Five tiers must pass locally before the push: typecheck and Biome, unit tests, integration tests, the security and adversarial suites, then build with smoke. All of it runs on bun, so a machine without it stalls at the first step. The version field in package.json, CHANGELOG.md and .release-please-manifest.json stay out of the diff, and every uses: line under .github/workflows/ gets pinned to a full 40-char SHA.

What it helps with

  • branch off the latest main with a name CI accepts
  • write a commit subject that passes check-title
  • add a release-notes fragment without bumping the version
  • run all five check tiers before pushing
  • keep release-please files out of the PR diff

Example prompts for the agent

  • Load the contributing skill and create a fix/plan-sync-race branch from main.
  • Does my PR title pass check-title? Draft the pending release fragment too.
  • Run all five tiers locally before I push.

How to install contributing

1Skills CLI (Vercel)

npx skills add ZaxbyHub/opencode-swarm --skill contributing -a claude-code

2Manually: put the files in place

~/.claude/skills/contributing/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/contributing/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about contributing

How do I install contributing in Claude Code?

Run npx skills add ZaxbyHub/opencode-swarm --skill contributing -a claude-code. The skill file lands at ~/.claude/skills/contributing/SKILL.md.

What does contributing do?

It lays out the PR workflow for opencode-swarm: branch naming, commit and PR title format, a required release-notes fragment, five local check tiers and the description template.

Can I edit CHANGELOG.md or the version in package.json myself?

No. release-please manages those files along with .release-please-manifest.json, so manual edits do not belong in a PR.

Source text

SKILL.md · MIT
---
name: contributing
description: >
  End-to-end PR workflow for opencode-swarm. Covers branch setup, conventional
  commits, mandatory release notes, 5-tier CI checks, and PR submission format.
  Load this skill before creating branches, commits, or pull requests.
---

# Contributing to opencode-swarm

## 1. Branch Setup

```bash
git checkout main && git pull origin main
git checkout -b <type>/<short-description>
bun install --frozen-lockfile
```

Branch naming: `<type>/<short-description>` (e.g. `feat/add-retry-backoff`, `fix/plan-sync-race`).

## 2. Commit Message Format (Conventional Commits)

Every commit MUST follow: `<type>(<optional scope>): <description>`

Rules:
- Description lowercase, no trailing period
- Scope optional but encouraged

| Type | Changelog section | Version bump |
|------|-------------------|-------------|
| `feat` | Features | minor |
| `fix` | Bug Fixes | patch |
| `perf` | Performance | patch |
| `revert` | Reverts | patch |
| `docs` | Documentation | none |
| `chore` | — | none |
| `refactor` | — | none |
| `test` | — | none |
| `ci` | — | none |
| `build` | — | none |

Breaking changes: add `BREAKING CHANGE: <description>` footer or `!` suffix on type (e.g. `feat!:`). Triggers major bump.

Valid examples:
- `feat(architect): add retry backoff to SME delegation`
- `fix(circuit-breaker): prevent race condition on concurrent invocations`
- `refactor(swarm): extract phase orchestration into dedicated module`

Invalid (rejected by CI):
- `WIP`, `fix stuff`, `Update README`, `feat: Add feature.` (trailing period), `Feat:` (uppercase)

## 3. Release Notes (MANDATORY — every user-visible PR, no exceptions)

⛔ Do NOT compute the next version. ⛔ Do NOT create `docs/releases/vX.Y.Z.md`. ⛔ Do NOT write to a shared `docs/releases/unreleased.md`. release-please owns the version; the release workflow aggregates fragments at release time.

1. Choose a short, kebab-case slug describing your change. Pick one unlikely to collide with concurrent PRs.
2. Create `docs/releases/pending/<your-slug>.md`.

Include:
- What changed (grouped by theme)
- Why (bug report, feature request, hardening)
- Migration steps (if any)
- Breaking changes (if any)
- Known caveats

Use a descriptive heading (`# <topic>`), not a version prefix. Even one-line changes need a fragment explaining why it matters. Aggregation is done by `scripts/release-notes-fragments.mjs` via `.github/workflows/release-and-publish.yml` — each PR owning its own unique file is what eliminates the merge-conflict hotspot.

## 4. Run All Checks Locally (5 tiers, all must pass)

```bash
# Tier 1: Quality
bun run typecheck
bunx biome ci .

# Tier 2: Unit tests
bun test tests/unit --timeout 120000

# Tier 3: Integration tests
bun test tests/integration ./test --timeout 120000

# Tier 4: Security & adversarial
bun test tests/security --timeout 120000
bun test tests/adversarial --timeout 120000

# Tier 5: Build + smoke
bun run build
bun test tests/smoke --timeout 120000
```

**`package-check` CI failures:** `package-check` validates the npm tarball (`npm pack` + tarball contents) and is the authoritative packaging gate. A failure is a source/build/package-manifest problem, not generated-file drift. `dist/` is generated and NOT committed — do not stage it; run `bun run build` locally only when you need the bundle. There is no longer a committed-dist drift check.

If a pre-existing unrelated failure exists, note it in the PR description but do NOT skip other tiers.

## 5. Push and Open PR

```bash
git push -u origin <branch-name>
```

PR title MUST be a valid conventional commit: `<type>(<scope>): <description>`

PR body template:
```
## Summary
- Bullet 1
- Bullet 2

## Test plan
- [ ] Tier 1 quality checks pass
- [ ] Unit tests pass
- [ ] Integration tests pass
- [ ] Security/adversarial tests pass
- [ ] Build + smoke tests pass
```

## 6. Do NOT Manually Edit These Files

release-please manages these automatically:
- `package.json` version field
- `CHANGELOG.md`
- `.release-please-manifest.json`

Never replace the release PR body, create tags/releases manually, or edit these files.

## 7. CI Checks

The protected `main` ruleset requires the exact contexts in the
[`required-check-contract.json`](../../scripts/required-check-contract.json)
and its [fresh external evidence](../../docs/ci/required-check-evidence.json).
This is the live required set, not a claim that every listed job or matrix cell
runs on every pull request.

| Live required context(s) | Validates |
|-------|-----------|
| `quality` | TypeScript compiles, Biome lint + format clean |
| `security` | Security & adversarial tests pass |
| `unit (ubuntu-latest, 1)` through `unit (ubuntu-latest, 4)` and `unit-passed` | Required Ubuntu shards and their aggregate; extra platform cells are event- or path-scoped |
| `package-check` and `integration` | Package and integration checks pass |
| `smoke (ubuntu-latest)`, `smoke (macos-latest)`, `smoke (windows-latest)` | Required platform package builds and smoke tests pass |
| `php-validation` and `rust-sandbox-runner` | Language/build validation passes |
| `check-title` and `pr-standards` | PR title and standards checks pass |
| `coverage` | Merge-group-only union coverage gate |

`release-owner-guard` is a dependency helper for the required `quality` context,
not a standalone required context. `check-duplicates` is a non-required helper.
The local `drift` workflow includes `pull_request`, `push` to `main`, and
`merge_group: checks_requested`, but `drift` remains intended-only until ruleset
promotion; its pre-promotion divergence is a visible nonblocking notice. See
[`docs/ci-required-check-contract.md`](../../docs/ci-required-check-contract.md).

## 8. GitHub Actions SHA Pinning

All `uses:` in `.github/workflows/` must be pinned to full 40-char SHA with version comment:
```yaml
- uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5.0.1
```

Find SHA: `gh api repos/{owner}/{repo}/git/ref/tags/{tag} --jq '.object.sha'`

## PR Checklist

- [ ] Branch created from latest `main`
- [ ] Every commit follows `<type>(<scope>): <description>`
- [ ] PR title follows same format
- [ ] No manual edits to `package.json` version, `CHANGELOG.md`, or `.release-please-manifest.json`
- [ ] `docs/releases/pending/<unique-slug>.md` exists with release notes (NOT a `docs/releases/vX.Y.Z.md` file)
- [ ] New tests in correct `tests/` subdirectory
- [ ] Tests updated for any changed behavior
- [ ] If modifying workflows, all `uses:` are SHA-pinned
- [ ] All 5 CI tiers pass locally
- [ ] PR description includes summary and test plan

© ZaxbyHub · MIT · ZaxbyHub/opencode-swarm

Similar skills

All skills for Git and GitHub →

contributing by other authors comes first.

contributing ZaxbyHub contributing is a Claude Code skill that maps commits, test runs and PRs to the opencode-swarm checklist, including the required release fragment. CX Codex +1 ★ 539repo stars task-to-pr owainlewis task-to-pr — a skill that carries a spec, issue, or task to an open pull request: branch, tests, Conventional Commits, CI, and an independent review. Merges only on explicit request. CX Codex +1 452installs git-workflow Netresearch DTT GmbH git-workflow — a skill for Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, and OpenCode that enforces Git standards. Automates pull request validation and blocks unreviewed merges. CX Codex +1 759installs create-pull-request davila7 create-pull-request — a Claude Code command that opens a pull request via GitHub CLI against the project's own PR template. It fires when a branch is ready and you need a draft PR with all template sections filled in. CX Codex +1 411installs changelog-generator Alireza Rezvani changelog-generator is a Claude Code skill that builds release notes from Conventional Commits and recommends a SemVer bump. It runs for release prep, commit checks, and hotfix planning. CX Codex +1 618installs ship raphaelsalaja A skill for Claude Code takes finished changes through commits, merges, releases and production checks. It runs when asked to push, merge or ship work. CX Codex +1 167installs devkit.github.create-pr Giuseppe Trisciuoglio devkit.github.create-pr — a Claude Code command that creates a branch, commits changes following Conventional Commits, and opens a GitHub pull request with a structured description. CX Codex +1 ★ 372repo stars

From the same set121

The whole set →
parallel-work-check parallel-work-check is a Claude Code skill that compares local and remote commits on an existing branch and reviews new changes. It helps catch overlapping work before editing. CX Codex +1 ★ 539repo stars design-docs Writes and syncs a project's design docs: domain, technical spec, behavior spec, plus a traceability registry and changelog. CX Codex +1 ★ 539repo stars orchestrating-subagents orchestrating-subagents is a Claude Code skill for dividing project tasks among subagents, with parallel explorers and independent code review in isolated contexts. CX Codex +1 ★ 539repo stars commit-pr The commit-pr skill guides commits, pull request updates, and CI checks in opencode-swarm. Use it when publishing issue-related code changes or closing out a PR. CX Codex +1 ★ 539repo stars clarify-spec clarify-spec resolves spec clarification markers and ambiguous requirements in Swarm projects by asking targeted questions one at a time. CX Codex +1 ★ 539repo stars pre-phase-briefing pre-phase-briefing builds phase-start context, reviews prior retrospectives, and checks whether the referenced codebase matches the planned work. CX Codex +1 ★ 539repo stars rust-crate-ci rust-crate-ci — a skill for editing the runners/swarm-sandbox-runner crate: it fixes the order of local checks and flags Windows breakage that only CI would catch. CX Codex +1 ★ 539repo stars clarify clarify filters requirements through a four-stage funnel with critic evaluation to build decision packets without noisy questions. CX Codex +1 ★ 539repo stars

Project sponsors

Companies that keep this analytics open