Replace conventional commit prefixes with git trailers
Commit subjects should be plain English sentences. Metadata like
issue references and AI attribution belongs in git trailers at the
bottom of the message, not encoded in the subject line.

Assisted-by: Claude Opus 4.6 via pi
change mpqlvxsqyzkolpmuvwrolvukvztovpot
commit 5f6a212d11bbf147b427d673c34a61659f83f5fa
author Alpha Chen <alpha@kejadlen.dev>
date
parent owkxvyol
diff --git a/ai/_AGENTS.md b/ai/_AGENTS.md
index a8d6a568..de82f31d 100644
--- a/ai/_AGENTS.md
+++ b/ai/_AGENTS.md
@@ -127,6 +127,16 @@ Commit quality:
 - Every commit must build and pass checks (bisect-able history)
 - Separate formatting and refactoring from feature changes
 
+Commit message format:
+- No conventional commit prefixes (`fix:`, `feat:`, `refactor:`, etc.)
+- Subjects are plain English sentences — capitalize the first word,
+  keep it under 60 characters
+- Use [git trailers](https://alchemists.io/articles/git_trailers)
+  for metadata, placed after a blank line at the bottom of the message
+- Trailer format is `Key: value` (capitalized key, colon, space, value)
+- `Assisted-by` is mandatory when AI drafts the message (the
+  `describing-changes` skill enforces this)
+
 ## Anti-rationalization
 
 These conventions exist because LLMs skip steps when unsupervised.
diff --git a/ai/skills/describing-changes/SKILL.md b/ai/skills/describing-changes/SKILL.md
index d5cb8827..2a37efe8 100644
--- a/ai/skills/describing-changes/SKILL.md
+++ b/ai/skills/describing-changes/SKILL.md
@@ -56,10 +56,11 @@ What's the impact?
 
 ### 5. Write the Description
 
-**Start with title only.** Type prefix + concise reasoning:
+**Start with title only.** Write a plain English sentence — no
+conventional commit prefixes (`fix:`, `feat:`, `refactor:`, etc.):
 
 ```
-refactor: Reduce visual noise in error construction
+Reduce visual noise in error construction
 ```
 
 **STOP: Is the title sufficient?** If yes, you're done. No body needed.
@@ -72,14 +73,14 @@ refactor: Reduce visual noise in error construction
 When body is necessary:
 
 ```
-fix: Normalize TTL unit mismatch
+Normalize TTL unit mismatch
 
 TTL (seconds) and timestamp (milliseconds) compared directly.
 Normalizing both to milliseconds avoids migration.
 ```
 
 **Format:**
-- Title: Under 60 characters, concrete problem or fix
+- Title: Under 60 characters, plain English, capitalized first word
 - Body: 1-2 sentences maximum, under 20 words total
 - Problem → Solution (omit needless words)
 
@@ -107,16 +108,36 @@ Each sentence must explain reasoning not visible in the code change itself.
 | "This is obvious from the code" | Obvious to you ≠ obvious to reviewers | Obvious what changed. Not obvious why. |
 | "Need to explain the approach" | Title may be sufficient | STOP: Is title sufficient? Most commits need no body. |
 
-## Footer Requirements
+## Git Trailers
 
-If AI assisted in crafting the message, include Assisted-by footer:
+Use [git trailers](https://alchemists.io/articles/git_trailers) for
+all commit metadata. Trailers are `Key: value` pairs placed after a
+blank line at the bottom of the commit message. Never encode metadata
+in the subject line — that's what trailers are for.
 
 ```
-Assisted-by: Claude Haiku 4.5 via pi
+Normalize TTL unit mismatch
+
+TTL (seconds) and timestamp (milliseconds) compared directly.
+Normalizing both to milliseconds avoids migration.
+
+Assisted-by: Claude Opus 4.6 via pi
 ```
 
-Format: `Assisted-by: [Model name] via [tool name]`
+### Required trailers
+
+`Assisted-by` is mandatory when AI drafts or substantially edits the
+message. Format: `Assisted-by: [Model name] via [tool name]`. Use the
+actual model and tool you are running inside — do not copy examples
+blindly.
+
+### Optional trailers
+
+Add other trailers when they provide useful context for post-processing
+or traceability:
 
-Use the actual tool you are running inside (e.g., pi, Claude Code). Do NOT copy the example blindly.
+- `Issue: <id>` — links the commit to a tracked issue
+- `Co-authored-by: Name <email>` — credits collaborators
 
-This is MANDATORY when using this skill. Do NOT omit it.
+Capitalize the first letter of each trailer key. Keep trailers
+alphabetically sorted when there are three or more.