Remove AI writing tropes from skill docs
Assisted-by: Claude Opus 4.8 via Claude Code
change lvtqrsuunylopqxokyzvrqstuvqsqlmx
commit bf1ef5593f4b83febd0bf7d5ef660f68bb586cdd
author Alpha Chen <alpha@kejadlen.dev>
date
parent wzqnyxsk
diff --git a/ai/skills/describing-changes/SKILL.md b/ai/skills/describing-changes/SKILL.md
index ee966cb9..b636a68a 100644
--- a/ai/skills/describing-changes/SKILL.md
+++ b/ai/skills/describing-changes/SKILL.md
@@ -63,7 +63,17 @@ conventional commit prefixes (`fix:`, `feat:`, `refactor:`, etc.):
 Reduce visual noise in error construction
 ```
 
-**STOP: Is the title sufficient?** If yes, you're done. No body needed.
+**HARD STOP before adding body text.** Ask yourself:
+
+1. Can a reader reconstruct the *reasoning* from the diff alone?
+   If yes, **stop here. Title only.**
+2. Does the diff show *what* changed but not *why*?
+   If no, **stop here. Title only.**
+3. Would a sentence in the body just paraphrase the diff?
+   If yes, **delete it. Title only.**
+
+**Default to title-only.** Most commits need no body. Adding body
+text is the exception, not the rule.
 
 **Add body ONLY if:**
 - Reasoning is truly non-obvious from diff
@@ -82,12 +92,12 @@ Normalizing both to milliseconds avoids migration.
 **Format:**
 - Title: Under 60 characters, plain English, capitalized first word
 - Body: 1-2 sentences maximum, under 20 words total
-- Problem → Solution (omit needless words)
+- Problem, then solution (omit needless words)
 
 **Before adding ANY body text, audit:**
-- Is this sentence invisible in the diff? (No → delete it)
-- Does this describe implementation visible in the code? (Yes → delete it)
-- Does this just restate what a careful diff reader would see? (Yes → delete it)
+- Is this sentence invisible in the diff? (If no, delete it.)
+- Does this describe implementation visible in the code? (If yes, delete it.)
+- Does this just restate what a careful diff reader would see? (If yes, delete it.)
 
 Each sentence must explain reasoning not visible in the code change itself.
 
diff --git a/ai/skills/designing-for-ios/SKILL.md b/ai/skills/designing-for-ios/SKILL.md
index b2522417..a46baa9f 100644
--- a/ai/skills/designing-for-ios/SKILL.md
+++ b/ai/skills/designing-for-ios/SKILL.md
@@ -80,8 +80,8 @@ Use tab bars for top-level navigation between app areas. Toolbars act on content
 
 ### System Fonts
 
-- **SF Pro**: system sans-serif for iOS
-- **New York (NY)**: serif alternative
+- SF Pro, the system sans-serif for iOS.
+- New York (NY), a serif alternative.
 - Both support variable font format with dynamic optical sizing.
 
 ### Default and Minimum Sizes
diff --git a/ai/skills/dotslash/SKILL.md b/ai/skills/dotslash/SKILL.md
index a452b4ef..736302a7 100644
--- a/ai/skills/dotslash/SKILL.md
+++ b/ai/skills/dotslash/SKILL.md
@@ -112,8 +112,8 @@ dotslash -- cache-dir              # Print cache directory path
 
 ## Key details
 
-- **Hash**: Use `blake3` (preferred) or `sha256`. The `create-url-entry` helper defaults to blake3.
-- **Providers are tried in order**. Put the direct HTTP URL first (faster for public repos), GitHub Release provider second (works when authenticated).
-- **`format` must be a recognized value**: `tar.gz`, `tar.zst`, `tar.xz`, `tar.bz2`, `tar`, `zip`, `gz`, `zst`, `xz`, `bz2`, or omitted for uncompressed binaries. Note: `tgz` is not valid — use `tar.gz`.
-- **`path` must be a normalized relative UNIX path**. No leading `./`, no `..`, no trailing `/`, no backslashes.
-- **Cache location**: `~/Library/Caches/dotslash` on macOS.
+- Use `blake3` (preferred) or `sha256` for the hash. The `create-url-entry` helper defaults to blake3.
+- Providers are tried in order. Put the direct HTTP URL first (faster for public repos), then the GitHub Release provider (works when authenticated).
+- The `format` field must be a recognized value: `tar.gz`, `tar.zst`, `tar.xz`, `tar.bz2`, `tar`, `zip`, `gz`, `zst`, `xz`, `bz2`, or omitted for uncompressed binaries. `tgz` is not valid; use `tar.gz`.
+- The `path` must be a normalized relative UNIX path: no leading `./`, no `..`, no trailing `/`, no backslashes.
+- The cache lives at `~/Library/Caches/dotslash` on macOS.
diff --git a/ai/skills/jj-workspaces/SKILL.md b/ai/skills/jj-workspaces/SKILL.md
index 5c9e8d05..e1ad1e2e 100644
--- a/ai/skills/jj-workspaces/SKILL.md
+++ b/ai/skills/jj-workspaces/SKILL.md
@@ -8,7 +8,7 @@ description: Use when needing isolated workspace for experiments, parallel devel
 
 ## Overview
 
-Create isolated jj workspaces for experimentation, parallel development, and subagent coordination. All workspaces share repository history, enabling seamless switching and comparison.
+Create isolated jj workspaces for experimentation, parallel development, and subagent coordination. All workspaces share repository history, so switching between them and comparing their changes needs no extra setup.
 
 **Core principle:** Isolation by design. Each workspace operates independently with zero risk of interference.
 
diff --git a/ai/skills/nvim-pack/SKILL.md b/ai/skills/nvim-pack/SKILL.md
index 4b697072..fbd7423c 100644
--- a/ai/skills/nvim-pack/SKILL.md
+++ b/ai/skills/nvim-pack/SKILL.md
@@ -52,7 +52,7 @@ Located at `$XDG_CONFIG_HOME/nvim/nvim-pack-lock.json`. Tracks `rev`, `src`, and
 
 **Revert after update:** Restore lockfile from VCS (`git checkout HEAD -- nvim-pack-lock.json` or `jj restore`), then `:restart` and `:lua vim.pack.update(nil, {offline = true, target = "lockfile"})`.
 
-**Cross-machine sync:** Commit lockfile → pull on other machine → `:restart` → `:lua vim.pack.update(nil, {target = "lockfile"})`.
+**Cross-machine sync:** Commit the lockfile, pull on the other machine, `:restart`, then run `:lua vim.pack.update(nil, {target = "lockfile"})`.
 
 ## PackChanged Events