Skip to content

Spec mandates @ references in the Phase Files table; every template and example uses backticked paths - #7

Merged
TGPSKI merged 1 commit into
mainfrom
fix/issue-6-spec-mandates-references-in-the-phase-files
Aug 9, 2026
Merged

TGPSKI merged 1 commit into
mainfrom
fix/issue-6-spec-mandates-references-in-the-phase-files

Conversation

@TGPSKI

@TGPSKI TGPSKI commented Aug 9, 2026

Copy link
Copy Markdown
Owner

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". Matches templates/multi-phase-router/router.md:83-88 and 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.md is 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

@path is a CLAUDE.md-family import mechanism — imported files expand into context at launch, recursive to four hops — not a markdown convention. SKILL.md is 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:

  1. An agent reads @ as "load this now" and pulls every phase file at router time, defeating the progressive disclosure the router exists to provide.
  2. If a router's text reaches a CLAUDE.md through the documented @AGENTS.md import 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

SKILL.md and CONTRIBUTING.md describe the convention the templates and all four examples already use.

Met. SKILL.md:148 now says "backticked relative paths, one level deep from the router", matching templates/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:72 no longer asks reviewers to verify references that do not exist.

No template or example file changes — they are already correct. A diff that touches templates/ or examples/ means the fix went the wrong direction.

Met. git diff --name-only returns exactly CONTRIBUTING.md, README.md, SKILL.md. git diff --name-only -- templates/ examples/ is empty.

README.md prompt-invocation syntax is unchanged.

Met. README.md:6 (User: @onboard-service/SKILL.md) is untouched. README.md:67 keeps `@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 plus examples/contributor-access/grant-access/references/phase-02-access.md:95 (@{github-username}, unrelated mechanism), all expected.

Closes #6

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
TGPSKI merged commit 79a64a0 into main Aug 9, 2026
2 checks passed
@TGPSKI
TGPSKI deleted the fix/issue-6-spec-mandates-references-in-the-phase-files branch August 9, 2026 09:34
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Spec mandates @ references in the Phase Files table; every template and example uses backticked paths

1 participant