Skip to content
Back to search

git-flowkit-skills

Portable Agent Skill for branch naming, Conventional Commits, PR templates, and offline semantic release previews using your repository policies.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/whale-devx--git-flowkit-skills/badge.svg)](/listings/whale-devx--git-flowkit-skills)

HTML

<a href="/listings/whale-devx--git-flowkit-skills"><img src="/api/listings/whale-devx--git-flowkit-skills/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

npx skills add whale-devx/git-flowkit-skills --skill git-flowkit

Choose your coding agent in the installer. Add `-g` for a user-global installation. The installer is the external [Skills CLI](https://github.com/vercel-labs/skills), not an npm package published by this project. Check its current Node.js requirements. For a manual installation, copy the complete `skills/git-flowkit` directory into your agent's documented skills directory; do not copy `SKILL.md` alone.

For an existing project-local copy, record its commit before upgrading. [Upgrade and rollback instructions](skills/git-flowkit/references/upgrading.md)

Ask your agent:

> Use git-flowkit to inspect this repository, follow its existing rules, and prepare > a branch, Conventional Commit, PR description, and release preview. Do not publish.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 165 lines
  1. # Git FlowKit
  2. **AI Git workflows, Conventional Commits, and safe semantic releases. Your rules.**
  3. [English](README.md) · [ภาษาไทย](README.th.md) · [Configuration](skills/git-flowkit/references/configuration.md) · [Release setup](skills/git-flowkit/references/releases.md)
  4. One portable Agent Skill for branch naming, commits, pull requests, merge messages,
  5. and release planning. Reuse your existing repository policies instead of replacing
  6. them with another agent's defaults.
  7. > **Initial implementation — not a published stable release.** The offline helpers
  8. > are executable and tested. Remote release automation is opt-in. Cross-agent
  9. > end-to-end compatibility is not yet certified; see [compatibility](skills/git-flowkit/references/compatibility.md).
  10. [Install by agent or integrate an API client](skills/git-flowkit/references/compatibility.md#project-installation-by-host)
  11. ## Install the skill
  12. ```bash
  13. npx skills add whale-devx/git-flowkit-skills --skill git-flowkit
  14. ```
  15. Choose your coding agent in the installer. Add `-g` for a user-global installation.
  16. The installer is the external [Skills CLI](https://github.com/vercel-labs/skills), not
  17. an npm package published by this project. Check its current Node.js requirements.
  18. For a manual installation, copy the complete `skills/git-flowkit` directory into your
  19. agent's documented skills directory; do not copy `SKILL.md` alone.
  20. For an existing project-local copy, record its commit before upgrading.
  21. [Upgrade and rollback instructions](skills/git-flowkit/references/upgrading.md)
  22. Ask your agent:
  23. > Use git-flowkit to inspect this repository, follow its existing rules, and prepare
  24. > a branch, Conventional Commit, PR description, and release preview. Do not publish.
  25. ## What is implemented
  26. | Capability | Included in this implementation |
  27. | --- | --- |
  28. | Repository discovery | Local policy, native PR/MR templates, supported release-engine signals, conflicts |
  29. | Branch and commits | Configurable naming pattern, ticket IDs, Conventional Commit validation, breaking markers |
  30. | Templates | Editable commit, PR, merge, and release templates; local/global resolution; strict placeholder validation |
  31. | Safe setup | Preview by default; explicit local apply; no overwrites; idempotent initialization |
  32. | Version planning | Single-package SemVer preview, custom bump rules, pre-1.0 policy, initial prerelease creation |
  33. | Release automation | Review-gated Release Please scaffold; this repository's automation waits for all CI jobs |
  34. | Merge readiness | Offline evidence checks for HEAD, freshness, approvals, checks, protection, and review threads |
  35. | Portability | Agent Skills format; Python 3.11+ and Git; standard library only; no provider API dependency |
  36. **Not claimed:** autonomous merges, built-in registry publishing, universal native-config
  37. parsing, monorepo dependency propagation, or end-to-end testing in every coding agent.
  38. Existing semantic-release, Changesets, Python Semantic Release, release-plz, GoReleaser,
  39. and JReleaser configurations are detected and retained, not reimplemented.
  40. ## Try the helpers
  41. From a clone of this repository, with Python 3.11+ and Git:
  42. ```bash
  43. python skills/git-flowkit/scripts/flowkit.py doctor
  44. python skills/git-flowkit/scripts/flowkit.py branch feat "Add team templates" --ticket DEV-42
  45. python skills/git-flowkit/scripts/flowkit.py check-commit --message "feat(templates): add team templates"
  46. python skills/git-flowkit/scripts/flowkit.py render pr --data examples/pr-data.json --template skills/git-flowkit/assets/templates/pr.md
  47. python skills/git-flowkit/scripts/flowkit.py release-preview --current 1.4.2 --commits examples/commits.json
  48. ```
  49. The examples produce `feat/DEV-42-add-team-templates` and an advisory next version of
  50. `1.5.0`. No branch or release is created. Example PR validation is explicitly **not run**.
  51. For a multiline migration note, use `check-commit --file MESSAGE.txt`.
  52. `check-commit` and `release-preview` retain the full `BREAKING CHANGE:` note
  53. in `breaking_notes`, up to the next footer such as `Refs #42`.
  54. For another repository, put `--repo /path/to/repository` **before** the command and
  55. invoke the script from its actual installation path.
  56. ```text
  57. python <installed-skill>/scripts/flowkit.py --repo <your-repo> init
  58. python <installed-skill>/scripts/flowkit.py --repo <your-repo> init --apply
  59. ```
  60. `init` creates only missing files. Edit `.git-flowkit.json` to select the generated
  61. `.git-flowkit/templates/*.md` files. Native repository templates keep precedence until
  62. you explicitly select another template. `init --global --apply` sets up personal defaults.
  63. For GitHub PRs, FlowKit finds `pull_request_template.md` or `.txt` in the repository root,
  64. `.github/` or `docs/`. It also finds named Markdown and text files directly inside a
  65. `PULL_REQUEST_TEMPLATE/` directory in each location. File names are case-insensitive.
  66. When several templates apply, pass the repository-relative path with `render pr --template`.
  67. ## Configuration is yours
  68. ```json
  69. {
  70. "version": 1,
  71. "branch": { "pattern": "{type}/{ticket}{slug}" },
  72. "commit": { "require_scope": true, "max_subject_length": 72 },
  73. "templates": { "pr": ".git-flowkit/templates/pr.md" },
  74. "release": { "engine": "auto", "pre1_breaking": "minor" }
  75. }
  76. ```
  77. JSON is the implemented configuration format; the earlier proposed YAML interface is
  78. not a shipped parser. Native engine configuration retains its original format.
  79. [Full configuration reference](skills/git-flowkit/references/configuration.md) explains
  80. precedence, validation, global paths, supported fields, and migration boundaries.
  81. ## From change to release
  82. ```mermaid
  83. flowchart LR
  84. A[Discover repository rules] --> B[Prepare branch and commit]
  85. B --> C[Draft PR and merge message]
  86. C --> D[Validate actual evidence]
  87. D --> E[Authorized merge]
  88. E --> F[Native release engine]
  89. F --> G[Review release PR]
  90. G --> H[Tag and GitHub release]
  91. ```
  92. The agent prepares and checks. Repository protections and the native release engine
  93. remain authoritative. For this repository, CI can create Release Please PRs and releases
  94. only after a maintainer explicitly sets `FLOWKIT_RELEASE_ENABLED=true`.
  95. The first ordinary release candidate is configured as `0.1.0`. Subsequent
  96. candidates use the previous release and the project's commit policy.
  97. It does not publish to npm or PyPI. See the [activation checklist](skills/git-flowkit/references/releases.md).
  98. If the release job fails after creating a release, check the tag's commit and the
  99. PR labels before retrying. [Release recovery checks](skills/git-flowkit/references/releases.md#recover-a-release-after-an-interrupted-run)
  100. ## Safety and verification
  101. The CLI never commits, pushes, merges, tags, fetches, installs packages, or publishes.
  102. Only `init --apply` and `release-setup --apply` write missing local files. Templates are
  103. inert text; config cannot inject executable template expressions. Read the
  104. [security policy](SECURITY.md) and [evidence contract](skills/git-flowkit/references/safety.md).
  105. ```bash
  106. python -m unittest discover -s tests -v
  107. python tools/validate_repo.py
  108. ```
  109. CI is configured for Linux, macOS, and Windows on Python 3.11 and 3.13. A configured
  110. matrix is not a claim that every run has passed; inspect the PR's actual checks.
  111. ## Contribute
  112. Start with [CONTRIBUTING.md](CONTRIBUTING.md). High-value contributions include reproducible
  113. agent compatibility tests, translations, native-engine fixtures, and safety regressions.
  114. [ROADMAP.md](ROADMAP.md) distinguishes shipped behavior from planned work.
  115. Built around [Agent Skills](https://agentskills.io/specification),
  116. [Conventional Commits 1.0.0](https://www.conventionalcommits.org/en/v1.0.0/),
  117. and [Semantic Versioning 2.0.0](https://semver.org/).
  118. See [sources](skills/git-flowkit/references/sources.md) for the upstream specifications.
  119. MIT licensed. Existing license attribution is preserved.
  120. From a Git checkout, reproduce the project-local install and helper journey with
  121. `python tools/install_smoke.py candidate`. Use `python tools/install_smoke.py main`
  122. for the public source. Both need npm registry access, Node.js with npx, Python and Git.
  123. The main check also needs GitHub access and the main commit in the checkout.
  124. Each run creates a disposable project and prints the revision and installed path.
  125. When a Windows log uses a legacy encoding, characters it cannot represent appear as Unicode escapes.
  126. If the installer fails, inspect its output and rerun after connectivity returns.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.