fix(create-agent-skills): remove literal dynamic context directives that break skill loading

[kirvahe]

Problem

The create-agent-skills skill fails to load via the Skill tool with:

Bash command failed for pattern "!`command`": (eval):1: redirection with no command

Root cause

The SKILL.md file contained literal !command dynamic context injection directives as documentation examples (lines 100, 111–112). Claude Code's preprocessor scans the **entire** SKILL.md as plain text before sending it to the model — it does not parse markdown. Fenced code blocks (` ```yaml `) and inline code spans ( ) offer no protection from execution.

When loading this skill, the preprocessor attempted to execute three directives:

1. !`command` → shell error (command is not a valid command)
2. !`gh pr diff` → fails outside a PR context
3. !`gh pr diff --name-only` → same

This caused the skill to fail on every invocation, forcing Claude to fall back to manually reading the SKILL.md file — losing the benefits of skill-based loading.

Upstream references

• anthropics/claude-code#27149 — "Preprocessor executes !command`` directives inside markdown code spans" (closed, wontfix). Resolution: "The double backtick escaping was broken, so the content was never actually inside a code span. The preprocessor was correctly executing bare text. Workaround: describe the syntax in prose instead of using the literal syntax."
• anthropics/claude-code#28024 — duplicate, closed

Fix

1. Replaced the literal directives with a prose description of the dynamic context injection syntax
2. Added a warning explaining the preprocessor behavior (plain-text scanning, no markdown awareness)
3. Linked to references/official-spec.md § "Dynamic Context Injection" for the concrete example — reference files are loaded on-demand by Claude via the Read tool and are not preprocessed at skill load time

Why reference files are safe

When Claude encounters a link like [official-spec.md](references/official-spec.md) in a skill, it reads that file on-demand using the Read tool. The preprocessor only processes the top-level SKILL.md content. This makes reference files the correct place for documentation that includes literal dynamic context directives.

Scope

• 1 file changed: plugins/compound-engineering/skills/create-agent-skills/SKILL.md
• No logic changes — purely documentation
• No reference files modified — official-spec.md already contains a safe concrete example
• Net effect: −14 lines (removed literal examples), +3 lines (prose description + warning + link)

Test plan

• Invoke /compound-engineering:create-agent-skills via the Skill tool — should load without errors
• Verify the "Dynamic Context Injection" section reads clearly and links to the reference
• Confirm no other SKILL.md files in the plugin contain literal !command`` directives: grep -rl '!\x60' plugins/*/skills/*/SKILL.md should return empty

🤖 Generated with Claude Code