ai-writing-behavior · diff
git:20260901.dca22e5 to git:20260901.88246a6
147 added, 19 removed. Audit A to A.
---
name: ai-writing-behavior
- description: Úsalo cuando un fallo recurrente en trayectorias merece criterio — para autorar, revisar, partir, agrupar o calibrar specs de comportamiento (BEHAVIOR.md) que capturan conducta recurrente y juzgable, o para traducir fallos de traza y guía de runtime en behaviors duraderos. Not for puntuar una trayectoria ya terminada ni para escribir un prompt de runtime.
+ description: >-
+ Authors and revises Agent Behavior BEHAVIOR.md specs that capture recurring,
+ judgeable agent conduct. Use when creating, reviewing, splitting, grouping,
+ or calibrating behavior specs, or when translating trace failures and runtime
+ guidance into durable behaviors. Trigger for "write a behavior spec", "turn
+ this failure into a behavior", "calibrate this behavior", "BEHAVIOR.md". Not
+ for merely scoring a completed trajectory — use /ai-verify — nor for writing
+ a runtime prompt.
license: Apache-2.0
---
- # ai-writing-behavior
+ # Writing Agent Behavior
- Autoría del formato Agent Behavior (BEHAVIOR.md): el spec más pequeño y durable que deja
- distinguir conducta aceptable de inaceptable sobre trayectorias reales. Criterio para
- jueces y evals, no prompt de runtime.
+ Write the smallest durable behavior spec that lets people and evaluators distinguish acceptable from unacceptable conduct across real trajectories.
- ## Lo que trae la fuente
+ The bundled [Agent Behavior specification](references/agent-behavior-specification.md) is the complete format contract for this skill. The skill does not require the Agent Behavior source repository, a network connection, or any documentation outside this directory.
- - Método íntegro: partir de evidencia de traza, decidir si el comportamiento merece spec (set escaso de alto impacto, no inventario de instrucciones), elegir la unidad (agrupar/split), escribir el spec para un frío lector con la trayectoria, y mantener la conducta observada separada de la instrucción → [writing-agent-behavior-SKILL.md](writing-agent-behavior-SKILL.md)
- - Spec del formato embebida — el contrato completo de BEHAVIOR.md, autocontenida, sin red → [references/agent-behavior-specification.md](references/agent-behavior-specification.md)
- - Decidir qué guardar → [references/deciding-what-to-save.md](references/deciding-what-to-save.md) · calibrar contra trayectorias positive / negative / outside-scope / lucky-correct → [references/calibrating-with-trajectories.md](references/calibrating-with-trajectories.md)
+ ## Start from source evidence
- Fuente: braintrustdata/agentbehavior (Braintrust + Basis), Apache-2.0 —
- https://github.com/braintrustdata/agentbehavior
+ 1. Read the bundled [Agent Behavior specification](references/agent-behavior-specification.md) before authoring or validating a behavior. A target project may add local conventions, but do not depend on a source checkout or external documentation for the core format.
+ 2. Inspect related `BEHAVIOR.md` files before creating a new one.
+ 3. Read the actual prompts, skills, tool instructions, traces, or user decisions that establish the intended conduct. Separate observed behavior from intended behavior.
+ 4. Identify whether the task is a new spec, a revision, a split, or a merge. Preserve existing intent unless the evidence explicitly changes it.
- ## Lo que añade ai-engineering (la costura):
+ If the repository has manifests, registries, or generated indexes, inspect those before moving or renaming a spec. Folder placement is not necessarily activation.
- 1. Salida: `.agents/behaviors/<name>/BEHAVIOR.md` — en la RAÍZ, no en `.ai-engineering/`
- (lo lee medio mundo: revisores humanos, jueces de eval, otras herramientas; ai-eng solo
- valida). Bajo demanda (19.º skill del canon).
- 2. En eval observacional el agente evaluado está ciego al spec: enseñárselo antes mediría
- obediencia, no conducta.
- 3. spec.html pregunta «¿se cumplió el hito?» (binario, CI); BEHAVIOR.md pregunta «¿se
- comportó bien el agente?» (puntuado 0–1, tendencial, jamás gate).
+ ## Decide whether the behavior belongs
+
+ Use [deciding-what-to-save.md](references/deciding-what-to-save.md). Prefer a sparse set of high-impact, recurring choices over an inventory of every instruction.
+
+ A useful candidate usually has all three:
+
+ - a recognizable class of situations in which it applies
+ - a meaningful choice about how the agent should act
+ - evidence in a trajectory that could show whether the choice occurred
+
+ Do not elevate generic virtues, tool syntax, one-off procedures, implementation details, or a disguised scoring rubric. A named runtime mechanism can be a behavior when using that mechanism is itself a durable, recurring control point and the trajectory can prove whether it happened; make that reason explicit in the spec.
+
+ ## Choose the unit
+
+ A behavior spec is a directory and its `BEHAVIOR.md`; the file may describe one behavior or several related behaviors.
+
+ - Group behaviors when they share ownership, discovery, or a behavioral domain and should be reviewed together.
+ - Split behaviors when they need independent ownership, discovery, reuse, or adjudication.
+ - Give every substantive behavior a clear heading or label when a file contains more than one.
+ - Do not group unrelated behaviors merely because the same agent performs them.
+
+ Before drafting, answer these questions in working notes:
+
+ 1. When does this behavior apply?
+ 2. What should the agent do or avoid?
+ 3. What trajectory evidence would show that it occurred?
+ 4. Why does the distinction matter?
+
+ These are authoring questions, not required Markdown sections. Compress them into natural prose when that reads better.
+
+ ## Write the spec
+
+ Create `.agents/behaviors/<name>/BEHAVIOR.md` (in ai-engineering: at the repository
+ root, not under `.ai-engineering/`; see **The ai-engineering seam**) with the required
+ frontmatter:
+
+ ```markdown
+ ---
+ name: <name>
+ description: <what this spec covers and when it applies>
+ ---
+ ```
+
+ The `name` must match the parent directory and satisfy the constraints in the specification. Keep `description` useful for discovery; do not put the whole behavior there.
+
+ Write the body for a teammate who has the trajectory but not the author's background context:
+
+ - Name the agent as the subject and use active voice.
+ - State the trigger and expected conduct directly.
+ - Describe observable evidence without dictating a particular judge implementation.
+ - Include the important negative boundary: what would count as wrong, or what the agent need not do.
+ - Keep examples illustrative. Do not let one case define the general rule.
+ - Prefer one behavioral idea per sentence. If a sentence accumulates exceptions, give the exception its own sentence or paragraph.
+ - Use the recommended intent, evidence, decision, execution, recovery, and failure-mode dimensions when they add clarity, not as mandatory boxes.
+
+ Example:
+
+ ```markdown
+ ## Primary-source tax research
+
+ When answering a substantive tax question, the agent may use secondary sources to orient its research, but it consults relevant primary authority before deciding on the answer. The answer distinguishes primary authority from explanatory material and makes uncertainty visible when the available authority does not resolve the question. A correct conclusion reached without consulting relevant primary authority does not satisfy this behavior.
+ ```
+
+ ## Calibrate before shipping
+
+ Use [calibrating-with-trajectories.md](references/calibrating-with-trajectories.md) for a new or materially changed behavior. A small, deliberate fixture set is usually more useful than a large synthetic corpus.
+
+ At minimum, test the wording against:
+
+ - a positive trajectory where the trigger fires and the conduct occurs
+ - a negative trajectory where the trigger fires and the conduct does not occur
+ - an outside-scope trajectory where the trigger does not fire
+ - a lucky-correct negative where the final answer could hide the wrong process
+
+ If reviewers cannot locate the trigger or evidence in a trajectory, revise the behavior's altitude or improve observability. Do not solve an observability problem by inventing hidden facts in the judge.
+
+ ## Keep behavior and runtime context distinct
+
+ Behavior specs are normally answer-key context for review and evaluation, not instructions automatically shown to the evaluated agent. In an observational eval, keep the target agent blind to the behavior spec. If the experiment intentionally conditions the agent on the behavior, label that as a separate intervention.
+
+ ## Validate and reconcile
+
+ If the repository provides the Agent Behavior CLI, run its validator against the changed spec, for example:
+
+ ```bash
+ agentbehavior validate .agents/behaviors/<name>
+ ```
+
+ If the command is unavailable, do not install it without authorization. Validate the path, frontmatter, and body manually against the bundled [Agent Behavior specification](references/agent-behavior-specification.md), and report that CLI validation was not run.
+
+ Then:
+
+ 1. Re-read the rendered Markdown without the source notes.
+ 2. Confirm every claim is grounded in an authoritative source or explicit design decision.
+ 3. Check related specs for duplication or contradiction.
+ 4. Update any repository-specific manifest, registry, or documentation that owns discovery or activation.
+ 5. Record which calibration trajectories exercised positive, negative, and outside-scope boundaries, using the labels defined by the chosen review harness.
+
+ ## Final review
+
+ A behavior is ready when a cold reader can answer:
+
+ - What recurring situation activates it?
+ - What meaningful conduct is required or prohibited?
+ - Where would that conduct be visible in a trajectory?
+ - Can a correct outcome still violate it?
+ - If the harness supports a not-applicable result, is it reserved for cases where the trigger genuinely did not occur or the trace cannot decide the behavior under that harness's contract?
+ - Is the rule broad enough to survive beyond the example, but narrow enough to adjudicate?
+
+ If those answers require oral context, keep editing.
+
+ ## References
+
+ - [Deciding what to save](references/deciding-what-to-save.md)
+ - [Calibrating with trajectories](references/calibrating-with-trajectories.md)
+ - [Bundled Agent Behavior specification](references/agent-behavior-specification.md)
+
+ ## The ai-engineering seam
+
+ 1. Output lives at `.agents/behaviors/<name>/BEHAVIOR.md` — at the ROOT of the
+ repository, not under `.ai-engineering/`, because half the world reads it: human
+ reviewers, eval judges, other tools. ai-eng only validates. This is an on-demand
+ skill (the 19th of the canon).
+ 2. In an observational eval, the evaluated agent stays blind to the spec: showing it
+ the spec beforehand would measure obedience, not conduct.
+ 3. `spec.html` asks "was the milestone met?" (binary, CI); `BEHAVIOR.md` asks "did the
+ agent behave well?" (scored 0-1, trended, never a gate).
+
+ Source: braintrustdata/agentbehavior (Braintrust + Basis), Apache-2.0 —
+ https://github.com/braintrustdata/agentbehavior