# Github Conventions

> Use this skill before creating a branch, writing a commit message, or opening a pull request in this project. Trigger on: "create a branch", "commit this", "write a commit message", "open a PR", "create a pull request", "what should I name this branch", or any time a GitHub workflow action is about to happen.

- Skill: `sakydev/github-conventions` (Agent Skill)
- Install (CLI): `npx skillmds@latest add sakydev/github-conventions`
- Raw SKILL.md: https://api.skillmd.com/api/skills/sakydev/github-conventions/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: sakydev (https://skillmd.com/u/sakydev)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/sakydev/github-conventions

---


# GitHub Conventions

## Branches

Pattern: `<ticket-id>-<short-description>` or `no-ticket-<short-description>`

```
FLX-123-add-storage-driver
no-ticket-add-agentic-instruction-files
```

Branch from `origin/main`. Kebab-case. No slashes. No uppercase.

## Commits

Conventional Commits. Ticket number goes after the type.

```
feat: FLX-1234 add presigned URL download for storage files

- Introduce GetPresignedURL method on StorageService
- Add download endpoint under /storage/:id/download
- Map driver-specific errors to typed pkg/errors responses
```

| Type | When |
|------|------|
| `feat` | New feature or endpoint |
| `fix` | Bug fix |
| `refactor` | Code change, no behaviour change |
| `test` | Adding or fixing tests |
| `chore` | Tooling, deps, config |
| `docs` | Documentation only |

Bullet points. No blank lines between them. One commit per logical change. Never `--no-verify`. Never force-push `main`.

For any change spanning multiple concerns (new module + config + routing + CI, a multi-file refactor, a ticket touching several layers), split into a sequence of small commits — one per chunkable piece (e.g. skeleton, then config, then handler, then wiring, then infra/CI) — instead of one large commit. Each commit should build/typecheck on its own where practical. Default to splitting; only use a single commit when the change is genuinely one atomic unit (a single small fix, a one-file tweak).

## Pull Requests

Title mirrors the commit subject: `type: FLX-1234 short description`. Under 70 characters.

```markdown
## What

What does this PR do and why?

## Changes

- Logical changes. Not a file list.
```

No "this PR" in the title. No trailing period. One PR, one concern. Add `Closes #<issue>` when fixing a GitHub issue. No Test plan section unless explicitly asked. Never add Claude as a co-author — no `Co-Authored-By` lines in commits or PR descriptions.