refactor(agents): extract AGENTS.md subsystem gotchas into repo-local skills#109
Merged
Conversation
ADR-0003 plus an implementation spec for moving the situational platform/app-specific sections of the root AGENTS.md (Finicky, Hammerspoon, Komorebi, Rancher Desktop, Windows support, mise-on-Windows) into five repo-local skills under .agents/skills/, keeping core chezmoi knowledge and cross-platform mechanics inline. Decision reached via two independent consensus panels (seeded + unseeded), both unanimous. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…section Remove the inline ## Windows support, ## Finicky, ## Hammerspoon, ## Rancher Desktop, ## Komorebi, and ## mise on Windows sections now covered by repo-local skills; add compact skill-pointer bullets in Repo-specific conventions and a meta-rule entry for the new pattern. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- swap em-dash separator for a colon in all five new SKILL.md descriptions (repo bans em dashes) - add 'macOS' trigger term to the finicky skill description - name run_onchange_after_bootstrap_windows.ps1.tmpl explicitly in the windows-internals scope and AGENTS.md pointer (shared with mise-on-windows) - fix an em dash in the windows-internals scope line Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The implementation plan and design spec were execution artifacts; the work is done and ADR-0003 captures the decision and consequences. Remove the dangling spec reference from the ADR. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
main reworked the hammerspoon config after this branch was cut (Ctrl->Option keybinds, added space_indicator.lua menu-bar badge, mru-spaces position stability via run_onchange_after_macos_defaults.sh.tmpl). The extracted skill captured the old Ctrl/2-file version; resync it to main's current content so the rebase doesn't silently drop that work. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
ChipWolf
force-pushed
the
refactor/extract-subsystem-skills
branch
from
June 15, 2026 17:40
4dc42ea to
47b5d6d
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
The repo-root
AGENTS.mdhad grown to 269 lines, past its own meta-rule's ~200-line "propose splitting" ceiling, and ~83 of those lines (~31%) were situational, platform/app-specific subsystem gotchas paid for as always-on context in every session in this repo. This moves them into on-demand repo-local skills..agents/skills/:finicky,hammerspoon(macOS)komorebi,mise-on-windows,windows-internals(Windows;windows-internalsbundles Rancher Desktop + WSL + ssh-tpm-agent + dual-gpg + WezTerm + bootstrap/elevation)Load .agents/skills/<name>/SKILL.md before changing <globs>pointer in the Repo-specific conventions block, matching the existinghomebrew-management/update-*convention..agents/is outside the chezmoi source state (.chezmoiroot=home), so this has zerochezmoi applyimpact — it's read-in-place repo tooling, like the existing repo-local skills.Why / how it was decided
Decided via two independent
consensus-skill panels (one seeded with options, one unseeded); both converged with no dissent on per-subsystem extraction. Rationale, options considered, and consequences are recorded in ADR-0003 (the canonical record for this change).Notable refinements beyond a naive cut:
## Windows supportsection is split, not moved wholesale. Cross-platform OS-gating mechanics (.chezmoiignoreconditionals, the bash/PowerShell chezmoiscript OS-guard rule, the new-config decision rule) fire on any new-file edit and stay inline in conventions; only Windows-operational internals move to the skill.conditionsgate, not Windows behaviour; keeping it in a Windows skill would hide it from macOS/Linux sessions. Already covered by the condition-gate concept + the MCP/permission skills.Test plan
No code test suite (chezmoi dotfiles repo). Verified:
##headings removed from AGENTS.md; five pointers present.chezmoisource state still renders; repo-root.agents/is not a managed target (no apply impact).Post-review changes
A two-axis
/review(standards + spec) ran on the branch. Fixes applied as follow-up commits: swapped em-dash separators for colons in the five new skill descriptions (repo bans em dashes), added themacOStrigger term to finicky, and named the sharedrun_onchange_after_bootstrap_windows.ps1.tmplexplicitly in thewindows-internalspointer. The implementation plan and design spec were dropped — they were execution artifacts; ADR-0003 is the canonical record.Known follow-up (out of scope): a repo-wide em-dash sweep — AGENTS.md and several skill bodies (including the pre-existing
update-*skills) carry em dashes in prose that predate this PR.🤖 Generated with Claude Code