github-writing-conventions

Files (1)

• SKILL.md

SKILL.md (first lines)

This is on top of `prose-conventions`'s general rules for writing and editing prose.

## Naming vs. Linking References

Backticks name something as an identifier — a repo, an issue/PR, a file — and are fine there whether or not that thing is linkable elsewhere. Whether a reference should also be clickable is a separate choice: match it to whether a click-through is wanted at that point in the text.

An issue or PR link relies on GitHub's autolinking, which fires only on plain text, never inside a code span — so a clickable reference carries no backticks at all, not even around the number. A repo or file string never autolinks, so making one clickable takes an explicit markdown link.

Write each form exactly as the examples below are formatted:

- Naming an issue/PR: `` `threeal/action-starter#1076` ``'s CLAUDE.md implementation replaced...
- Linking an issue/PR, same-repo: fixed by #44
- Linking an issue/PR, cross-repo: fixed by threeal/action-starter#1076, or by the full URL
- Naming a repo: `` `threeal/nodejs-starter` ``'s CLAUDE.md still uses...
- Linking a repo: see [threeal/nodejs-starter](https://github.com/threeal/nodejs-starter)
- Naming a file: `` `src/main.ts` `` handles the entry point
- Linking a file: see [`src/main.ts`](https://github.com/org/repo/blob/main/src/main.ts)

Naming rather than linking an issue/PR fits a possessive phrase, or one already linked once in the same body.

Never link cross-repo with a bare number like #44.
Why: GitHub resolves it against the rendering repo, pointing at whatever issue or PR holds that number there — very likely the wrong thing.

## Issues

Write an issue as narration led by background and rationale — what problem or gap prompted it, what's missing, confusing, or broken, and why that matters. The implementation gets barely any space: a sentence or two near the end, or folded into the closing line.

When the issue adopts a change already tracked in another repo — typically a repo following up on its template — link that repo's issue or PR and don't restate its background or rationale. The narration goes to what's specific to this repo: why the change matters here, or how it differs.
Why: like a PR's closing keyword, the link puts the original reasoning one click away; restating it buries the part only this issue can say.

Prose is the default shape for that narrative, since most issues are one coherent problem description rather than a set of disjoint facts. Use a bullet list, code block, table, or section header wherever it separates genuinely distinct content more clearly than prose would — ordered steps, a short ranking, a before/after comparison, a snippet. The bar is whether the structure earns its place.

## Pull Requests

Always write a meaningful description; never open a PR with an empty or near-empty body.
Why: the point of asking Claude to open the PR is to spare the user writing it themselves.

When the PR closes an issue, open with a closing keyword and reference (e.g. `Closes #44`), then don't restate that issue's background — a brief nod is enough, and the rest of the body goes to the changes actually made.
Why: the keyword both closes the issue on merge and puts the full reasoning one click away.

When the change differs from what its issue described — extra scope, a smaller change, or a different approach — say in the PR description what changed from the plan, why, and how the PR does it instead, and leave the issue as filed.
Why: a reviewer reads the PR against its issue, and a difference with no explanation looks like a mistake. The PR is where the plan change gets recorded, so the issue stays an accurate record of what was known when it was filed.

Justify a change by its own merit, and leave out follow-up work it enables but doesn't include.
Why: pointing at future work frames the PR as a step toward something else, implying it needs that reason to be merged — which weakens a self-justifying change like a version bump whose own reason is already enough.

Don't wrap the whole body in a lone `## Summary` header; write it as plain prose or bullets instead. Add section headers only when the body holds more than one distinct kind of content, such as a summary plus a test plan.

Omit the test plan entirely unless a human has to verify something by hand — skip it when CI or a git hook already covers every relevant check, when the change has no runtime behavior to exercise, or when there's obviously nothing to test. Never include one just to say "N/A".

## Screenshots

Neither `gh` nor the GitHub API can upload images into an issue or PR body or comment, so screenshots have to be dragged into the GitHub editor by the user. Make that step mechanical:

- Save the image files in a `.screenshots/` directory at the repo root, named for what each one shows (`before-login.png`, `after-login.png`), and never commit them.
- In the body or comment, put a visible placeholder wherever each image belongs, naming its exact file — e.g. `**[Drop .screenshots/before-login.png here]**`.
- After opening the issue or PR, tell the user its placeholders are waiting for images, and that `.screenshots/` can be deleted once they're placed.

Why: the dot-prefixed directory stays out of normal listings and goes away in one delete, and a placeholder naming its file leaves no guessing about which image goes where.

## Casing and Punctuation

- PR title: capitalize the first letter — `Add login feature`, not `add login feature`.
- Repo description: capitalize the first letter, and end with no period or other punctuation.

A repo description is a single tagline, a sentence fragment rather than a full sentence. Commas can lightly join related qualities (`Fast, minimal HTTP router for Go`), and one `-` or `—` can join a name to a clarifying clause (`Zod — TypeScript-first schema validation`), but don't stack more than one separator. No emoji.

These rules stop at the About text. A README opener is separate prose — no length limit, and its job is saying what the project actually does rather than fitting a tagline — so editing one is never a reason to bring the other in line with it.
Why: the About text renders stripped of all surrounding context — sidebar, search results, social previews — which is what forces it into a single tagline; a README opener is read inside the project, with everything else there for context, so it carries none of those constraints.

## Topics

Add a topic only for the repo's own purpose, and the language/framework/stack that purpose runs on.
Why: topics exist for people to find and understand a repo at a glance, not to inventory everything it uses.

A supporting tool or dependency — a test framework, a git hooks manager, a formatter, a CI provider — doesn't earn a topic just because the repo relies on it internally, no matter how central it is to the build. It earns one only when it's what the repo is about: `lefthook` on `setup-lefthook-action`, not on a repo that merely runs Lefthook as its hook manager.

Topics don't need to match a parent or sibling repo's list, even under `repo-lineage-uniformity`.
Why: that skill keeps shared config and docs uniform across a lineage, but a repo's topics describe itself, not its ancestry.

From threeal/.claude, MIT.

More from threeal/.claude