docs(claude): split CLAUDE.md sections into focused skills#243
Merged
demandal25 merged 4 commits intoMay 28, 2026
Conversation
Move conditional-use guidance out of the always-loaded CLAUDE.md and into on-demand skills, so PR/`gh` workflow advice and external tuning references only enter context when the relevant skill is invoked. ### What changed - **`CLAUDE.md`** — drop the `GitHub CLI`, `PR Description`, and `Key External References` sections (now lived in skills); collapse the `Installing Torch` blurb into a one-line pointer to the README table; shrink "Arch ↔ codename" to a one-liner. Net: 4.6 KB → 2.8 KB. - **`.claude/skills/pr-workflow/SKILL.md`** (new) — holds the `gh api repos/ROCm/flashinfer/pulls/...` workaround for the `gh pr edit` GraphQL failure and the project's PR-description template. - **`.claude/skills/benchmark-kernel/SKILL.md`** — appends an "External tuning references" section (CK as ground truth for LDS/scheduling, AITER as fp16/hdim=256 perf reference, HipKittens 4-wave-interleave guidance). These are tuning-time references, naturally co-located with the benchmarking guide. - **`.gitignore`** — ignore `.claude/settings.local.json` so per-developer Claude Code overrides don't get committed. ### Why `CLAUDE.md` loads into every prompt; skills load only on invocation. External tuning references and PR-edit quirks are useful only in specific workflows, so they belong in skills. ## Test plan - [x] `git diff` reviewed — only doc/skill files touched - [x] `pre-commit run -a` clean
There was a problem hiding this comment.
Pull request overview
Refactors the always-loaded CLAUDE.md to be shorter by moving workflow- and tuning-specific guidance into focused Claude Code skills, so that only relevant guidance is loaded when a skill is invoked.
Changes:
- Trim
CLAUDE.mdby replacing verbose sections with pointers to README and skill docs. - Add a new
pr-workflowskill containingghPR-edit workarounds and the PR description template. - Extend the existing
benchmark-kernelskill with external tuning reference links; ignore local Claude settings via.gitignore.
Reviewed changes
Copilot reviewed 3 out of 4 changed files in this pull request and generated 2 comments.
| File | Description |
|---|---|
CLAUDE.md |
Removes always-loaded workflow/tuning sections; adds concise pointers and keeps a short arch mapping note. |
.gitignore |
Ignores .claude/settings.local.json to prevent committing per-developer Claude overrides. |
.claude/skills/pr-workflow/SKILL.md |
New skill for PR creation/edit guidance and PR body conventions. |
.claude/skills/benchmark-kernel/SKILL.md |
Adds “External tuning references” section for perf iteration. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
- CLAUDE.md: fix gfx950 codename — MI350X → MI355X (matches README.md line 80 and CONTRIBUTING.md line 5). - pr-workflow/SKILL.md: disambiguate naming — the GitHub repo is `ROCm/flashinfer`; `amd-flashinfer` is the Python package name. Title, description, and intro note all clarified so the `gh api` commands no longer look inconsistent with the skill's framing.
Move the ~100-line plan-mode review prompt out of CLAUDE.md into a new .claude/skills/plan-review/SKILL.md so it loads on-demand rather than on every prompt. Same motivation as the pr-workflow / benchmark-kernel splits in this PR: keep CLAUDE.md focused on always-relevant guidance. While moving the prompt, replace the non-existent `AskBeforeAction` tool reference with the real `AskUserQuestion` tool so the skill is actionable as written. Model Usage Policy stays in CLAUDE.md — short and broadly applicable. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Replace ambiguous "Ask to push to remote." with a concrete instruction spelling out who should ask whom and which commands trigger it (git push, gh pr create). Addresses Copilot review comment on PR ROCm#243. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
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
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
Split conditional-use guidance out of the always-loaded
CLAUDE.mdinto focused Claude Code skills, so PR/ghworkflow advice, external tuning references, and the interactive plan-review prompt only enter the model's context when the relevant skill is invoked. Net:CLAUDE.mdshrinks ~60% (4.6 KB → ~1.8 KB), and per-developer Claude settings are now ignored from git.What changed
CLAUDE.md— drop theGitHub CLI,PR Description, andKey External Referencessections (now live in skills); move the ~100-line plan-mode review prompt into aplan-reviewskill; collapse theInstalling Torchblurb into a one-line pointer to the README table; shrink the Arch ↔ codename note to one line. The short Model Usage Policy stays inCLAUDE.md(broadly applicable, low cost)..claude/skills/pr-workflow/SKILL.md(new) — holds thegh api repos/ROCm/flashinfer/pulls/...workaround for thegh pr editGraphQL failure and the project's PR-description template..claude/skills/plan-review/SKILL.md(new) — interactive plan-mode review workflow: engineering preferences, the four review stages (Architecture / Code Quality / Tests / Performance), the per-issue option format, and the BIG/SMALL CHANGE interaction model. While moving, the non-existentAskBeforeActiontool reference was replaced with the realAskUserQuestiontool so the skill is actionable as written..claude/skills/benchmark-kernel/SKILL.md— appends an External tuning references section (CK as the ground truth for LDS/scheduling, AITER as fp16/hdim=256 perf reference, HipKittens 4-wave-interleave guidance). These are tuning-time references, naturally co-located with the benchmarking guide..gitignore— ignore.claude/settings.local.jsonso per-developer Claude Code overrides aren't committed.Design notes
CLAUDE.mdloads into every prompt while skills load only on invocation. External tuning references, PR-edit quirks, and the plan-mode review template are all conditional-use, so they belong in skills.benchmark-kernel(notadd-rocm-kernel) because they're consulted during perf iteration, not initial scaffolding.AskBeforeAction→AskUserQuestionsubstitution (real Claude Code tool name).Test plan
git diffreviewed — only doc/skill files touchedpre-commit run --filesclean on every commit (markdownlint, trailing whitespace, line endings)CLAUDE.mdand the three skills verified.claude/settings.local.jsonconfirmed ignored (git check-ignore)