Affected files:
skills/prompt-optimizer/references/core-patterns.md ("Layer the prompt correctly")skills/prompt-optimizer/SKILL.md (Step 3, the "Separate durable behavior from task-local context" bullet)
What's missing
The skill's layering model is:
- Stable behavior (role, defaults, safety, tool-use policy, output contract)
- Task-local context (user request, retrieved docs, current state, dynamic variables)
- Examples
That split assumes a single author owns the entire system prompt. It doesn't address a pattern we hit in practice: the system prompt is composed at runtime from two layers with different owners:
- Platform layer — owned by the product/framework team; carries behavior rules, output contract, tool policy.
- Deployment/persona layer — owned by the downstream deployer (e.g., a
SOUL.md file a customer checks into their own repo); carries voice, identity, domain framing.
Both end up concatenated into the system prompt, but only the platform layer is reliable across installs. A deployment might ship a 5-line persona file or a detailed one. The platform code cannot assume deployer-authored files contain anything load-bearing.
Concrete example from the field
We refactored a harness prompt and briefly considered deleting behavior bullets ("gather evidence before answering", "never claim tools are unavailable") on the theory that a deployer's personality file would cover them. Verified by reading the repo's actual persona file — it was five lines of voice/tone, no behavior rules. Deleting those bullets would have dropped them entirely in production deployments.
Suggested fix
Add a short "Layered prompts with multiple owners" subsection to core-patterns.md with this invariant:
- If part of the system prompt is authored by a downstream deployer (persona files, brand guidelines, identity files), treat that layer as voice-only.
- All platform-level behavior rules — evidence gathering, tool-use policy, narration rules, output contract, escalation boundaries — must live in the platform-owned layer and never depend on the deployer layer.
- Every platform behavior rule must survive independent of what the deployer layer contains.
Touch SKILL.md Step 3 as well to point at this subsection when the target is a layered runtime.
Why it matters
The existing "keep one authoritative owner per rule" advice is right for single-author prompts but ambiguous for layered ones. Platform teams drift toward "the persona file will cover tone, so I don't need to" — which silently breaks for deployments whose persona file is sparse or customized.
Affected files:
skills/prompt-optimizer/references/core-patterns.md("Layer the prompt correctly")skills/prompt-optimizer/SKILL.md(Step 3, the "Separate durable behavior from task-local context" bullet)What's missing
The skill's layering model is:
That split assumes a single author owns the entire system prompt. It doesn't address a pattern we hit in practice: the system prompt is composed at runtime from two layers with different owners:
SOUL.mdfile a customer checks into their own repo); carries voice, identity, domain framing.Both end up concatenated into the system prompt, but only the platform layer is reliable across installs. A deployment might ship a 5-line persona file or a detailed one. The platform code cannot assume deployer-authored files contain anything load-bearing.
Concrete example from the field
We refactored a harness prompt and briefly considered deleting behavior bullets ("gather evidence before answering", "never claim tools are unavailable") on the theory that a deployer's personality file would cover them. Verified by reading the repo's actual persona file — it was five lines of voice/tone, no behavior rules. Deleting those bullets would have dropped them entirely in production deployments.
Suggested fix
Add a short "Layered prompts with multiple owners" subsection to
core-patterns.mdwith this invariant:Touch SKILL.md Step 3 as well to point at this subsection when the target is a layered runtime.
Why it matters
The existing "keep one authoritative owner per rule" advice is right for single-author prompts but ambiguous for layered ones. Platform teams drift toward "the persona file will cover tone, so I don't need to" — which silently breaks for deployments whose persona file is sparse or customized.