AGENT SKILL

pr-writing

Write or review clear commit messages, PR titles, and PR descriptions that explain what changed and why. Use before writing git history or when asked to improve it. Not for code comments, chat replies, or docs pages.

License 许可
MIT
最近更新
2026-10-21
Stars
★ 0
Forks
0

01 前言 Front Matter

name
pr-writing
license
MIT
metadata
{ "version": "1.0.0" }
description
Write or review clear commit messages, PR titles, and PR descriptions that explain what changed and why. Use before writing git history or when asked to improve it. Not for code comments, chat replies, or docs pages.

02 资源文件 3

03 SKILL.md 正文

PR writing

Full rules: METHODOLOGY.md. Before/after: EXAMPLES.md. Chat shape: RESPONSE.md.

These are requirements, not preferences. A message that breaks one gets rewritten, not shipped.

Operating order

1. Read the diff first

git diff main...HEAD --stat then the real hunks. You cannot state why from a file list.

2. Write the subject (§1)

Under 50 characters. Capitalized. No period. Imperative mood.

Test every subject: "If applied, this commit will ___." If the sentence breaks, the subject is wrong.

Add retry guard to the token refresh path

Banned first words: Added, Adding, Adds, Fixed, Fixes, Updated, Changes, WIP, Misc, Various. Banned anywhere in a subject: emoji, ticket IDs, [tags], trailing ..

3. Blank line, then body wrapped at 72 (§1)

No exceptions — rebase, format-patch, and git log all break without the blank line, and the default pager does not wrap.

4. Body says what and why, never how (§2)

The diff already says how. The body says: the problem that existed, why this solution, what you rejected, what it costs.

5. Apply the language contract (§3–4)

Every sentence, in commits and PR bodies both:

Rule Source Test
Active voice, present tense Google Who does it? Name them.
≤20 words per instruction, ≤25 per statement STE Count it.
One instruction per sentence STE Two verbs → two sentences.
One word, one meaning, everywhere STE Same thing, same noun. No synonyms.
Keep articles (the, a) STE Telegraph style is a defect.
≤3 words per noun cluster STE user account creation failure → rewrite.
Second person you, never we Google we refactored → this change refactors.
Conditions before instructions Google If X, do Y — never Do Y if X.
Sentence case headings, serial commas Google —
Code font for identifiers, paths, flags Google —
ISO dates (2026-08-12) Google Never 08/12/26.

Banned words: simply, just, easily, obviously, please, leverage, utilize, in order to, various improvements, under the hood, out of the box, low-hanging fruit. Banned opener: This PR ... — do not pre-announce.

6. Fill the PR body template (§5)

## What changed
<1–3 sentences. Active voice, present tense.>

## Why
<The problem. The reason for this solution. What you rejected.>

## How to verify
1. <One action per step.>
2. <Expected result, stated concretely.>

## Risk
<What breaks if this is wrong. How to roll it back.>

Closes ABC-123

Drop a section only when it is genuinely empty, and say so: Risk: none — docs only.

7. Gate before you push

bash scripts/pr-lint.sh

Exit non-zero → fix the message. Do not run gh pr create on a failing message.

Non-negotiables

  1. Never git commit -m for a change that needs a body. Use a message file or a heredoc.
  2. The PR title obeys the subject rules exactly — 50 characters, imperative, no period.
  3. A squash-merge message is a commit message. Same rules.
  4. Never let a template heading survive with placeholder text under it.
  5. If you cannot state the why, you do not understand the change yet. Go read the diff again.

04 同仓库更多 Skills

fern-works
fern-works/greenline

use-garden

Consulting garden, the separately installed guidance command this repository's owner enabled, when an open engineering choice the repository does not settle, made in a change or only recommended, would be informed by published guidance. Use for a choice between approaches, a pattern or pitfall for a technology or concern the work touches, or a unit a repository decision names; not for a question about this repository's own facts or a change whose choices are already settled.

★ 0
fern-works
fern-works/greenline

use-garden

Consulting garden, the separately installed guidance command this repository's owner enabled, when an open engineering choice the repository does not settle, made in a change or only recommended, would be informed by published guidance. Use for a choice between approaches, a pattern or pitfall for a technology or concern the work touches, or a unit a repository decision names; not for a question about this repository's own facts or a change whose choices are already settled.

★ 0
fern-works
fern-works/greenline

what-to-build

Propose what this product could do next at three altitudes: sharpen a shipped slice, extend one, or open ground the product does not stand on yet. Use for 'what should we build next', 'any ideas for this app', 'what's missing', 'is this done or is there more in it', and quick-win hunts. Not for refactors, which belong to the architecture survey.

★ 0
fern-works
fern-works/greenline

wayfinder

Plan a huge chunk of work (more than one agent session can hold) as a shared map of decision tickets in a plan directory's map.md, and resolve them one at a time until the way to the destination is clear.

★ 0
fern-works
fern-works/greenline

verify

Prove a change's claims with fresh evidence: restate each item of its acceptance so it can fail, capture a baseline and a treatment with the same command, compare the raw artifacts, and return VERIFIED, NOT VERIFIED or INCONCLUSIVE for each, at the depth the change's mode gives the verify step. Use when the mode reaches verify, or when the owner says "verify this", "prove it works" or "did this fix it".

★ 0
fern-works
fern-works/greenline

tdd

Test-first development at any step: discover the repository's own test commands, name the break a test catches, watch it fail for the intended reason, make it pass with the smallest change, and add a new test only where it catches a realistic failure the existing ones would miss. Use when writing or changing a test, building a feature or fixing a bug test-first, or deciding whether a change needs a new test; also on 'red-green-refactor' and integration tests.

★ 0