Updating skill / agent rules to be index files#15
Merged
Conversation
Replace the 23 one-symlink-per-doc entries under .claude/rules/skills/ with a single .claude/rules/skill-building-guidance.md index file. The index carries paths: "plugin/skills/**/*.md" so it loads only when a skill file is being read, and lists every guidance doc with a 1-3 sentence description so Claude can pick the relevant subset to open on demand instead of loading all 23 docs at once. This mirrors the per-file-type index-file pattern that /coding-standard now uses for coding standards.
Replace the 5 one-symlink-per-doc entries under .claude/rules/agents/ with a single .claude/rules/agent-building-guidelines.md index file. The index carries paths: "plugin/agents/**/*.md" so it loads only when an agent file is being read, and lists every guidance doc with a 1-3 sentence description so Claude can pick the relevant subset to open on demand instead of loading all 5 docs at once. Matches the layout introduced in the previous commit for skill-building guidance.
Move .claude/rules/skill-building-guidance.md to its canonical location under .claude/rules/coding-standards/plugin-skills.md, and use the template's verbatim instruction paragraph and "## Available standards" section heading. The previous file paraphrased the template (saying "guidance" / "## Available guidance" instead of "standard" / "## Available standards"), which violated Step 7.3 and Step 10.4 of the coding-standard skill, both of which require the instruction paragraph to be unchanged from the template. Entries are sorted alphabetically by title.
mxriverlynn
force-pushed
the
rules-as-index-files
branch
from
1340e64 to
dbe6893
Compare
Move .claude/rules/agent-building-guidelines.md to its canonical location under .claude/rules/coding-standards/plugin-agents.md, and use the template's verbatim instruction paragraph and "## Available standards" section heading. Matches the realignment applied in the previous commit for the plugin-skills index. Entries are sorted alphabetically by title.
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
This PR replaces 27 per-rule symlinks with 2 path-scoped index files, so that Claude loads only the rule files it actually needs instead of paying the full token cost of every matching standard.
.claude/rules/mechanism from "load every matching standard in full" to "load a short index, then selectively open standards by name" — the progressive-disclosure pattern applied to rule loading itself.docs/guidance/agent-building-guidelines/anddocs/guidance/skill-building-guidance/. Nothing underplugin/ordocs/changes.plugin/agents/**/*.md, and skill rules now fire onplugin/skills/**/*.mdplusplugin/skills/**/scripts/**(previously each symlink carried its own scope).Behavior changes
Before: opening any file that matched a rule's path glob caused Claude Code to load the full text of every matching standard. For a skill edit, that meant up to 22 standards loaded in full whether relevant or not.
After: opening a matching file loads one short index file (40 lines for agents, 59 lines for skills). The index tells Claude it is an index rather than a standard, lists the available standards with one-line descriptions, and instructs Claude to Read only the standards clearly relevant to the current task — possibly none.
plugin/agents/**/*.mdplugin-agents.mdindex onlyplugin/skills/**/*.mdorplugin/skills/**/scripts/**plugin-skills.mdindex onlyWhat to look at first
plugin/skills/**/scripts/**, which the prior symlink layout may not have covered uniformly — check that this matches intent..claude/rules/coding-standards/rather than keepingagents/andskills/subdirectories. The new names (plugin-agents.md,plugin-skills.md) imply this convention will extend to other index files later.Files of interest
.claude/rules/coding-standards/plugin-skills.md— new skills index; 22 standards listed, scoped to skill SKILL.md files and skill scripts..claude/rules/coding-standards/plugin-agents.md— new agents index; 5 standards listed, scoped to agent definition files.