Spec mandates @ references in the Phase Files table; every template and example uses backticked paths - #7
Merged
TGPSKI merged 1 commit intoAug 9, 2026
Conversation
SKILL.md:148 required the Phase Files table to use `@` references, and CONTRIBUTING.md:72 told reviewers to check that `@`-references resolve. No template or example in the repo does this -- templates/multi-phase-router/ router.md:83-88 and all four examples list phases as backticked relative paths under references/. `@path` is a CLAUDE.md-family import mechanism that expands files into context at launch, not a markdown convention. SKILL.md is not a memory file, so `@` there is inert text. Following the spec literally would produce routers that either disagree with the template, or -- if the router text reaches a CLAUDE.md through an @AGENTS.md import -- load every phase file at launch, defeating the progressive disclosure the router pattern exists to provide. - SKILL.md:148 now states the convention the templates already use - SKILL.md Router Rules gains a rule that the router names the phase file and instructs the agent to read it; the read is the load - CONTRIBUTING.md:72 checks internal links, not `@`-references - README.md:67 notes that `@onboard-chart/SKILL.md` is a prompt mention, a different mechanism from a router's phase file references No template or example changed -- they were already correct. Closes #6
TGPSKI
deleted the
fix/issue-6-spec-mandates-references-in-the-phase-files
branch
August 9, 2026 09:34
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.
What changed
Two spec lines required a convention no template, example, or pattern doc in this repo follows.
SKILL.md:148— "lists all phases with@references" → "lists all phases as backticked relative paths, one level deep from the router". Matchestemplates/multi-phase-router/router.md:83-88and all four examples.SKILL.md### Router Rules— new rule: the router names the phase file by relative path and instructs the agent to read it. The read is the load; a bare path is not a directive to load anything.CONTRIBUTING.md:72— "all internal@-references resolve to existing files" → "all internal links resolve to existing files".README.md:67— notes that@onboard-chart/SKILL.mdis a prompt mention that attaches the router to the conversation, distinct from how a router references its phase files. Prevents the next reader from "fixing" it.Why
@pathis a CLAUDE.md-family import mechanism — imported files expand into context at launch, recursive to four hops — not a markdown convention.SKILL.mdis not a memory file, so@there is inert text: a path with a decorative sigil. Import parsing also skips code spans, so the spec's own backticked`@`would not import anything even in a CLAUDE.md.Two failure modes if the spec were followed literally:
@as "load this now" and pulls every phase file at router time, defeating the progressive disclosure the router exists to provide.CLAUDE.mdthrough the documented@AGENTS.mdimport pattern, the phase files genuinely expand at launch.Anthropic's skill-authoring guidance uses plain markdown links for bundled files and says to keep references one level deep from
SKILL.md— the router →references/shape this repo already uses. No AGENTS.md-family spec defines an import syntax, and Cursor's@is a chat-composer mention with different resolution rules.Acceptance
Met.
SKILL.md:148now says "backticked relative paths, one level deep from the router", matchingtemplates/multi-phase-router/router.md:83-88,examples/kubernetes-onboarding/onboard-service/SKILL.md:74-79, and the terraform-aws-account, ansible-inventory, and contributor-access examples.CONTRIBUTING.md:72no longer asks reviewers to verify references that do not exist.Met.
git diff --name-onlyreturns exactlyCONTRIBUTING.md,README.md,SKILL.md.git diff --name-only -- templates/ examples/is empty.Met.
README.md:6(User: @onboard-service/SKILL.md) is untouched.README.md:67keeps`@onboard-chart/SKILL.md`verbatim; only explanatory prose was appended.Remaining
@file-references after the change, per the issue's grep — the two README invocations plusexamples/contributor-access/grant-access/references/phase-02-access.md:95(@{github-username}, unrelated mechanism), all expected.Closes #6