Coding standards skill update: symlink as rules#9
Merged
Conversation
The skill now writes each new standard with a `paths:` YAML frontmatter
block and symlinks it from `.claude/rules/coding-standards/{name}.md`
into the canonical doc, instead of appending an enumerated entry to
CLAUDE.md. Claude Code loads each standard on demand when it reads a
file matching the glob, so standards no longer bloat session startup.
- SKILL.md: Step 3 discovers the project's primary file-type globs;
Step 6 proposes the per-standard `paths:` list, requires user
approval, and writes the frontmatter (preserving existing keys when
updating); Step 7 creates the relative symlink and only adds a
one-time pointer paragraph to CLAUDE.md/AGENTS.md if the memory file
doesn't already reference the rules folder; Step 10 verifies the
frontmatter, symlink, and the absence of new enumerated entries.
- template.md: prepends a `paths:` YAML frontmatter block.
- docs/skills/coding-standard.md: TL;DR, Key concepts, What you get
back, and the In-more-detail step summaries all reflect the new
integration, plus a Sources entry for the Claude Code memory docs.
Adds a "Why the canonical doc lives in docs/ and a symlink lives in .claude/rules/" section to the /coding-standard operator doc so readers understand: one file with two access paths (not two copies), why .claude/ is not the human-readable home, why the symlink + paths: model is preferable to a CLAUDE.md enumeration, and exactly what the skill will and will not touch in the memory file. Also: - SKILL.md Project Context: switch the rules-directory check to the single-command, no-chaining find pattern used by the rest of the plugin (`find . -maxdepth 4 -type d -path "*/.claude/rules/...`), removing the 2>/dev/null and || echo idioms that violate the skill's own documented context-injection rules. - context-injection-commands.md: register the new AGENTS.md and .claude/rules/coding-standards/ find commands against /coding-standard so the canonical list of injected commands stays accurate.
The In-more-detail section had been showing a nine-step process and labeling the adversarial review as Step 8, but the SKILL has carried a separate Adoption-Bias Audit at Step 8 since v2.3, with adversarial review at Step 9 and verification at Step 10. Realign the operator doc to the ten-step structure, add a one-line description of the adoption-bias audit, and update the Cost and latency note to point at Step 9 (not Step 8) for the junior-developer + information-architect dispatch.
Every skill-building and agent-building guidance doc now carries `paths:` YAML frontmatter scoping it to the files the guidance is actually about, and is symlinked into `.claude/rules/skills/` or `.claude/rules/agents/` so Claude Code loads the relevant guidance only when a contributor edits a skill or an agent file in this repo. - Skill-building guidance (23 docs) scopes to `plugin/skills/**/*.md`. Script-related guidance (script-execution-instructions, graceful-degradation) additionally scopes to `plugin/skills/**/scripts/**` so it loads when shell scripts are edited too. - Agent-building guidance (5 docs) scopes to `plugin/agents/**/*.md`. - The plugin-entity taxonomy is symlinked at `.claude/rules/plugin-entity-taxonomy.md` with no `paths:` field, so it loads at every session start. This is intentional: deciding whether something is a skill, an agent, or a hook is a precondition for every other contributor question, so it's worth the always-on cost. Canonical docs stay in `docs/guidance/` where humans browse them. The symlinks in `.claude/rules/` give Claude Code a second access path without duplicating content.
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 exposes the plugin's contributor guidance as path-scoped Claude Code rules, so that authoring rules load automatically into context only when an agent edits the plugin file they govern — instead of relying on humans to remember them.
paths:YAML frontmatter block and a matching symlink under.claude/rules/. Claude Code's path-scoped rules feature loads a rule into context only when a file matching one of its globs is read (load_reason: path_glob_match), so editingplugin/skills/foo/SKILL.mdnow auto-loads all skill-building guidance, and editingplugin/agents/bar.mdauto-loads agent-building guidance. No change at session startup; nothing loads until a matching file is touched./coding-standardskill was rewritten so the standards it produces use the same mechanism: every new standard now carriespaths:frontmatter and is symlinked into.claude/rules/coding-standards/, replacing the old approach of adding an enumerated link toCLAUDE.md. The skill grew from 9 to 10 steps and gained an Adoption-Bias Audit step./coding-standardskill writes its output — there is nothing for a human to invoke differently.paths:glob scoping (broadplugin/skills/**/*.mdvs. narrower second globs) and to the backward-compatibility promise that the rewritten skill leaves pre-existing enumeratedCLAUDE.mdentries untouched.Behavior changes
Two distinct behavioral changes, both about loading and authoring guidance, not product runtime:
docs/guidance/)paths:glob and a symlink under.claude/rules/. Claude Code auto-loads the doc into context when any file matching the glob is read. Skill-building docs scope to"plugin/skills/**/*.md"; agent-building docs and the entity taxonomy scope to"plugin/agents/**/*.md". Two skill docs (graceful-degradation.md,script-execution-instructions.md) add a second glob"plugin/skills/**/scripts/**"so they also load when scripts are touched./coding-standardskill outputdocs/coding-standards/, then added an enumerated link toCLAUDE.md/AGENTS.md. That link loaded on every session whether relevant or not.paths:frontmatter into the standard, then creates a relative symlink at.claude/rules/coding-standards/{filename}pointing back to the canonical doc. Adds a one-time pointer paragraph to the memory file only if it does not already reference.claude/rules/coding-standards/. Never adds a new enumerated entry; pre-existing enumerated entries from earlier skill versions are deliberately left alone (migrating them out is explicitly out of scope).The canonical doc still lives in
docs/; the.claude/rules/entry is a relative symlink to it, so there is one file with two access paths and no duplication/drift.What to look at first
"plugin/skills/**/*.md"glob, which means editing any single SKILL.md pulls all ~24 skill-building docs into context at once. Worth deciding whether that is the intended tradeoff (complete guidance vs. context size) or whether narrower scoping was considered and rejected.scripts/**glob.graceful-degradation.mdandscript-execution-instructions.mdadd"plugin/skills/**/scripts/**". Confirm that pairing is deliberate and that other script-relevant docs (e.g.,hardening-fuzzy-vs-deterministic.md) were intentionally not given it.coding-standard/SKILL.mdclaim the skill will not touch pre-existing enumeratedCLAUDE.mdentries and only adds a pointer paragraph if one is absent. This is the main behavioral risk surface — verify the conditional logic actually distinguishes "pointer paragraph exists" from "enumerated entry exists."../depth (../../../docs/...for skills/agents,../../docs/...for the top-level taxonomy). The skill instructs adjusting depth when the docs directory is nested differently — check whether that instruction is clear enough to apply correctly in a project whose docs tree differs from this repo's.Files of interest
plugin/skills/coding-standard/SKILL.md— the substantive rewrite: newallowed-tools(ln,test,readlink), glob discovery in Step 3,paths:frontmatter authoring in Step 6, symlink-based integration in Step 7, new Adoption-Bias Audit in Step 8.docs/skills/coding-standard.md— operator-facing explanation, including the new "Why the canonical doc lives indocs/and a symlink lives in.claude/rules/" section that justifies symlink-over-enumerated-link.plugin/...coding-standard/references/template.md— gained thepaths:frontmatter block standards are now generated with.docs/...building-guidance/graceful-degradation.md— representative of the 30 frontmatter additions, and one of the two docs carrying the extrascripts/**glob..claude/rules/skills/context-hygiene.md— representative symlink; confirms the relative-target convention back intodocs/guidance/.