ai: fix stale refs and conflicts in agent instructions
Assisted-by: Claude Opus 5.5 via Claude Code
diff --git a/ai/_AGENTS.md b/ai/_AGENTS.md
index 86e95b89..a79e7187 100644
--- a/ai/_AGENTS.md
+++ b/ai/_AGENTS.md
@@ -19,7 +19,8 @@ are meaningless to humans.
- Cite primary sources: the documentation, spec, or code itself, not
a summary or a recollection of it
- When working with GitHub, read .github templates for PRs and issues
-- Attribute AI-written content when possible (Co-Authored-By, footer, or similar)
+- Attribute AI-written content: commits and PRs use the `Assisted-by`
+ trailer (`describing-changes` owns the format); elsewhere, a footer
- Preserve user input exactly unless asked to modify it
- "Update based on my comments" means find inline comments I've left
(in files, on a PR, in a doc, etc.), apply the feedback, and remove
diff --git a/ai/claude/rules/model-selection.md b/ai/claude/rules/model-selection.md
index 3ee2ef11..c8a354d3 100644
--- a/ai/claude/rules/model-selection.md
+++ b/ai/claude/rules/model-selection.md
@@ -1,48 +1,10 @@
-# Model Selection
+# Model selection for subagents
-Default to Opus for interactive sessions. Drop down when the task is
-clearly mechanical.
+When you spawn a subagent, pick its model from what the subtask needs:
-## Opus
+- Opus for judgment: design, debugging, multi-file refactors, review.
+- Sonnet for bounded, well-specified work with clear instructions.
+- Haiku for mechanical work: lookups, formatting, boilerplate.
-The default. Interactive coding, reasoning, architecture decisions,
-multi-file refactors, debugging, writing, code review — anything
-involving judgment or conversation.
-
-## Sonnet
-
-Background tasks and well-scoped autonomous work where the instructions
-are clear and the task is bounded.
-
-## Haiku
-
-Commit messages, simple lookups, formatting, mechanical edits, generating
-boilerplate. Anywhere speed matters more than depth.
-
-## When to question the default
-
-Opus is wrong when:
-- The task is bounded and well-specified — Sonnet finishes faster at
- near-identical quality. Long Opus sessions on mechanical work waste
- latency and cost.
-- You're iterating in a tight loop (manual edits, repeated small
- prompts). Sonnet's speed compounds.
-- You're using Fast mode out of habit but the work is exploratory —
- the speed bias is hiding under-thought design.
-
-Signals to drop a level mid-session:
-- You're correcting Claude on simple facts more than once.
-- The remaining work is mechanical follow-through on a decided plan.
-- You're paying for a 1M context window on a 20k-token task.
-
-## When spawning subagents
-
-The tiers above are defaults, not a lookup table to apply mechanically.
-Use judgment on the actual subtask rather than defaulting every subagent
-to Sonnet: a complex multi-file refactor delegated to a subagent may
-still warrant Opus, while a one-line lookup fits Haiku even run inline.
-
-Reserve the main loop's reasoning for judgment-heavy work — design,
-review, synthesis — once an approach is decided, delegate the
-implementation and let the choice of subagent tier follow from what the
-subtask actually needs.
+These are defaults, not a lookup table. A complex refactor handed to a
+subagent may still warrant Opus; a one-line lookup fits Haiku.
diff --git a/ai/skills/bash/SKILL.md b/ai/skills/bash/SKILL.md
index 02f4bb89..c52aeb0d 100644
--- a/ai/skills/bash/SKILL.md
+++ b/ai/skills/bash/SKILL.md
@@ -81,4 +81,4 @@ compelling reason.
---
-*This is a self-improving skill — see the `self-improving-skills` skill.*
+*This is a self-improving skill. If you used it and it came up short — a missing command, flag, gotcha, or workflow — invoke the `self-improving-skills` skill and follow it before you finish.*
diff --git a/ai/skills/commit/SKILL.md b/ai/skills/commit/SKILL.md
index bc858962..4d4dda72 100644
--- a/ai/skills/commit/SKILL.md
+++ b/ai/skills/commit/SKILL.md
@@ -1,6 +1,6 @@
---
name: commit
-description: Use when the user asks to "commit changes", "commit my work", "/commit", "create a commit", "jj commit", "describe a change", "describe a revision", "/describe", "rewrite commit message", or "update revision description"
+description: Use when committing work with jj, or writing or rewriting a revision's description (including /commit and /describe)
argument-hint: <revision, fileset, or instructions>
allowed-tools: [Bash(jj diff *), Bash(jj show *), Bash(jj log *), Bash(jj st *), Bash(jj workspace list)]
---
diff --git a/ai/skills/dependency-management/SKILL.md b/ai/skills/dependency-management/SKILL.md
index aaa552ca..43999baa 100644
--- a/ai/skills/dependency-management/SKILL.md
+++ b/ai/skills/dependency-management/SKILL.md
@@ -86,4 +86,4 @@ problem.
---
-*This is a self-improving skill — see the `self-improving-skills` skill.*
+*This is a self-improving skill. If you used it and it came up short — a missing command, flag, gotcha, or workflow — invoke the `self-improving-skills` skill and follow it before you finish.*
diff --git a/ai/skills/describing-changes/SKILL.md b/ai/skills/describing-changes/SKILL.md
index 8b1ca853..3048a358 100644
--- a/ai/skills/describing-changes/SKILL.md
+++ b/ai/skills/describing-changes/SKILL.md
@@ -16,7 +16,7 @@ Not for describing how code works — that is separate from why it changed.
## Implementation
-**REQUIRED SUB-SKILL:** Use the technical-writing skill. Change descriptions are prose for humans; apply the writing skill to ensure clarity and conciseness.
+Apply the `technical-writing` skill: change descriptions are prose for humans.
### 1. Identify What Changed
diff --git a/ai/skills/design-notes/SKILL.md b/ai/skills/design-notes/SKILL.md
index 9a7f1112..3462107f 100644
--- a/ai/skills/design-notes/SKILL.md
+++ b/ai/skills/design-notes/SKILL.md
@@ -7,7 +7,7 @@ description: Use when starting non-trivial implementation work, when design deci
Supplementary notes on designing software with AI, accumulated from experience and external sources.
-*This is a self-improving skill — see the `self-improving-skills` skill.*
+*This is a self-improving skill. If you used it and it came up short — a missing command, flag, gotcha, or workflow — invoke the `self-improving-skills` skill and follow it before you finish.*
## Before proposing: read the existing record
diff --git a/ai/skills/editing-prose/SKILL.md b/ai/skills/editing-prose/SKILL.md
index 90c12519..c6492237 100644
--- a/ai/skills/editing-prose/SKILL.md
+++ b/ai/skills/editing-prose/SKILL.md
@@ -9,9 +9,8 @@ Catches AI writing tropes that other writing skills miss. Sources:
[tropes.fyi](https://tropes.fyi) and
[Modeltell](https://github.com/thirdshiftlab/modeltell).
-Complements `technical-writing` (structure, terminology),
-`writing-clearly-and-concisely` (sentence-level clarity), and
-`diataxis` (document classification). Those skills cover good writing in
+Complements `technical-writing` (structure, terminology, sentence-level
+clarity) and `diataxis` (document classification). Those skills cover good writing in
general; this one covers the specific patterns LLMs reach for that flag
text as AI-generated.
diff --git a/ai/skills/jj-workspaces/SKILL.md b/ai/skills/jj-workspaces/SKILL.md
index ccf2a3dd..c2fbd011 100644
--- a/ai/skills/jj-workspaces/SKILL.md
+++ b/ai/skills/jj-workspaces/SKILL.md
@@ -12,8 +12,6 @@ Create isolated jj workspaces for experimentation, parallel development, and sub
**Important:** Run `jj` (or `jj status`) periodically in each workspace. jj only snapshots the working copy when you run a command—it doesn't watch for file changes. Running `jj` ensures it sees your edits.
-**Note (v0.39+):** `jj workspace add` now links with relative paths by default, enabling workspaces to work inside containers or when moved together. Existing workspaces with absolute paths continue to work.
-
## When to Use
**Triggers:**
@@ -52,7 +50,7 @@ jj workspace update-stale
Use the paren-free `trunk` alias, not `trunk()` — Claude Code's shell
parser treats the parentheses as a subshell even when quoted and triggers
a permission prompt. Don't hardcode a bookmark instead; `trunk()` resolves
-differently per repo. See the `jj` skill's Common Pitfalls section.
+differently per repo. See "Revsets and filesets" in the `jj` skill's `pitfalls.md`.
**Result (with mm):** `trunk → workspace change → mm`
@@ -101,7 +99,7 @@ jj diff -r approach-a@ -r approach-b@
## Subagent Coordination
-For dispatching agents to work in parallel. **Execute setup BEFORE dispatching ANY agents.**
+For dispatching agents to work in parallel. Finish setup before dispatching any agent.
### Phase 1: Setup (Coordinator)
@@ -109,7 +107,7 @@ Create workspace(s) using the standard process above.
### Phase 2: Dispatch (Coordinator)
-Use Task tool to dispatch in parallel. **Start agents in the workspace directory** using the Task tool's working directory or by instructing the agent to `cd` first. Each agent gets:
+Dispatch subagents in parallel, and tell each one to `cd` into its workspace before anything else. Each agent gets:
- Task specification
- Workspace path (exactly one) - agent starts here
- Verification commands
@@ -118,7 +116,7 @@ Use Task tool to dispatch in parallel. **Start agents in the workspace directory
### Phase 3: Execution (Agent)
**Agent steps, in order:**
-1. `cd` into workspace directory first—all work happens FROM that directory
+1. `cd` into the workspace directory first; all work happens from there
2. Make file edits to implement task
3. Run verification (tests, type checks)
4. Split changes to parent: `jj split -m '<description>' .` (selects all files, creates parent commit with changes, leaves working copy empty)
@@ -157,12 +155,12 @@ rm -rf work/<name>
| Mistake | Fix |
|---------|-----|
-| Working from wrong directory | Agent must `cd` into workspace directory first—jj resolves its context from cwd, so all commands run FROM there |
+| Working from wrong directory | Agent must `cd` into workspace directory first—jj resolves its context from cwd, so all commands run from there |
| Skipping DAG placement | Must run `jj rebase` to place in DAG (with `-B mm` if megamerge exists) |
| Agent skipping split | Agent must run `jj split -m '<description>' .` to finalize changes |
| Skipping `jj workspace update-stale` | Run in main workspace after workspace operations |
-| Creating workspaces during dispatch | Create ALL workspaces BEFORE dispatch |
-| Agent touching other workspaces | Agents work ONLY in assigned path |
+| Creating workspaces during dispatch | Create every workspace before dispatch |
+| Agent touching other workspaces | Agents work only in their assigned path |
| Empty WC commits after rebase | After rebase + forget, run `jj abandon 'empty() & description(exact:"") & @-'` to drop the workspace's leftover empty WC |
| Forgetting cleanup | Remove directories after forgetting workspace |
| jj not seeing file changes | Run `jj` or `jj status` periodically—jj only snapshots on command execution |
diff --git a/ai/skills/jj/SKILL.md b/ai/skills/jj/SKILL.md
index 3340c3c1..92ed84d7 100644
--- a/ai/skills/jj/SKILL.md
+++ b/ai/skills/jj/SKILL.md
@@ -11,7 +11,7 @@ Verify behavior and flags against `jj <command> --help`, and read
catalogues flags that fail silently, hang without a TTY, or make a no-op look
like it worked.
-*This is a self-improving skill — see the `self-improving-skills` skill.*
+*This is a self-improving skill. If you used it and it came up short — a missing command, flag, gotcha, or workflow — invoke the `self-improving-skills` skill and follow it before you finish.*
Flags below are verified against jj 0.45.1 unless a line names another
version.
diff --git a/ai/skills/markdown/SKILL.md b/ai/skills/markdown/SKILL.md
index c8b53a58..05aee9e2 100644
--- a/ai/skills/markdown/SKILL.md
+++ b/ai/skills/markdown/SKILL.md
@@ -23,4 +23,4 @@ a separate link reference for the same source.
---
-*This is a self-improving skill — see the `self-improving-skills` skill.*
+*This is a self-improving skill. If you used it and it came up short — a missing command, flag, gotcha, or workflow — invoke the `self-improving-skills` skill and follow it before you finish.*
diff --git a/ai/skills/nvim-pack/SKILL.md b/ai/skills/nvim-pack/SKILL.md
index fbd7423c..fe8b4b3e 100644
--- a/ai/skills/nvim-pack/SKILL.md
+++ b/ai/skills/nvim-pack/SKILL.md
@@ -50,7 +50,7 @@ Located at `$XDG_CONFIG_HOME/nvim/nvim-pack-lock.json`. Tracks `rev`, `src`, and
**Unfreeze:** Change `version` back to a branch/tag/range. `:restart`.
-**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"})`.
+**Revert after update:** Restore the lockfile from VCS (`jj restore nvim-pack-lock.json`), then `:restart` and `:lua vim.pack.update(nil, {offline = true, target = "lockfile"})`.
**Cross-machine sync:** Commit the lockfile, pull on the other machine, `:restart`, then run `:lua vim.pack.update(nil, {target = "lockfile"})`.
diff --git a/ai/skills/pr/SKILL.md b/ai/skills/pr/SKILL.md
index 5c778a4f..c747f781 100644
--- a/ai/skills/pr/SKILL.md
+++ b/ai/skills/pr/SKILL.md
@@ -1,6 +1,6 @@
---
name: pr
-description: Use when the user asks to "create a pull request", "create a PR", "/pr", "open a PR", "submit for review", or "push and create PR"
+description: Use when opening a pull request for a jj revision, including pushing it first (/pr)
argument-hint: <revision> [ready|web]
allowed-tools: [Bash(jj diff *), Bash(jj log *), Bash(jj show *), Bash(jj bookmark list *)]
---
@@ -56,8 +56,7 @@ PR. Every `<revision>` below means the one you resolved here.
proceeding.
4. Check for .github PR templates and follow them. For checklist items that do
not apply, use strikethrough: `- ~~Irrelevant item~~`
-5. **Invoke the `technical-writing` skill** before drafting any prose. This is
- mandatory.
+5. Invoke the `technical-writing` skill before drafting any prose.
6. Generate a PR title summarizing all commits in the changeset (not just the
most recent). The title reflects the overall change, not individual commits.
7. Draft the PR summary: one to three sentences of prose on why the change
diff --git a/ai/skills/ruby-style/SKILL.md b/ai/skills/ruby-style/SKILL.md
index aeec9109..2eb676cb 100644
--- a/ai/skills/ruby-style/SKILL.md
+++ b/ai/skills/ruby-style/SKILL.md
@@ -337,4 +337,4 @@ end
---
-*This is a self-improving skill — see the `self-improving-skills` skill.*
+*This is a self-improving skill. If you used it and it came up short — a missing command, flag, gotcha, or workflow — invoke the `self-improving-skills` skill and follow it before you finish.*
diff --git a/ai/skills/rust/SKILL.md b/ai/skills/rust/SKILL.md
index 20e18956..36d9a598 100644
--- a/ai/skills/rust/SKILL.md
+++ b/ai/skills/rust/SKILL.md
@@ -9,7 +9,7 @@ Preferences for writing and shipping Rust. The actual guidance lives
in references — this file routes by task and lists the cross-cutting
principles that apply everywhere.
-*This is a self-improving skill — see the `self-improving-skills` skill.*
+*This is a self-improving skill. If you used it and it came up short — a missing command, flag, gotcha, or workflow — invoke the `self-improving-skills` skill and follow it before you finish.*
## When to read which reference
diff --git a/ai/skills/skill-notes/SKILL.md b/ai/skills/skill-notes/SKILL.md
index bf65d02e..05af76f1 100644
--- a/ai/skills/skill-notes/SKILL.md
+++ b/ai/skills/skill-notes/SKILL.md
@@ -7,7 +7,7 @@ description: Use when creating a new SKILL.md file, reviewing an existing skill
Supplementary notes on writing effective skills, accumulated from experience and external sources.
-*This is a self-improving skill — see the `self-improving-skills` skill.*
+*This is a self-improving skill. If you used it and it came up short — a missing command, flag, gotcha, or workflow — invoke the `self-improving-skills` skill and follow it before you finish.*
## Skill Categories
diff --git a/ai/skills/web-design/SKILL.md b/ai/skills/web-design/SKILL.md
index 353e49b1..53e79a84 100644
--- a/ai/skills/web-design/SKILL.md
+++ b/ai/skills/web-design/SKILL.md
@@ -72,4 +72,4 @@ References:
---
-*This is a self-improving skill — see the `self-improving-skills` skill.*
+*This is a self-improving skill. If you used it and it came up short — a missing command, flag, gotcha, or workflow — invoke the `self-improving-skills` skill and follow it before you finish.*
diff --git a/ai/skills/web-standards/SKILL.md b/ai/skills/web-standards/SKILL.md
index b99b616f..bcbcc4f0 100644
--- a/ai/skills/web-standards/SKILL.md
+++ b/ai/skills/web-standards/SKILL.md
@@ -140,4 +140,4 @@ moves in order.
---
-*This is a self-improving skill — see the `self-improving-skills` skill.*
+*This is a self-improving skill. If you used it and it came up short — a missing command, flag, gotcha, or workflow — invoke the `self-improving-skills` skill and follow it before you finish.*