Skip to content

ServerKit is a lightweight, modern server control panel for managing web applications, databases, and services on your VPS or dedicated server. Built with Python/Flask backend and React frontend.

docs(skills): revise pull request description guidance

Juan Denis6a77f5e5aed9
diff --git a/.claude/skills/create-pr/SKILL.md b/.claude/skills/create-pr/SKILL.md
index 87b1a5cb..7840454d 100644
--- a/.claude/skills/create-pr/SKILL.md
+++ b/.claude/skills/create-pr/SKILL.md
@@ -1,186 +1,128 @@
---
name: create-pr
-description: Draft or revise a local ServerKit pull request title and description from the branch diff. Use for PR descriptions and dev-to-main promotion notes; keep issue replies, advisories, and marketing copy in their own formats.
+description: Generate a pull request title and description from the current branch's commits. Produces a concise summary, optional feature highlights, and collapsible technical details.
---
# Create PR Description
-Write for a reviewer who has not seen the conversation. Explain the problem,
-the resulting behavior, and the evidence needed to assess the change. Save a
-local Markdown draft; creating or updating a GitHub PR is a separate action.
+Generate a pull request title and description that's scannable, informative, and has just enough personality to feel human.
-## Establish the comparison
+## Instructions
-Read the repository instructions and any PR template. Inspect the branch,
-working-tree status, and available refs before selecting a base:
+### 1. Gather context (do ALL of these)
+
+Run these commands to build a complete picture before writing anything:
```bash
-git status --short
-git branch --show-current
-git branch -a
+# Commit overview
+git log main..HEAD --oneline --stat
+
+# Full diff stat for file-level scope
+git diff main..HEAD --stat
+
+# Actual code changes — read the diff, don't just skim filenames
+git diff main..HEAD
```
-Use the user's specified base or the existing PR's base when available. For
-ServerKit's normal workflow, feature branches target `dev`; `dev` promotions
-target `main`. Check `.github/workflows/main-promotion.yml` if the requested
-target conflicts with that flow. Explain the conflict without changing the
-branch or silently choosing a different target. Ask only if the intended
-comparison cannot be resolved from the request and repository context.
+If the full diff is too large, diff individual areas (backend routes, frontend, storage, etc.) in batches. You must understand **what the code actually does**, not just which files were touched.
-Resolve the base to an available ref, preferring the intended remote-tracking
-ref when present. Record the exact base and HEAD commit IDs used. Local refs
-can be stale; do not describe them as current remote state without checking.
+### 2. Write the PR file
-With `BASE_REF` replaced by that resolved ref, inspect:
+Write the file to `.pr/YYYY-MM-DD.md` (using today's date). Create the `.pr/` directory if it doesn't exist. If a file for today's date already exists, append a counter: `YYYY-MM-DD-2.md`, `YYYY-MM-DD-3.md`, etc.
-```bash
-git log BASE_REF..HEAD --oneline
-git diff BASE_REF...HEAD --stat
-git diff BASE_REF...HEAD
-git log BASE_REF..HEAD --format='%aN <%aE>'
-```
+The structure depends on whether the PR introduces user-facing features or is purely internal (refactors, bug fixes, infra).
-The three-dot diff compares HEAD to the merge base, so base-only changes do
-not enter the description. Read large diffs by area, including relevant
-callers when needed to understand behavior. Use commits for context and
-authorship; describe the final diff, including fixes made during review.
-
-Uncommitted edits do not belong to the branch comparison unless the user asks
-to include them. If included, inspect staged and unstaged diffs and identify
-that scope in the handoff. If the comparison is empty or refs are missing,
-report that instead of inventing a PR. Do not change code or run a broad audit
-as a prerequisite to writing the description.
-
-## Choose the amount of detail
-
-The visible body stays short no matter how large the branch is. A reviewer
-reads it before deciding to expand anything, so it carries the problem, the
-resulting behavior, and what they must act on — not the implementation.
-
-- A small fix usually needs a title, one short paragraph, and relevant
- validation. Two sentences can be enough. Do not pad it to a sentence quota,
- and do not add an accordion it does not need.
-- Anything larger keeps the same shape: two or three short paragraphs, then
- `### Contributors` when others authored commits, `### Highlights` as
- user-facing outcomes, short `### Upgrade notes` and `### Validation`, then
- everything else inside `<details><summary>Technical changes</summary>`.
- Skip Highlights if it would repeat the paragraphs.
-- Aim for roughly 400 words before the accordion. A large promotion does not
- earn a longer body; it earns a longer appendix.
-
-Inside the accordion, group bullets under bold subsystem labels. Cover material
-changes and risks, but group mechanical edits instead of writing a file-by-file
-inventory; link an existing detailed review or plan when it helps. Put blank
-lines around Markdown inside it. Do not promote implementation detail into the
-body, and do not give the body its own `##` sections per subsystem — that is
-what the accordion is for. Keep upgrade actions, breaking changes, security
-limitations, and validation visible outside it. Omit empty sections and
-template placeholders. Do not invent a shared story for unrelated changes.
-
-## Write the description
-
-**Title.** Start the file with `# <Title>`. Use a plain sentence-case title that
-names the main behavior, preferably under 70 characters, with no trailing
-period. Preserve the project's preference for no `feat:`, `fix:`,
-`type(scope):`, or square-bracket tags. A subsystem label is fine when useful.
-This heading supplies the eventual PR title; the remaining content is the body.
-
-**Opening.** Lead with the concrete problem and what changes. For a bug, name
-the trigger and the before/after behavior. For a feature, say what the user can
-now do. Explain a design choice when its reason matters to review and is
-supported by the diff or recorded context. Do not invent motives or rejected
-alternatives. Move protocol timings and long identifier lists into details.
-
-**Voice.** Use direct, conversational prose. Do not manufacture personality
-with a joke, metaphor, apology, or dramatic reveal. Cut stock openers such as
-"This is the big one," "Turns out," "Three gremlins," and "This PR builds the
-bridge." Replace praise such as "real," "proper," "honest," "seamless," or
-"robust" with the behavior that earns it. Avoid repeated "one door" or
-"same story" framing, "not X, but Y" slogans, and "riding along" transitions.
-Keep a technical contrast when it explains an actual compatibility boundary
-or tradeoff. Technical qualifiers and terms such as "read-only" or "atomic"
-are useful when precise; this is an editorial pass, not a word blacklist.
-
-**Evidence and limits.** Tie factual claims to the inspected diff, supplied
-evidence, or an identified check. Keep distinctions between implemented,
-verified, and expected behavior. "Reject pending-MFA tokens on login-link
-routes" is more precise than "2FA can no longer be bypassed." Describe the
-covered platforms and paths instead of promising future compatibility or
-claiming a bug cannot recur. Date measurements and state what they measure;
-file counts and line reductions usually belong out of the summary. Do not
-infer performance gains from fewer queries or smaller source files alone.
-
-**Validation.** Include concise, relevant results when available, even for
-internal changes. Name what was checked and any material gap. Added tests or
-CI configuration are changes, not proof that checks passed. Do not invent
-results, imply a historical run covered the current HEAD, or rerun expensive
-suites just to fill this section. If no execution evidence is available, say
-that validation was not run or results were not available, as applicable.
-
-**Upgrade and security notes.** Make required migrations, session invalidation,
-new permission requirements, data-retention changes, and remaining limitations
-easy to find. Preserve the distinction between JWT-only and API-key-capable
-routes; an authentication decorator change can expand access. State the
-specific boundary and any known exception. Do not turn a security fix into
-a blanket assurance about the product.
-
-**Contributors.** For multi-author work, credit contributors other than the
-repo owner in a short section. Exclude bots and consolidate known aliases.
-Use a verified GitHub handle when available, otherwise the author's name;
-do not guess handles from email addresses or expose their email addresses.
-Keep contribution notes tied to the commits or supplied attribution.
-
-No emoji, generated-by footer, or commentary about making the draft sound human.
-
-## Examples
-
-These edits illustrate scope and tone using the local archive. They do not
-establish fresh validation of those historical changes.
-
-**Small change** (`.pr/2026-08-21-6.md`):
-
-```markdown
-# Consolidate the shared error state
-
-`ErrorBoundary` now renders the shared `ErrorState` component. The extension
-SDK exports the same component, preserving the boundary's reporting, retry,
-and route-reset behavior.
-```
+#### When the PR has user-facing features:
+
+~~~markdown
+# <Title>
+
+<4-6 sentence summary>
+
+### Highlights
+
+- Highlight 1
+- Highlight 2
+- ...
+
+<details>
+<summary>Technical changes</summary>
+
+- Detail 1
+- Detail 2
+- ...
+
+</details>
+~~~
+
+#### When the PR is purely internal (no user-facing features):
+
+~~~markdown
+# <Title>
+
+<4-6 sentence summary>
+
+<details>
+<summary>Technical changes</summary>
+
+- Detail 1
+- Detail 2
+- ...
+
+</details>
+~~~
+
+Omit the Highlights section entirely for internal-only PRs — don't force it.
+
+### Style Rules
+
+#### Title
+- **Write a normal, human title — NOT a conventional-commit prefix.** Name the PR the way you'd describe it to a teammate. **No `type(scope):`, no `feat:` / `fix:` / `chore:` lead-in, no square-bracket tags** in the title.
+ - Good: `Add the Cloudflare DNS provisioning extension` · `Harden the subprocess audit against injection`
+ - Bad: `feat(dns): add cloudflare provisioning` · `fix: subprocess injection` · `chore(deps): bump`
+- Capitalize the first word like a sentence; imperative or plain-descriptive are both fine; no trailing period. Keep it under ~70 chars.
+- Leading with the subsystem and a colon in plain words is fine when it aids scanning: `Backend: …`, `Extensions: …`.
+- The `# <Title>` line at the top of the generated file **is** the PR title — when the PR is eventually opened, that same string is the `gh pr create --title` value. Don't write a second, different headline.
+- **Where the release weight actually lives (so you can safely keep it out of the title):** `version-bump.yml` reads the *commit message* pushed to `dev` (`github.event.head_commit.message`), **not this title.** A `feat:`/`feature:`/`minor:` prefix or a `[minor]` tag in the commit → minor bump; `BREAKING:`/`major:` or `[major]` → major; anything else → patch. Put any bump intent in your **commits**; leave the PR title human.
+
+#### Summary
+- **4-6 sentences.** This is the part people actually read — give it room to breathe.
+- **Open with a touch of personality.** One line that makes the reader smile — a wry observation, a lighthearted remark, a playful metaphor. Not forced, just human. Examples of the energy (don't copy these literally, invent your own each time):
+ - "This one's mostly about cleaning house."
+ - "Turns out the type checker was right to complain."
+ - A playful metaphor about what the code was doing wrong
+ - A wry observation about the state of things before this PR
+- **Match the tone to the change.** The voice should fit what the PR actually is — a bug fix can read dry and a little relieved ("This should've been caught months ago."), a new feature can read genuinely excited, a refactor can read like satisfying cleanup, a security fix should stay sober and matter-of-fact. Don't paste the same energy onto every PR; that's just a different kind of static.
+- **Then explain what was going on and what this PR does about it.** Set the scene — what was broken, missing, or annoying? What's the approach? Name the main change areas (new feature, refactor target, bug fixed) but describe them in context, not as a dry list. The reader should walk away understanding the *story* of this PR, not just a changelog.
+- **Include the "why" and the reasoning.** If there was a design choice, a trade-off, or a particular reason you went one way instead of another, mention it briefly. "We went with X instead of Y because Z" is the kind of thing that saves people from asking in review.
+- **Do not repeat what Highlights or Technical changes already cover** verbatim, but it's fine to reference the same areas — the summary gives narrative context, the sections below give specifics.
+
+#### Highlights (only when applicable)
+- One bullet per user-facing feature, behavior change, or notable improvement.
+- Write from the user's perspective — what they'll notice, not internal implementation.
+- Plain language, no code references. "Schedules now respect your configured timezone" not "`SchedulerService` gains a `timezone` attribute".
+- 3-7 bullets is the sweet spot. If you can only think of 1-2, fold them into the summary and skip this section.
+
+#### Technical changes (inside the accordion)
+- One bullet per discrete change. Be specific — name files, classes, functions, patterns.
+- Format: `backtick code references` for identifiers, plain text for descriptions.
+- Every meaningful change in the diff must have a bullet. If a change touches security (CORS, auth, SQL injection), error handling, accessibility, or concurrency, it gets its own bullet — do not bury these.
+- Bullets should describe the mechanism, not just the intent. "Race condition in `get_or_create_chat` fixed by moving creation inside the lookup session" is good. "Fix database issues" is not.
+- Group related changes together (all typing fixes, all security hardening, all API changes, etc.)
+
+#### Contributors
+- If the PR includes commits from multiple authors (not just the repo owner), add a **Contributors** section after the summary and before Highlights.
+- Use `git log main..HEAD --format='%aN <%aE>' | sort -u` to find unique commit authors.
+- Exclude bot accounts (e.g., `github-actions[bot]`).
+- Format: `@username` if their GitHub handle is available (check the ARGUMENTS or commit metadata), otherwise use their name. Add a brief note about what they contributed if it's clear from the commits.
+- Keep it short — one line per contributor, no need for a full changelog.
+
+#### General
+- **No test plan section.** Do not include "Test plan" or "Testing".
+- **No mention of tests.** Do not reference test files, test results, or testing.
+- **No emoji.**
+- **No "Generated by" footer.**
+
+### 3. Stop after writing the file
-Add actual validation evidence or an accurate statement that it is unavailable.
-This change does not need Highlights and a technical accordion.
-
-**Bounded security claim** (`.pr/2026-09-05.md`): replace "Two-factor
-authentication can no longer be stepped around" with "Pending-2FA tokens expire
-after five minutes and cannot administer login links. Redeeming a link requires
-the target account's TOTP step when enabled."
-
-**Direct explanation** (`.pr/2026-08-21-7.md`): replace "The one design call
-worth flagging" and its long setup with "Resource pickers use an extended mode
-of `/search` to share the command palette's authorization checks. Pickers opt
-into cursor paging; the palette keeps its five-results-per-type limit."
-
-## Save and review
-
-For a new draft, create `.pr/` if needed and write `.pr/YYYY-MM-DD.md` using the
-current local date. If it exists, use the next available suffix (`-2`, `-3`,
-...). When asked to revise
-an existing draft, update that file instead of generating another dated copy.
-Do not rewrite other historical drafts unless requested.
-
-Read the finished draft against the final diff. Remove repeated explanations,
-unnecessary setup, and claims stronger than the evidence. Check that required
-upgrade actions remain visible and that links, paths, credit, and validation
-match the chosen scope. Do not copy changing counts or release status from
-an older `.pr` file without checking them.
-
-Release behavior belongs to the workflows. If bump intent matters, inspect
-`.github/workflows/version-bump.yml`; it reads the commit message pushed to
-`dev`. A PR title can become that message through a squash or merge workflow,
-so do not promise the title can never affect versioning. Drafting a description
-does not authorize changing commit messages or `VERSION`.
-
-Return the draft's path and a brief handoff identifying the comparison used
-and any material evidence gap. Stop at the local draft unless the user has
-also authorized publishing or updating the PR. Honor that authorization when
-present; otherwise do not push, open/edit a remote PR, or post comments.
+This skill's job ends when the `.pr/` file is written. **Do not** run `gh pr create`, `git push`, or any other remote-affecting command to actually open the PR — that's a separate, explicit step the user requests on its own. Print the path of the file you wrote and a one-line note that it's ready to review/copy.