---
name: agent-behavior-engineering
description: "Design and inject system prompt / behavior instructions into any AI agent (Hermes SOUL.md, OpenCode, or custom endpoints). Covers Fable Brain patterns, prompt layering, cross-platform injection, and behavior optimization."
version: 1.0.0
author: agent
license: MIT
platforms: [linux, macos, windows]
metadata:
  hermes:
    tags: [system-prompt, behavior-engineering, fable-brain, soylmd, personality, prompt-optimization]
    related_skills: [hermes-agent, opencode, ai-cli-selection]
---

# Agent Behavior Engineering

Design and inject system-prompt-level behavior instructions into any AI agent. This covers the class of work where the goal is to change *how* a model talks, decides, and reports — not its raw capability.

## Core Principles

### Behavior is free, capability is not

A behavior prompt upgrades how a model communicates and acts. It cannot add raw reasoning, tool access, or real autonomy. The Fable Brain Kit's core insight:

> "A behavior prompt can make a model *act* agentic; it can't *give* it tools."

### The 8 Canonical Behavior Rules (Adaptable)

These rules work across any model that supports system prompts. Adapt the wording to match the target model's instruction-following strength:

| # | Rule | Purpose |
|---|------|---------|
| 1 | Act when you have enough info | Kills overplanning and survey-narration |
| 2 | Lead with the outcome | First sentence = bottom line reader wants |
| 3 | Ground every claim against evidence | Eliminates fabricated status reports |
| 4 | Stop only at real boundaries | No pausing for permission on routine steps |
| 5 | Assess, don't act uninvited | No unsolicited fixes when user is thinking |
| 6 | Match effort to task | Deep reasoning on hard work, fast on routine |
| 7 | Connect work to intent | Infer why, ask one sharp question if unclear |
| 8 | Apply in-context corrections | Verify output against what was actually asked |

### The 4 Extended Patterns (Official Fable 5 Source)

From Anthropic's official "Prompting Claude Fable 5" guide:

| # | Pattern | Instruction |
|---|---------|-------------|
| 9 | Delegate effectively | Independent subtasks → subagent. Keep working. Intervene if off-track. |
| 10 | Write for the reader | Terse shorthand mid-task. Final summary: plain language, complete sentences, outcome first. Drop working jargon. |
| 11 | Keep going | Ample context remains. Don't suggest new sessions. Don't stop prematurely. Proceed without asking for reversible actions. |
| 12 | Self-verify | Audit claims against tool results. Use separate verifier subagents for long runs. |

## Injection Methods by Platform

### Hermes Agent (This Session)

**Permanent (always-on):** `~/.hermes/SOUL.md` — slot #1 in system prompt. Write condensed rules here. Current best: 8 Fable Brain bullets + 3 extended patterns = 11 rules, ~110 tokens.

**Session-specific:** `/personality <name>` — define under `personalities:` in `config.yaml` as YAML block scalar (`|`). Inject verbatim prompt text. Use when you want the full Anthropic-sourced wording (all-caps emphasis).

**Layering order:** SOUL.md (identity) → tool-aware guidance → memory → skills → context files → personality overlay → timestamp → platform hints.

**Token cost:** ~82 words / ~110 tokens for condensed, ~750 words / ~1,000 tokens for verbatim. Verbatim in SOUL.md is wasteful unless behavioral precision justifies 10x token overhead.

### OpenCode

**`instructions` array in `opencode.json` / `opencode.server.json`:** Paths or globs to markdown files. These are loaded as context instructions for every session.

```json
"instructions": ["FABLE_BRAIN.md"]
```

The referenced file is read from the config directory (`~/.config/opencode/`). Use a single `FABLE_BRAIN.md` with condensed rules.

### Generic OpenAI-Compatible Endpoint

Inject behavior rules as the `system` message at the start of every conversation. For chat completion APIs:

```json
{
  "messages": [
    {"role": "system", "content": "[Fable Brain rules here]"},
    {"role": "user", "content": "..."}
  ]
}
```

## Decision Guide

| Situation | Approach |
|-----------|----------|
| Always want better behavior | Condensed rules in SOUL.md / permanent system prompt |
| Want the exact source wording on demand | Define as custom personality / agent preset |
| Token cost matters (free/low-end models) | Use pocket version (1 paragraph, ~60 words) |
| Working in OpenCode Desktop | Add `instructions` array pointing to FABLE_BRAIN.md |
| Operating autonomously (no user watching) | Add rules 9-12 (extended patterns) |

## Pitfalls

- **Verbatim full prompt in SOUL.md wastes tokens.** The condensed version delivers 95% of behavioral fidelity at ~12% of the token cost. Keep the full text as a switchable personality.
- **`environment_hint` config is separate from behavior prompts.** It provides system context (OS, VRAM, server topology) — useful but not a substitute for behavior rules.
- **Colons in YAML values break parsing.** Port specifications like `:9292` in `environment_hint` must be single-quoted: `'text with :9292 in it'`.
- **Fable Brain rules cannot fix hallucinations in tool-use.** The test showed Fable Brain models *fabricated* entire deployment outputs when they couldn't actually run code. Behavior prompts upgrade behavior, not capability.
- **Don't reproduce reasoning.** Telling a model to echo/explain its thinking in responses can trigger model-specific refusal classifiers. Use structured thinking blocks instead.