agentleFS
BinayakDotelBinayakDotel/skills-marketplace/skills/conventional-commits/SKILL.md

conventional-commits

Skill1 starsChanged 36 days agoMITView on GitHub

Write clear, Conventional Commits style commit messages from a diff, staged changes or a short description of the work. Produces a typed subject line, an optional body that explains what and why, and footers for breaking changes and issue references; it also splits a mixed change into several focused commits. Use whenever the user asks for a commit message, says "commit this", "write a commit", "make a commit", wants to reword or tidy an existing message, or asks how to divide work into commits.

62 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use harness-loop, plain-english and 9 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • z3e8Skill

    harness-loop

    Test-drive the pyharness agent from the outside — run a probe task headlessly, inspect what happened with low context cost, fix the harness, re-run. Use when a change needs a real end-to-end run to verify (not just make test), when debugging why a session failed, or when asked to "try a run and see what happens".

    Also in 3 projects that use this

  • MounirDhahriSkill

    plain-english

    Tighten prose by stripping AI tics and applying Orwell/Gowers plain-English rules. Use when the user asks to rewrite, tighten, simplify, or detox writing — phrases like "plain English", "make this clearer", "cut the AI voice", "fix the writing", "rewrite plainly", "tighten this", "detox this". Also run as a self-audit pass before delivering long-form prose (essays, blog posts, articles, reports, documentation) so the output isn't recognisably AI-generated.

    Also in 3 projects that use this

  • xenitV1Skill

    clean-code

    Pragmatic coding standards - concise, direct, no over-engineering, no unnecessary comments

    Also in 3 projects that use this

  • GoogleSkill

    grilling

    Grill the user relentlessly about a plan, decision, or idea. Use when the user wants to stress-test their thinking, or uses any 'grill' trigger phrases.

    Also in 6 projects that use this

  • NVIDIASkill

    github

    Interact with GitHub using the gh CLI restricted to REST API only (no GraphQL). Use when the user wants to work with GitHub issues, pull requests, repos, releases, or Actions — especially in sandboxed environments where the GraphQL endpoint may be blocked. Trigger keywords - github, gh, pull request, PR, github issue, github actions, workflow, release, gh api.

    Also in 3 projects that use this

  • GoogleSkill

    tdd

    Test-driven development. Use when the user wants to build features or fix bugs test-first, mentions "red-green-refactor", or wants integration tests.

    Also in 6 projects that use this

  • +5 more from google

The file

We split this skill into the rules it gives an agent

2 rules. 0 are common, 2 are distinctive, and 0 are very specific to this project.

  • 0

    Common

    Most of the 56 edited versions we read keep these.

  • 2

    Distinctive

    This author's own choices. Worth a look.

  • 0

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Read the change: Prefer the real diff: git diff --staged for staged work, otherwise git diff.

    line 26
  2. Distinctive:

    Do not invent a type or scope the project has not defined.

    line 119

“Common” is measured: kept by at least 6 in 10 of the 56 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Conventional commits

A commit message is read twice: once now by a reviewer, once later by whoever runs git blame. Write a one-line header anyone can scan, and add a body only when it earns its place by explaining why.

Format

<type>(<scope>): <subject>

<body>

<footer(s)>

The subject is one line. Type and scope are optional in the spec but always worth choosing deliberately; a bare update stuff is not a message.

Workflow

  1. Read the change. Prefer the real diff: git diff --staged for staged work, otherwise git diff. If the user only describes the work in prose, use that and state what you assumed.
  2. Choose the type from the table below. Pick the intent, not the file touched: moving code is refactor; adding a capability is feat.
  3. Write the subject: type(scope): summary — imperative, lowercase, no period, ideally ≤ 50 characters (72 is the hard ceiling).
  4. Add a body only if it carries something the subject cannot: the reason, the trade-off, the thing a reader would otherwise have to ask. Wrap at 72; blank line after the subject.
  5. Add footers for breaking changes and issue links.
  6. If the change is really several changes, say so and propose one commit per change instead of piling everything into one message.

Choose the type

typeUse for
feata new capability the user can see
fixa bug fix
docsdocumentation only
refactora behaviour-preserving code change
perfa change that improves speed or memory
testadding or correcting tests
styleformatting only (whitespace, semicolons)
buildbuild system or dependencies
ciCI configuration and scripts
chorehousekeeping that touches neither src nor tests
revertundoing a previous commit

feat and fix are the two that map to releases; use them only when that is genuinely what changed.

The subject line

  • Imperative, present tense: add retry, never added, adds or adding. It should complete "This commit will …".
  • Lowercase after the type, no trailing period, no Requested by chatter.
  • Name the behaviour, not the diff: fix(auth): reject expired tokens, not fix: change line 42.
  • Keep it scannable: aim for ≤ 50 characters; 72 is where tools start to truncate.
  • Scope is a noun for the affected area, lowercase, in parentheses: parser, api, deps. It is a hint, not a requirement — omit it when the change is repo-wide.

The body and footers

  • The body explains what changed and why; the diff already shows how.
  • One blank line between subject and body; wrap at 72; use - bullets for independent points.
  • Record the reasoning that is not in the code: an issue, a constraint, a rejected alternative.
  • Footers go after a blank line:
BREAKING CHANGE: the `token` field is now required
Closes: #128
Refs: #131, #140

A BREAKING CHANGE: footer, or a ! after the type/scope (feat(api)!: drop v1), marks an incompatible change.

Examples

Good — a feature with context:

feat(auth): add magic-link sign-in

Email a one-time link so users can sign in without a password.
Existing session keys are unchanged, so this is additive.

Closes: #204

Good — a fix that names the cause:

fix(pagination): stop dropping the last page

The cursor was compared with `<` instead of `<=`, so the final
partial page was never returned. Add a test for the odd-count case.

Good — one-liners:

docs(readme): document the skills install command
refactor(parser): extract the token reader into its own module
test(rate-limit): cover the burst boundary
chore: bump pytest to 8.3

Avoid:

update stuff
fixed bug
WIP
Added a new feature and also fixed the login and refactored css

The first three say nothing. The last hides three unrelated changes that belong in three commits.

Rules

  • One logical change per commit. If the subject needs "and", split it.
  • Do not invent a type or scope the project has not defined; if the repo already has its own convention, follow that instead and say so.
  • Describe the effect, not the file (document the install command, not change SKILL.md).
  • Match the language and wording style of the existing log.
  • Output the message ready to paste. Do not commit, push or reword history unless the user explicitly asks.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.