diff --git a/.claude/skills/pr/SKILL.md b/.claude/skills/pr/SKILL.md
index 0f5f1add..ba1d1dcc 100644
--- a/.claude/skills/pr/SKILL.md
+++ b/.claude/skills/pr/SKILL.md
@@ -42,6 +42,8 @@ Never write a title containing "and".
 - Format: `type(scope)!: subject`. Types and scopes come from the dev.md tables.
 - The scope names what a reader recognises, a stacklet or a bot, never a file.
 - Imperative, lowercase after the colon, no full stop, no identifiers.
+- Name the concrete change, not its effect: `add an install hint to restart
+  core on the first start`, not `say how to finish the agent's first start`.
 - Limit 72 characters as commit-lint counts them; dev.md asks for under 70. The
   ` (#N)` appended at merge does not count.
 - Use `!` only when the user must act. The description then carries `Upgrade:`
@@ -59,6 +61,12 @@ Refs: #127
 ```
 
 - One to three bullets. Footers only when they apply.
+- Start with the situation the PR answers, then what it changes: "The agent
+  is beta. After its first `./stack up agent`, it can sign in only after a
+  core restart." then "The hints shown after `./stack up agent` tell the
+  admin to run `./stack restart core`, then `./stack restart agent`."
+- Plain technical English: state what the change does. No paraphrase such
+  as "now say so" or "provide the required information".
 - No "Test plan" section. Test output and measurements go in a PR comment.
 - No em dashes. Use a comma, colon, period or parentheses.
 - No `Co-Authored-By`, no "Generated with" line, no tool link: this repository is
diff --git a/docs/agent/dev.md b/docs/agent/dev.md
index 174ee8f9..172cad3c 100644
--- a/docs/agent/dev.md
+++ b/docs/agent/dev.md
@@ -366,12 +366,20 @@ Paperless behaviour; a README fix is `docs(readme):`. A scope outside the
 table still commits and lands under General, so drift surfaces at release time
 rather than on the website.
 
-**Subject rules.** Describe the**Subject.** Imperative mood: it completes "If applied, this commit will
+**Subject.** Imperative mood: it completes "If applied, this commit will
 ...". Lowercase after the colon, no full stop, at most 72 characters
 including the prefix. Describe the change as an admin sees it: no class,
 file or function names unless an admin types them. A subject that needs
 "and" is two commits.
 
+Name the concrete change, what is added, fixed or removed, not a
+paraphrase of its effect:
+
+```
+fix(agent): say how to finish the agent's first start                # the effect: says nothing
+fix(agent): add an install hint to restart core on the first start   # the change
+```
+
 **Body.** Blank line after the subject, wrapped at 72. Why the change is
 needed and what it changes; the diff shows how. It must make sense without
 the PR. Bullets for sets of changes. No debugging history, test narrative