# Context Engineering Every agent run receives a prompt assembled from operator-controlled files. Agents, skills, and protocols are separate files so any combination can be assembled without copying. ## The four layers | File | Answers | Changes per | |------|---------|-------------| | `agents//PERSONA.md` | Who is doing this? Voice, judgment, standards. | Agent | | `protocols/.md` | What behavioral contracts apply? Cross-cutting rules. | Protocol | | `skills//SKILL.md` | What procedure is being followed? Steps, output format. | Skill | | Pipeline `instructions:` | What is the specific task right now? | Event | **The test:** * If an instruction is still true when the agent is doing a completely different task with a completely different skill, it belongs in `PERSONA.md`. * If an instruction is a behavioral contract that multiple skills need — how to avoid repeating work, how to handle an ambiguous outcome, how to escape early — it belongs in a `protocols/` file. * If it only applies to one procedure, put it in `SKILL.md`. * If it depends on the specific event, put it in the pipeline `instructions:`. ## Protocols Protocols are named behavioral contracts that skills declare and bento injects. They sit between the built-in infrastructure blocks and the agent persona in the assembled system prompt. A protocol file lives at `protocols/.md`: ```markdown --- name: commit-aware-retry description: HEAD-anchored re-attempt guard for recurring tasks. --- Before doing any recurring work on this thread, compare the current HEAD SHA to the SHA recorded in your notes from the last run... ``` A skill declares the protocols it requires in its frontmatter: ```markdown --- name: solve-issue protocols: - commit-aware-retry - outcome-discipline --- # Solve an agent-ready issue [task-specific instructions only] ``` Bento injects each declared protocol as a `## Protocol: ` block into the agent's system prompt at assembly time. The skill body only contains what is unique to that task. An unknown protocol name is a hard error at startup — the daemon will not load a skill that references a protocol that does not exist. ### What belongs in a protocol A protocol is the right layer for behavioral patterns that: * Apply across multiple unrelated skills (early-escape guards, outcome discipline, attribution rules) * Describe *how* to act rather than *what* to do * Would otherwise be copy-pasted across skill files and drift out of sync If a behavioral rule only makes sense for one skill, keep it in that skill's body. ## Composability Because agents, protocols, and skills are separate, you can combine them in any pipeline: * **One agent, many skills.** A `reviewer` persona runs a whole-PR review skill in one pipeline and a comment-reply skill in another. Same voice, different procedures. * **One skill, many agents.** A `triage` skill runs under a `support-bot` agent for customer tickets and under a `pm` agent for internal issues. Same procedure, different judgment and tone. * **One protocol, many skills.** A `commit-aware-retry` protocol is declared by both `issue-triage` and `solve-issue`. The guard logic is written once and stays in sync across both. This only works if the layers are actually independent. An agent that names a skill, or a skill that duplicates a protocol, breaks reuse. ## Keep layers independent * `PERSONA.md` does not name a skill, an output format, or a trigger type. * `SKILL.md` does not assume a particular agent's voice or persona. * A protocol does not contain task-specific steps or output formats. * Neither names a pipeline. **Prefer narrow skills over branchy ones.** A skill file that says "if this is a PR review, do X; if this is a comment reply, do Y" is two skills pretending to be one. Write one skill per procedure. ## Output formats belong in the skill A structured output requirement exists because a specific pipeline needs it. It belongs in `SKILL.md`, not `PERSONA.md`. If the output contract lived in the persona, every pipeline using that agent would inherit it — including ones that want plain prose. ## What this looks like in practice ``` agents/ reviewer/PERSONA.md # reads critically, cites specifics, does not hedge notifier/PERSONA.md # concise, friendly, no technical jargon protocols/ commit-aware-retry.md # check HEAD before re-attempting recurring work outcome-discipline.md # always reach an explicit outcome; never post partial work skills/ review/SKILL.md # whole-PR: read repo, assess readiness, post GitHub review pr-comment/SKILL.md # comment reply: evaluate against HEAD, emit structured reply solve-issue/SKILL.md # solve one agent-ready issue; protocols: [commit-aware-retry, outcome-discipline] standup/SKILL.md # summarise merged PRs and open review requests pipelines/ pr-review.yaml # reviewer + review + event prompt comment-reply.yaml # reviewer + pr-comment + event prompt issue-solve.yaml # solver + solve-issue + static prompt morning-standup.yaml # notifier + standup + static prompt ```