bollwerkadmin/bollwerk
1
0
Fork 0
Code Issues 9 Pull requests Projects Releases Packages Wiki Activity Actions
bollwerk/.github/skills/git/SKILL.md

11 KiB
Raw Permalink Blame History

name: git description: Expert Git workflow assistant. Use this skill whenever the user mentions anything related to Git: writing commit messages, branching, pull requests, merging, rebasing, resolving conflicts, .gitignore files, changelogs, tagging, stashing, cherry-picking, or undoing changes. Also trigger when the user says "commit", "push", "branch", "PR", "merge", "rebase", "diff", or asks "how do I undo" — even if they don't say "Git" explicitly.

Git Workflow Skill

Provide expert, context-aware Git guidance. Prefer concise, ready-to-run commands over lengthy explanations. Always tailor advice to the user's apparent workflow (solo dev, team, open-source fork, CI/CD pipeline, etc.).

1. Commit Messages

Use the Conventional Commits format by default unless the user has their own convention:

<type>[optional scope]: <short description>

[optional body – what and why, not how]

[optional footer(s): BREAKING CHANGE, Closes #123, Co-authored-by: …]

Types

Type When to use
feat New feature (bumps MINOR in SemVer)
fix Bug fix (bumps PATCH)
docs Documentation only
style Formatting, whitespace (no logic change)
refactor Code change that is neither fix nor feat
perf Performance improvement
test Adding or correcting tests
build Build system or dependency changes
ci CI/CD configuration
chore Maintenance tasks, no production code change
revert Reverts a previous commit

Breaking changes: append ! after the type (feat!:) and/or add BREAKING CHANGE: <description> in the footer.

Workflow for generating a commit message

  1. Look at the staged diff (git diff --cached) or the user's description.
  2. Pick the correct type and optional scope (module, file area, or feature).
  3. Write the description in the imperative mood, lowercase, no trailing period (≤72 chars).
  4. Always write a body — even for small changes. The body must be understandable without reading the diff. See domain-specific rules below.
  5. Add footers for issue references (Closes #42), breaking changes, or co-authors.

Domain-specific body rules

These rules define the minimum context a body must contain depending on what was changed.

Skill changes (files under .github/skills/):

  • Name the skill (e.g. "git skill", "claude-api skill").
  • Name the section or rule that was changed.
  • Explain why it was changed (what problem it solves).

Agent or prompt config changes (files under .github/agents/, .github/prompts/):

  • Name the agent or prompt file.
  • Describe what the file does / what instruction was added or changed.
  • State the motivation.

Migration steps (files under Migration/, Sources/, Tests/):

  • State the step number and title (e.g. "Step 3 – Netzwerkschicht").
  • List which files or modules were created or changed.
  • Call out significant decisions explicitly:
    • Libraries or frameworks chosen (and why, if relevant)
    • Architectural patterns introduced (e.g. MVVM, repository pattern, protocol-oriented design)
    • APIs, protocols or data models defined
    • Deviations from the original migration plan

General fallback rule: the body answers "what was done and why" for a reader who has no access to the diff.

Example – skill change:

chore(git): always write a commit body with domain-specific context

git skill, section "Workflow for generating a commit message":
Added mandatory body rules per change category (skills, agents,
migration steps) so commit history is readable without the diff.
Previously the body was optional and often omitted.

Example – migration step:

feat(migration): implement Step 3 – Netzwerkschicht

Sources/HVACore/Networking/:
- APIClient.swift: generic async/await HTTP client using URLSession
- Endpoint.swift: protocol defining path, method, and body encoding
- AuthInterceptor.swift: injects Bearer token from KeychainService

Decision: chose native URLSession over Alamofire to avoid third-party
dependency; conforms to the architecture defined in Step 2.

Example – feature with issue reference:

feat(auth): add OAuth2 login via GitHub

Users can now sign in with their GitHub account instead of
creating a separate password. Token is stored in an httpOnly cookie.

Closes #88

Example – breaking API change:

feat(api)!: rename /users endpoint to /accounts

BREAKING CHANGE: All clients must update their base URL from /users to /accounts.

2. Branch Naming

Pattern Purpose
main / master Production-ready code
develop Integration branch (Gitflow)
feature/<ticket-or-slug> New feature work
fix/<ticket-or-slug> Bug fix
hotfix/<slug> Urgent production patch
release/<version> Release preparation
chore/<slug> Maintenance / tooling

Keep branch names lowercase, hyphen-separated, ideally scoped to a ticket ID: feature/PROJ-42-user-profile.

Commands:

git switch -c feature/PROJ-42-user-profile   # create + switch (modern)
git push -u origin feature/PROJ-42-user-profile

3. Pull Request / Merge Request Descriptions

A good PR description contains:

  1. What – one-sentence summary of the change.
  2. Why – motivation, linked issue.
  3. How – relevant implementation decisions (optional for small PRs).
  4. Testing – what was tested, test commands.
  5. Screenshots / recordings (for UI changes).
  6. Checklist – [ ] Tests pass, [ ] Docs updated, [ ] No secrets committed.

4. Common Operations – Quick Reference

Undo / Fix

Goal Command
Unstage a file git restore --staged <file>
Discard local changes in file git restore <file>
Undo last commit, keep changes staged git reset --soft HEAD~1
Undo last commit, keep changes unstaged git reset HEAD~1
Undo last commit, discard changes git reset --hard HEAD~1 ⚠️
Revert a pushed commit safely git revert <sha>
Fix last commit message git commit --amend -m "new message"
Add forgotten file to last commit git add <file>; git commit --amend --no-edit

⚠️ --hard and git push --force are destructive. Warn the user before suggesting them, especially on shared branches.

Stash

git stash push -m "WIP: my description"   # save
git stash list                             # view
git stash pop                              # restore latest
git stash apply stash@{2}                 # restore specific
git stash drop stash@{0}                  # delete

Rebase

# Update feature branch on top of main
git switch feature/my-branch
git fetch origin
git rebase origin/main

# Interactive rebase to clean up last 5 commits
git rebase -i HEAD~5

Interactive rebase actions: pick, reword, edit, squash (s), fixup (f), drop (d).

Abort a rebase at any time: git rebase --abort.

Cherry-pick

git cherry-pick <sha>               # apply one commit
git cherry-pick <sha1>..<sha2>      # apply a range
git cherry-pick --no-commit <sha>   # stage without committing

Tags / Releases

git tag -a v1.2.3 -m "Release v1.2.3"
git push origin v1.2.3
git push origin --tags               # push all tags

5. Merge Conflict Resolution

  1. Run git status to see conflicted files.
  2. Open each file — find <<<<<<< HEAD … ======= … >>>>>>> branch markers.
  3. Edit to keep the correct code, remove all markers.
  4. git add <resolved-file> for each file.
  5. git commit (merge) or git rebase --continue (rebase).

Use a visual tool when helpful:

git mergetool                        # uses configured diff tool
git config --global merge.tool vscode

6. .gitignore

When asked to create or update a .gitignore:

  1. Identify the language/framework/OS from context.
  2. Use the patterns from gitignore.io as a baseline.
  3. Add project-specific entries (secrets files, local config, build artifacts).

Useful commands:

git check-ignore -v <file>           # why is a file ignored?
git rm --cached <file>               # stop tracking a file already committed

7. Changelog Generation

When asked to write a CHANGELOG, derive entries from git log:

git log v1.0.0..HEAD --oneline --no-merges

Format using Keep a Changelog:

## [Unreleased]

### Added

- …

### Changed

- …

### Fixed

- …

### Removed

- …

## [1.2.0] – 2026-04-22

### Added

- feat(auth): add OAuth2 login via GitHub

Group Conventional Commits by type: feat → Added, fix → Fixed, refactor/perf → Changed, revert + removals → Removed.

8. Safety Rules

  • Never suggest git push --force on main/master. Use --force-with-lease on personal branches.
  • Warn before any --hard reset or history-rewriting command.
  • Never include secrets, tokens, or passwords in example commands.
  • When the user is on a team, prefer git revert over history rewriting for shared commits.

9. After Every Commit

After executing a git commit, always display the following summary as plain text in the response (no code block, no separate box):

Commit: <short-sha>
Branch: <branch>
Message:

<commit message body, if present>

Example output:

Commit: 2e4cc9de
Branch: master
Message:
chore(git): enrich commit messages with mandatory domain-specific context

git skill, section 'Workflow for generating a commit message':

  • Step 4 changed from optional to mandatory body
  • Added new section 'Domain-specific body rules'

Motivation: commit history should be readable by a user without access to the diff or full repository context.