# Context engineering Every agent run receives a prompt assembled from operator-controlled files. Agents, skills, and policies are separate files, so you assemble any combination of them without copying. ## The four layers | File | Answers | Changes per | |------|---------|-------------| | `agents//PERSONA.md` | Who is doing this? Voice, judgment, standards. | Agent | | `policies/.md` | What behavioral contracts apply? Cross-cutting rules. | Policy | | `skills//SKILL.md` | What procedure does the agent follow? Steps, output format. | Skill | | Pipeline `instructions:` | What is the specific task right now? | Event | Use these rules to choose a file: * 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, it belongs in a `policies/` file. Such contracts cover how to avoid repeating work, how to handle an ambiguous outcome, and how to escape early. * 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:`. ## Policies Policies 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 policy file lives at `policies/.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 policies it requires in its frontmatter: ```markdown --- name: solve-issue policies: - commit-aware-retry - outcome-discipline --- # Solve an agent-ready issue [task-specific instructions only] ``` Bento injects each declared policy as a `## Policy: ` block into the agent's system prompt at assembly time. The skill body only contains what is unique to that task. An unknown policy name is a hard error at startup. The daemon refuses to load a skill that references a policy that does not exist. ### What belongs in a policy A policy is the right layer for behavioral patterns that: * Apply across multiple unrelated skills, such as early-escape guards, outcome discipline, and attribution rules. * Describe *how* to act rather than *what* to do. * Drift out of sync when an author copies them across skill files. If a behavioral rule only makes sense for one skill, keep it in that skill's body. ## Composability Agents, policies, and skills are separate, so any pipeline combines them freely: * **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 policy, many skills.** A `commit-aware-retry` policy is declared by both `issue-triage` and `solve-issue`. The guard logic is written once and stays in sync across both. This works only while the layers stay independent. An agent that names a skill, or a skill that duplicates a policy, 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 policy does not contain task-specific steps or output formats. * None of these files names a pipeline. Write one skill per procedure. For example, put PR review steps and comment reply steps in separate skills. ## 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`. An output contract in the persona reaches every pipeline that uses the agent, including the pipelines 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 policies/ 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; policies: [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 ```