5c0402736e
Two structural changes:
1. Generalize CLAUDE.md-specific guidance:
- "Project-specific conventions (put in CLAUDE.md)" → "(put in
your instructions file)" in writing-skills/SKILL.md
- "(explicit CLAUDE.md violation)" → "(explicit instruction-file
violation)" in receiving-code-review/SKILL.md
- The instruction-priority list in using-superpowers/SKILL.md
stays inclusive (CLAUDE.md, GEMINI.md, AGENTS.md) — that's
load-bearing, not a substitution opportunity.
2. Per-platform tool reference files at skills/using-superpowers/
references/{claude-code,codex,copilot,gemini}-tools.md. Each ref
documents:
- The runtime's preferred instructions file (CLAUDE.md, AGENTS.md,
GEMINI.md, etc.) and how it loads
- The runtime's personal-skills directory + cross-runtime
~/.agents/skills/ path where applicable
- Action-language → tool-name mapping table
Tool names and table content reflect the source-verified state from
direct inspection of openai/codex, google-gemini/gemini-cli,
sst/opencode, and the installed @github/copilot package. Filenames
and behaviors are sourced from each runtime's official docs.
Files in this commit also pick up later-phase changes that
accumulated on the same files (using-superpowers/SKILL.md "How to
Access Skills" overhaul, action-language flowchart, refs' final
table content). The bundled spec records original scope.
4.8 KiB
Platform-neutral config-file references — Phase B design
Background
Phase A (see 2026-05-05-platform-neutral-prose-design.md) replaced generic third-person "Claude" prose with agent-neutral forms. This phase tackles the next category: references to the per-platform instruction file (CLAUDE.md, AGENTS.md, GEMINI.md) inside skills.
The plugin runs on multiple harnesses, and each one reads its own instruction file. Where a skill names CLAUDE.md as if it were the only file, that's a Claude-Code-centric assumption that doesn't hold on Codex / Gemini CLI / OpenCode.
In scope
Two specific lines in active skills:
skills/writing-skills/SKILL.md:58—Project-specific conventions (put in CLAUDE.md)skills/receiving-code-review/SKILL.md:30—"You're absolutely right!" (explicit CLAUDE.md violation)
Out of scope
skills/using-superpowers/SKILL.md:22, 26— instruction-priority list. The list already names all three (CLAUDE.md, GEMINI.md, AGENTS.md) inclusively, which is correct: the section is making a real claim about what counts as user instruction on a multi-platform plugin. No change needed.- Historical / example artifacts:
skills/systematic-debugging/CREATION-LOG.md— attribution path (~/.claude/CLAUDE.md) is a historical fact.skills/writing-skills/examples/CLAUDE_MD_TESTING.md— the entire file is a worked example testing CLAUDE.md content variants. The filename, body, and the reference fromtesting-skills-with-subagents.mdall stay; normalizing them defeats the example.
- Platform-tooling references — Phase D candidates:
skills/using-superpowers/SKILL.md:40(Gemini CLI tool mapping note about GEMINI.md)skills/using-superpowers/references/gemini-tools.md(save_memorypersists to GEMINI.md)
Substitution rules
Two distinct calls, one per in-scope line.
Rule 1: "where to put project-specific conventions"
writing-skills/SKILL.md:58:
- Before:
Project-specific conventions (put in CLAUDE.md) - After:
Project-specific conventions (put in your instructions file)
Use a generic phrase rather than picking one filename. Different harnesses read different files (CLAUDE.md, AGENTS.md, GEMINI.md, etc.) and the skill should not assume one. The platform-tools reference docs (references/{codex,copilot,gemini}-tools.md) are the right place to name each platform's preferred file.
Rule 2: the "(explicit CLAUDE.md violation)" parenthetical
receiving-code-review/SKILL.md:30:
- Before:
"You're absolutely right!" (explicit CLAUDE.md violation) - After:
"You're absolutely right!" (explicit instruction-file violation)
The parenthetical is doing real work — it signals this phrase isn't just stylistically bad, it actively violates rules many users put in their instruction files. "Instruction file" is the natural cross-platform term covering AGENTS.md / CLAUDE.md / GEMINI.md collectively, and keeps the original signal without picking one filename or softening to "common".
Commit plan
Atomic commits, in order:
writing-skills/SKILL.md— CLAUDE.md → "your instructions file" in the "where to put project conventions" linereceiving-code-review/SKILL.md— CLAUDE.md → instruction-file in the violation parenthetical- Platform-tools reference docs — add the preferred per-platform instructions filename (CLAUDE.md, AGENTS.md, GEMINI.md, etc.) to each
references/{codex,copilot,gemini}-tools.mdso readers can resolve "your instructions file" to a real filename.
Each commit message names "Phase B" and the slice.
Verification
After each commit:
- Read the surrounding paragraph to confirm grammar and meaning still parse.
grep -n "CLAUDE\.md" <touched-file>— no remaining hits in active prose (carve-outs already documented).
After both commits:
grep -rn "CLAUDE\.md" skills/should return only the documented carve-outs (CREATION-LOG, CLAUDE_MD_TESTING and its inbound reference, the priority list in using-superpowers).
Non-goals
- Do not touch the priority list ordering in
using-superpowers/SKILL.md. Reordering CLAUDE.md / GEMINI.md / AGENTS.md is an aesthetic change, not a substitution, and out of scope here. - Do not rename
examples/CLAUDE_MD_TESTING.mdor change its content. - Do not modify Gemini-CLI-specific tooling references (Phase D candidates).
Implementation note
Phase B as written here covered three commits and the three non-Claude-Code platform-tools refs. Implementation went one step further: a fourth ref, references/claude-code-tools.md, was added in commit 8505703 for symmetry, so Claude Code's instructions-file conventions and tool-name list live alongside the others rather than implicitly in the surrounding skill prose. That addition wasn't anticipated in this spec but is consistent with its intent.