Git Workflow
This skill provides instructions for working with Git repositories and their
forges. Use git for local operations and gf for forge operations (issues,
pull requests, labels) and worktree management. gf auto-detects the forge
(GitHub or Gitea), so the same commands work regardless of the remote.
Tasks described in this skill:
- Generate Commit Message
- Create Issue
- Create Pull Request
- Create Worktree
- Remove Worktree
- Resolve the Issue
Common arguments
gf commands share these arguments:
<title>: Title of an issue or pull request. Must be concise (max 50
characters) and follow the Conventional Commit style,
<type>(<scope>): <description> or <type>: <description>, with a lowercase
description in the imperative mood.
e.g. feat(doc): add issue creation procedure<type>: One of the following:
feat: A new featurefix: A bug fixdocs: Documentation only changesstyle: Changes that do not affect meaning (formatting, white-space, etc.)refactor: A code change that neither fixes a bug nor adds a featureperf: A code change that improves performancetest: Adding or correcting testschore: Auxiliary tools, e.g. documentation generationbuild: Changes to the build system or external dependenciesci: Changes to CI configuration files and scripts
<scope>: Optional area of the change, e.g. doc, api, workflow.<body>: Body of an issue or pull request, composed from its template.<label>: Label name. Get the available labels with gf label list.<target_branch>: Base branch of a pull request. Defaults to main.<number>: Issue or pull request number.<branch_name>: Name of the branch to work on, following the Conventional
Commit style or the issue tag, e.g. feat/add-login.
Strict Rules
- The title and body MUST NOT contain any ANSI escape sequences, terminal
control codes, or other non-printable characters, including:
- SGR / color codes such as
\x1b[31m, \033[0m, [1;32m
- Cursor and screen codes such as
\x1b[2k, \x1b[?25l, \x1b[H
- Any byte in the ranges
\x00-\x08, \x0B-\x1F, or \x7F
- If any command output you read contains such sequences, strip them before
including the content. After composing the body, scan it once more and remove
any remaining bytes that match
\x1B\[, \x1B\], or other C0/C1 control
characters.
Generate Commit Message
Procedure
- Run
git --no-pager diff --cached --no-color to get staged changes.
- Based on the staged changes, generate a commit message following the
Conventional Commit style (see Common arguments).
- Output ONLY the raw commit message with no code blocks, explanations,
or fillers.
Create Issue
IF you're asked to create an issue, THEN you MUST work on this task.
Procedure
- Understand the user's request, problem report, or improvement idea.
- If the repository context is needed, inspect relevant files to understand the
current implementation, configuration, documentation, or behavior.
- Create the
<title> using the Conventional Commit style.
- Get the labels with
gf label list and select a <label> from the list.
If the list is empty, there is no label.
- Get the body template with
gf issue template --label <label>.
- Compose the
<body> following the template.
- Run
gf issue create --title <title> --body <body> --label <label>.
Create Pull Request
IF you're asked to create a pull request (PR), THEN you MUST work on this task.
Procedure
- Run
git --no-pager diff --no-color <target_branch>...HEAD to get the
changes between the current branch and the target branch.
- Create the
<title> using the Conventional Commit style.
- Get the body template with
gf pr template.
- Compose the
<body> following the template.
- Run
gf pr create --title <title> --body <body> -B <target_branch> --label <label>.
Create Worktree
When you're required to create a worktree or an isolated copy to edit files,
create one with gf worktree create.
Procedure
- Analyze the user request to understand your task.
- Determine the
<branch_name>. Use the tag the user specified; otherwise
derive it from the request.
- Run
gf worktree create -b <branch_name>. It creates the worktree at
~/.tmp/<repository-name>_<branch-name> (the repository name is detected
from the remote) and prints the path. Work in that directory.
Notes
gf reuses the branch if it already exists; otherwise it creates a new one.gf places the worktree under ~/.tmp/, never in the project directory.
Remove Worktree
When you're requested to remove a worktree, use this skill.
Procedure
- Run
gf worktree delete -b <branch_name> to remove the worktree.
Notes
- This removes only the worktree directory; the branch is kept.
Resolve the Issue
When you're required to resolve an issue or something to edit files in the
project, use this skill and follow the instructed procedure.
Procedure
- Analyze the user request.
- If the issue number is specified, view it with
gf issue view <number>.
Otherwise list issues with gf issue list and ask the user which to resolve.
- If no issue matches the user request, create a new issue
(see Create Issue).
- Create a worktree and branch for the issue
(see Create Worktree).
- Edit files in the worktree to resolve the issue.
- Commit your changes (see Generate Commit Message)
and push the branch to the remote repository.
- Create a pull request linked to the issue
(see Create Pull Request).
- Remove the worktree (see Remove Worktree).
Strict Rules
- Do NOT work on the current branch directly.
Always create a new branch for your work
and create a pull request to merge it into the current branch
or the user specified branch.
Source: shunya-sasaki/dotfiles — distributed by TomeVault.
1---2name: git-workflow-1063description: When you're asked to work with Git, you MUST use this skill. Use when this capability is needed.4---56# Git Workflow78This skill provides instructions for working with Git repositories and their9forges. Use `git` for local operations and `gf` for forge operations (issues,10pull requests, labels) and worktree management. `gf` auto-detects the forge11(GitHub or Gitea), so the same commands work regardless of the remote.1213Tasks described in this skill:1415- Generate Commit Message16- Create Issue17- Create Pull Request18- Create Worktree19- Remove Worktree20- Resolve the Issue2122## Common arguments2324`gf` commands share these arguments:2526- `<title>`: Title of an issue or pull request. Must be concise (max 5027 characters) and follow the **Conventional Commit** style,28 `<type>(<scope>): <description>` or `<type>: <description>`, with a lowercase29 description in the imperative mood.30 e.g. `feat(doc): add issue creation procedure`31- `<type>`: One of the following:32 - `feat`: A new feature33 - `fix`: A bug fix34 - `docs`: Documentation only changes35 - `style`: Changes that do not affect meaning (formatting, white-space, etc.)36 - `refactor`: A code change that neither fixes a bug nor adds a feature37 - `perf`: A code change that improves performance38 - `test`: Adding or correcting tests39 - `chore`: Auxiliary tools, e.g. documentation generation40 - `build`: Changes to the build system or external dependencies41 - `ci`: Changes to CI configuration files and scripts42- `<scope>`: Optional area of the change, e.g. `doc`, `api`, `workflow`.43- `<body>`: Body of an issue or pull request, composed from its template.44- `<label>`: Label name. Get the available labels with `gf label list`.45- `<target_branch>`: Base branch of a pull request. Defaults to `main`.46- `<number>`: Issue or pull request number.47- `<branch_name>`: Name of the branch to work on, following the **Conventional48 Commit** style or the issue tag, e.g. `feat/add-login`.4950### Strict Rules5152- The title and body MUST NOT contain any ANSI escape sequences, terminal53 control codes, or other non-printable characters, including:54 - SGR / color codes such as `\x1b[31m`, `\033[0m`, `[1;32m`55 - Cursor and screen codes such as `\x1b[2k`, `\x1b[?25l`, `\x1b[H`56 - Any byte in the ranges `\x00`-`\x08`, `\x0B`-`\x1F`, or `\x7F`57- If any command output you read contains such sequences, strip them before58 including the content. After composing the body, scan it once more and remove59 any remaining bytes that match `\x1B\[`, `\x1B\]`, or other C0/C1 control60 characters.6162## Generate Commit Message6364### Procedure65661. Run `git --no-pager diff --cached --no-color` to get staged changes.672. Based on the staged changes, generate a commit message following the68 **Conventional Commit** style (see [Common arguments](#common-arguments)).693. Output ONLY the raw commit message with no code blocks, explanations,70 or fillers.7172## Create Issue7374IF you're asked to create an issue, THEN you MUST work on this task.7576### Procedure77781. Understand the user's request, problem report, or improvement idea.792. If the repository context is needed, inspect relevant files to understand the80 current implementation, configuration, documentation, or behavior.813. Create the `<title>` using the **Conventional Commit** style.824. Get the labels with `gf label list` and select a `<label>` from the list.83 If the list is empty, there is no label.845. Get the body template with `gf issue template --label <label>`.856. Compose the `<body>` following the template.867. Run `gf issue create --title <title> --body <body> --label <label>`.8788## Create Pull Request8990IF you're asked to create a pull request (PR), THEN you MUST work on this task.9192### Procedure93941. Run `git --no-pager diff --no-color <target_branch>...HEAD` to get the95 changes between the current branch and the target branch.962. Create the `<title>` using the **Conventional Commit** style.973. Get the body template with `gf pr template`.984. Compose the `<body>` following the template.995. Run `gf pr create --title <title> --body <body> -B <target_branch> --label <label>`.100101## Create Worktree102103When you're required to create a worktree or an isolated copy to edit files,104create one with `gf worktree create`.105106### Procedure1071081. Analyze the user request to understand your task.1092. Determine the `<branch_name>`. Use the tag the user specified; otherwise110 derive it from the request.1113. Run `gf worktree create -b <branch_name>`. It creates the worktree at112 `~/.tmp/<repository-name>_<branch-name>` (the repository name is detected113 from the remote) and prints the path. Work in that directory.114115### Notes116117- `gf` reuses the branch if it already exists; otherwise it creates a new one.118- `gf` places the worktree under `~/.tmp/`, never in the project directory.119120## Remove Worktree121122When you're requested to remove a worktree, use this skill.123124### Procedure1251261. Run `gf worktree delete -b <branch_name>` to remove the worktree.127128### Notes129130- This removes only the worktree directory; the branch is kept.131132## Resolve the Issue133134When you're required to resolve an issue or something to edit files in the135project, use this skill and follow the instructed procedure.136137### Procedure1381391. Analyze the user request.1402. If the issue number is specified, view it with `gf issue view <number>`.141 Otherwise list issues with `gf issue list` and ask the user which to resolve.1423. If no issue matches the user request, create a new issue143 (see [Create Issue](#create-issue)).1444. Create a worktree and branch for the issue145 (see [Create Worktree](#create-worktree)).1465. Edit files in the worktree to resolve the issue.1476. Commit your changes (see [Generate Commit Message](#generate-commit-message))148 and push the branch to the remote repository.1497. Create a pull request linked to the issue150 (see [Create Pull Request](#create-pull-request)).1518. Remove the worktree (see [Remove Worktree](#remove-worktree)).152153### Strict Rules154155- Do NOT work on the current branch directly.156 Always create a new branch for your work157 and create a pull request to merge it into the current branch158 or the user specified branch.159160---161> Source: [shunya-sasaki/dotfiles](https://github.com/shunya-sasaki/dotfiles) — distributed by [TomeVault](https://tomevault.io).162<!-- tomevault:4.0:skill_md:2026-06-15 -->
tomevault-io