Emotion Skill

Emotion Skill is a small runtime router for coding agents.

It reads the latest user turn, recent dialogue, retries, delay pressure, optional host state, and optional feedback from the last routing decision. It then returns a compact host contract that tells the agent how to work this turn.

The core rule: internal user-state signals must become positive execution instructions. Production hosts should pass guidance.system_prompt_addendum, response_constraints, and routing into the model. Raw affect fields stay internal unless audit mode is explicitly enabled.

Use It When

• A bug fix has failed more than once.
• The user asks for evidence, exact checks, logs, or root cause.
• The user says to touch only specific files or avoid config drift.
• A tool call, session, queue, or heartbeat path has gone silent.
• The user says the work is good and the agent should close out.
• The agent needs to choose between collect, steer, and interrupt modes.

What It Returns

Use the host command for real integration:

python scripts/emotion_engine.py host --message "Show me the basis before changing more files." --pretty

Default host shape:

{
  "mode": "skeptical",
  "route_reasons": ["evidence_requested", "stall_risk"],
  "response_constraints": ["show_basis_first", "name_verification_steps", "avoid_guessing", "include_check_result", "progress_update_required"],
  "guidance": {
    "system_prompt_addendum": "The user wants evidence before more changes. Start with a verification point, command, or log excerpt, then give the conclusion and next step.",
    "tone": "evidence_first"
  },
  "routing": {
    "reply_style": "evidence_then_act",
    "verification_level": "high",
    "queue_mode": "collect",
    "prefer_main_thread": false,
    "progress_update_interval_sec": 20
  }
}

Default output deliberately keeps raw labels and raw emotion_vector out of the host prompt path. This keeps the skill from amplifying negative state words inside the model context.

Host Fields

• guidance.system_prompt_addendum: positive instruction text for the host LLM.
• guidance.tone: compact tone target such as evidence_first, careful_and_bounded, or guarded_closeout.
• response_constraints: compact reply guardrails.
• route_reasons: enum-like routing codes for logs and telemetry.
• routing.reply_style: response posture.
• routing.verification_level: checking depth.
• routing.queue_mode: collect, steer, or interrupt.
• routing.prefer_main_thread: keep the work on the main turn when user trust or clarity needs it.
• routing.progress_update_interval_sec: progress cadence for long-running work.
• satisfaction_lock: closeout guard after success.
• interaction_state: positive host-facing axes: clarity, trust, engagement.
• state.state_delta: action-named shifts such as needs_concrete_unblock, needs_evidence_first, or needs_alignment_check.
• memory.should_persist: host-side persistence recommendation.

Top-level interaction_state is canonical. state.interaction_state is a deprecated compatibility alias for v1.1 hosts and is marked by state._deprecated_alias; plan to remove that alias after the 1.4 line.

state.state_delta.interaction.needs is validated against alignment_check, evidence_first, and keep_progress_visible.

Input Contract

Smallest valid payload:

{
  "message": "latest user message"
}

Production payload:

{
  "message": "Only touch the parser file and show the failing path first.",
  "history": [
    {"role": "user", "text": "earlier user turn"},
    {"role": "assistant", "text": "earlier assistant turn"}
  ],
  "runtime": {
    "response_delay_seconds": 20,
    "unresolved_turns": 3,
    "bug_retries": 2,
    "same_issue_mentions": 2,
    "queue_depth": 1,
    "background_tasks_running": 1,
    "last_routing_outcome": {
      "mode_was": "skeptical",
      "user_followed_up_with": "still broken"
    }
  },
  "last_state": {
    "vector": {},
    "emotion_vector": {},
    "ttl_seconds": 1200
  },
  "calibration_state": {},
  "user_profile": {}
}

Malformed JSON, missing files, and top-level arrays return exit code 2 with a single-line error.

Raw Affect Audit Mode

For audit and calibration only:

{
  "host_capabilities": {
    "include_raw_emotion": true
  }
}

This adds diagnostics.internal.labels, diagnostics.internal.emotion_vector, raw state_delta, and mode_scores. Keep these fields out of normal LLM prompts.

Safety precedence: an explicit payload value of host_capabilities.include_raw_emotion=false or include_internal_diagnostics=false disables raw diagnostics even when the CLI includes --include-raw-emotion.

Runtime Commands

Command	Purpose
host	compact production contract
run	full diagnostics
screen	deterministic first pass
confirm	final state and weight schedule
predict	risk, stall, patience, and semantic-pass budget
route	routing only
guide	short-probe guidance
overlay	overlay prompt inspection
posthoc	review-pass and calibration inspection

Persistence Boundary

The core engine is stateless. It returns JSON, makes no network calls, and writes only when --output is provided.

Named timezone conversion uses Python zoneinfo when host timezone data is available. On Windows hosts without IANA timezone data, pass context.local_hour or an offset-bearing context.now_iso for deterministic local-hour handling without adding runtime dependencies.

The minimal host adapter writes three host-owned JSON files under --store-dir when persistence is enabled:

• user_profile.json
• last_state.json
• calibration_state.json

Use --no-persist for read-only previews. Use --ignore-bad-store to skip corrupt store files and continue from empty values.

Integration Pattern

1. Run host when a user turn arrives.
2. Put guidance.system_prompt_addendum before the model's task instructions.
3. Put overlay_prompt near the runtime metadata.
4. Feed response_constraints into reply planning.
5. Feed routing into queue, heartbeat, progress cadence, and subtask policy.
6. Apply satisfaction_lock after success.
7. Persist memory.proposed_calibration_state only in host-owned storage.

Runtime Layout

scripts/emotion_engine.py is the CLI and pipeline facade. Runtime logic lives in focused modules:

• emotion_types.py: schema, dimensions, enums, and typed maps.
• emotion_terms.py: terms, regexes, language detection, and counting.
• emotion_features.py: payload, profile, history, and feature extraction.
• emotion_scoring.py: screen, labels, mode scores, and dominant mode.
• emotion_routing.py: prediction, analysis, routing, constraints, and state delta.
• emotion_output.py: positive prompts, guidance, overlays, and host output.
• emotion_utils.py: shared JSON, diagnostics, vector, and normalization helpers.

Published Bundle

ClawHub publish now ships the runtime-facing subset only:

• SKILL.md
• README.md
• README.zh-CN.md
• CHANGELOG.md
• agents/openai.yaml
• scripts/emotion_engine.py
• scripts/emotion_types.py
• scripts/emotion_terms.py
• scripts/emotion_utils.py
• scripts/emotion_features.py
• scripts/emotion_scoring.py
• scripts/emotion_routing.py
• scripts/emotion_output.py
• scripts/minimal_host_adapter.py
• scripts/download_smoke.py
• demo/local_history_event.json
• references/examples.md
• references/model-prompts.md
• references/emotion-value-model.md
• references/emotion-policy-matrix.md
• references/integration-openclaw-hermes.md

The full GitHub repo keeps the heavier regression, audit, and calibration assets.

Validation

Published-bundle smoke:

python scripts/download_smoke.py

Runtime profiling:

python scripts/emotion_engine.py run --input demo/local_history_event.json --profile --log-level INFO --pretty

--profile adds pipeline_profile to full run output. --log-level INFO writes mode, labels, route reasons, degradation state, and total runtime to stderr, keeping stdout as valid JSON.

Full GitHub validation:

python scripts/alignment_test.py
python scripts/ablation_test.py
python scripts/smoke_test.py --seed 20260424 --strict
python scripts/independent_audit.py
python scripts/marketplace_tag_audit.py
python scripts/feature_gate_audit.py
python scripts/bundle_manifest_check.py
python -m compileall -q scripts

Current local regression results:

• alignment: 70/70
• ablation: 333/333
• strict smoke: ok
• independent audit: ok
• download smoke: ok
• marketplace scope audit: ok
• feature gate audit: ok
• bundle manifest: ok

Good Fit

Use it for coding-agent orchestration, repository debugging, scoped edits, verification-first replies, and closeout behavior after success.

Use a different skill for general emotional memory, roleplay, personal journaling, or long-term personality simulation.