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.

Improve create-pr skill guidelines

Juan Denis562254fe06b2
diff --git a/.claude/skills/create-pr/SKILL.md b/.claude/skills/create-pr/SKILL.md
index 2a6a5aeb..3bf10b22 100644
--- a/.claude/skills/create-pr/SKILL.md
+++ b/.claude/skills/create-pr/SKILL.md
@@ -37,7 +37,7 @@ The structure depends on whether the PR introduces user-facing features or is pu
~~~markdown
# <Title>
-<2-3 sentence summary>
+<4-6 sentence summary>
### Highlights
@@ -60,7 +60,7 @@ The structure depends on whether the PR introduces user-facing features or is pu
~~~markdown
# <Title>
-<2-3 sentence summary>
+<4-6 sentence summary>
<details>
<summary>Technical changes</summary>
@@ -77,18 +77,23 @@ Omit the Highlights section entirely for internal-only PRs — don't force it.
### Style Rules
#### Title
-- Imperative mood, start with a verb (Add, Fix, Refactor, etc.)
-- Summarize the entire PR scope — not just one commit
+- **Follow the repo's conventional-commit style:** `type(scope): summary` — e.g. `feat(agent): ...`, `fix(deps): ...`, `ci: ...`, `refactor(api): ...`, `test: ...`. Match the types and scopes already in `git log`; don't invent a new convention.
+- Pick the `type` that covers the **dominant** change across the whole PR, not just one commit. Mixed PRs lean on the most user-significant change (a feature wins over the chores that came with it).
+- Lowercase summary, imperative mood, no trailing period. Keep it under ~70 chars.
+- The CI version-bump keys off commit/title prefixes, so the `type` is functional, not cosmetic — `feat`/`fix` carry release weight; `ci`/`docs`/`test`/`chore` do not.
+- 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.
#### Summary
-- **2-3 sentences max.** This is the elevator pitch, not the full story.
+- **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
-- **Then say what the PR does at a high level.** Name the main change areas (new feature, refactor target, bug fixed) but don't enumerate every file. The personality is in *how* you describe the changes, not in being vague.
-- **Do not repeat what Highlights or Technical changes already cover.** The summary is the "why" and the big picture; details live below.
+- **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.
@@ -115,3 +120,7 @@ Omit the Highlights section entirely for internal-only PRs — don't force it.
- **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
+
+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.