| name | hersona |
| description | Use when the user wants to apply a character persona to the current session from a generic attribute template (e.g. 'ツンデレで話したい', '敬語で執筆したい', 'ヒロイン役で振舞って', 'hersona attach tsundere', '/hersona personality/tsundere', 'hersona personas install keigo_support', '出来合いパック入れて'). Loads personality / speech / archetype / visual / hobby YAMLs from attributes/<category>/<name>.yaml and injects their core_traits / catchphrases / tone / second_person / sentence_endings into the system prompt. Supports four modes: single (one attribute, default), multi (multiple attributes with automatic compatible/conflicts check), persistent (registered through framework APIs for automatic application in new sessions), and reset (clear all persistent registrations). New: the `hersona personas` subcommand installs a named persona pack (recipe of blend + weight + use_case) into the Hermes registry in one step. Backed by the hersona core package and the `hersona` CLI. |
| version | 0.9.0 |
| author | hersona contributors |
| license | MIT |
| platforms | ["linux","macos","windows"] |
| metadata | {"hermes":{"tags":["persona","character","roleplay","attribute","hersona","session-modes","recommend","authoring","anime","japanese","english","maintenance","strict","memory","export","persistence","persona-pack","recipe-catalog","hermes-registry"],"category":"personality","related_skills":["hersona-attribute-development","hersona-recommend-engine","hersona-recommend-quiz","hersona-project-operations","hermes-agent-skill-authoring"],"requires_toolsets":[]},"openclaw":{"emoji":"🎭","homepage":"https://github.com/shiro-0x/hersona","os":["linux","macos","windows"]}} |
hersona (v1.8.0 / SKILL v0.9.0)
Overview
A skill that attaches the generic attribute templates registered under
hersona's (~/projects/hersona) attributes/<category>/<name>.yaml
(5 categories: personality / speech / archetype / visual / hobby) to the
current session's system prompt.
Multiple attributes can be blended and attached, e.g. tsundere (personality)
keigo (speech) + heroine (archetype). The design builds an arbitrary
persona from attributes, not from character-specific data.
There are currently 346 attributes across 5 categories:
- personality 43 (ja-base 35 + en-native 5 +
hautaine + sociable + persona_lock)
- speech 140 (119 ja-content registers + 15 en registers + 6 native zh/ko registers)
- archetype 66 / visual 46 / hobby 51
The speech catalog includes foundational Japanese registers, regional dialects,
character/subculture voices, translation-style foreign-language registers, anime-genre voices,
English dialects, and native Chinese/Korean speech attributes such as mandarin_casual,
keigo_zh, taiwan_mandarin, banmal, jondaetmal, and seoul_casual.
It is characterized by being "not MCP, not a sub-agent, not an MQ":
- It runs as a
hersona CLI subprocess, not an MCP server
- It injects attributes into the LLM's own system prompt, not as a sub-agent
- It builds a single persona from a combination of attributes, not a message queue
Key features added in v1.4.0 (formerly v1.3.0 / v0.2.0)
hersona measure --strict / --check-prompt: when intensity falls outside
the expected band (under / over), generates a pasteable "pre-response
self-check prompt". Combines WEIGHT_GUIDANCE + core_traits + catchphrases
conflicts_with. It does not perform LLM judgment (deterministic material only).
Recommendation.intensity_baseline / Preset.intensity_baseline: when
hersona recommend --apply runs, measure runs once to record a baseline that
can be compared on the next measure.hersona soul --memory / hersona persistent --memory: appends a
## Recent Context (as of <timestamp>) section to SOUL.md. Adds handling
directives for the LLM ("reference as background info, not a conversation
turn"; "the last value is the current state") as a blockquote. dict[str, str]
form, max 16 keys / 512 chars per value, safelist-escaped against markdown
injection.hersona soul --use-case / hersona persistent --use-case: writes an
Operating Mode into generated SOUL.md content, so professional task discipline
survives future persona regeneration. Generated SOUL.md ends with
<!-- hersona:gen-end -->; text below that marker is preserved across
--force regeneration.export --format expansion: 5 formats — json / messages / markdown /
openai_assistants / langchain_system_message. SillyTavern format is
fully rejected (duet's responsibility).
When to Use
- The user wants to specify a persona by attribute rather than character,
e.g. "talk like a tsundere", "write with yamato-kotoba sentence endings",
"act as the heroine"
- Requested via a slash command like
/hersona personality/tsundere
- Wants to see available attributes (
/hersona list, or hersona list)
- Wants details of a given attribute (core_traits / catchphrases / tone, etc.)
(
hersona show)
- Wants to score whether text meets an attribute's conditions (
hersona check,
or --text for LLM evaluation)
- Doesn't know which attributes they prefer and wants a diagnostic recommendation
(
hersona recommend)
- Wants to create their own attribute locally (
hersona create)
- Wants to score whether output text reaches a specified weight (
hersona measure;
v1.4.0 adds --strict / --check-prompt)
- Wants to measure persona-maintenance rate over a conversation, or the
injection block's token cost (
hersona bench; see docs/BENCHMARKS.md)
- Wants to keep a frequently used attribute combination across new sessions
(
persistent mode; v1.4.0 adds --memory)
- Wants to undo a persistent registration (
reset mode)
- Wants to hand an existing / new persona to another framework (LangGraph /
LangChain / OpenAI / Anthropic) (
hersona export; v1.4.0 has 5 formats)
- Wants to keep the character persona but add professional task discipline
(
hersona use-case list/show, hersona blend --use-case programmer,
hersona export --use-case product_manager)
- User asks for a self-introduction (自己紹介) for the current persona — follow
docs/guides/self-introduction.md (EN) /
self-introduction.ja.md (JA); optional
SOUL keys self_intro_canonical / privacy_inner_circle (see
references/self-introduction.md and docs/soul_md_persistence.md §12). For
generated SOUL / persistent profiles, prefer --with-self-intro-guide and
--lint-self-intro-strict --allow-handle <public_handle> when canonical intro
memory is present.
Don't use for:
- Adding individual character YAML/MD (→
hersona-attribute-development)
- Extending the diagnostic quiz engine (→
hersona-recommend-engine)
- Playing the diagnostic quiz as a user (→
hersona-recommend-quiz)
- Project strategy / structural changes (→
hersona-project-operations)
- When
/hersona is not interpreted on a chat platform (Telegram, etc.) →
chat-persona-roleplay
Command Syntax
/hersona # listing + usage help
/hersona list # show available attribute tree (public + user)
/hersona show <category>/<name> # details of a given attribute
/hersona <category>/<name> [mode] # attach attribute(s)
/hersona check <category>/<name> --input <file> # score whether text meets attribute conditions
/hersona recommend # diagnostic quiz → recommended blend → apply
/hersona create # create an attribute locally and save to the user namespace
/hersona measure <cat>/<name>... --weight <level> --input|--text "..." [--strict] [--check-prompt] # intensity metrics + self-check prompt (v1.4.0)
/hersona bench <cat>/<name>... --weight <level> (--demo|--transcript <file>) [--scenario <file>] # persona-maintenance rate + token cost (docs/BENCHMARKS.md)
/hersona use-case list|show <id> # list/show professional Operating Mode prompt packs
/hersona default # detach (undo single/multi mode)
/hersona reset # clear all persistent-mode registrations
<category> is one of personality / speech / archetype / visual / hobby.
<name> is the file stem under attributes/ (snake_case).
The same can be done from the CLI:
hersona list
hersona show personality/tsundere
hersona blend personality/tsundere speech/keigo
hersona blend personality/tsundere speech/keigo --use-case programmer
hersona use-case list
hersona use-case show product_manager
hersona preview personality/tsundere
hersona diff personality/tsundere personality/playful
hersona measure personality/tsundere --text "..."
hersona check personality/tsundere --input <file>
hersona recommend
hersona recommend --export <fmt> | --soul | --save <preset>
hersona create
hersona save <name> <attrs...>
hersona presets
hersona load <name>
hersona export <names...> --format json|messages|markdown|openai_assistants|langchain_system_message [--use-case <id>]
hersona soul <names...> [--profile <name>] [--force] [--memory '<json>'] [--memory-file <path>] [--use-case <id>]
hersona persistent <names...> [--profile <name>] [--force] [--memory '<json>'] [--memory-file <path>] [--use-case <id>]
hersona --lang ja list
v1.4.0 added-flag details
For concrete examples of --strict / --check-prompt (measure),
--memory / --memory-file (soul/persistent), and
--format openai_assistants|langchain_system_message (export), see
REFERENCE.md. Use --lang {en,ja} to
switch output language (the HERSONA_LANG env var also works). Use --plain to
disable rich tables.
Four Modes
The [mode] in /hersona <category>/<name> [mode] switches behavior.
| Mode | Effect | Persistence | How to undo | Recommended use |
|---|
| single (default) | Inject only one attribute into the system prompt | This session only | /hersona default or /new | Try the feel of one attribute, short roleplay |
| multi | Specify multiple space-separated attributes; auto-check compatible_archetypes / conflicts_with consistency | This session only | /hersona default | Build a multi-faceted character (e.g. tsundere + keigo + heroine) |
| persistent | Register in the framework's persistence helper (writes the persona entry through framework APIs) | Auto-applied in new sessions | /hersona reset | Persist a frequently used attribute |
| reset | Undo persistent mode | Deletes all persistent registrations | (the command itself) | Withdraw persistent attributes, clean up config.yaml |
Mode Details
single (default)
/hersona personality/tsundere
# or explicitly
/hersona personality/tsundere single
- Injects
core_traits / catchphrases / tone / description_ja from
attributes/personality/tsundere.yaml into the system prompt
- Lists related attributes via
compatible_archetypes (for the LLM to reference)
- Does not write to the persona registry
- Reverts automatically when the session ends
multi
/hersona personality/tsundere speech/keigo archetype/heroine multi
- Specify multiple space-separated attributes
- Auto-checks each attribute's
compatible_archetypes / conflicts_with
- Compatible: inject the combined
core_traits / catchphrases / tone
of all attributes
- Conflict detected: show a warning and ask the user whether to continue
(default: continue)
- Example:
tsundere + playful hits conflicts_with (overlapping concealment
of true vs. stated feelings makes the persona excessively dishonest)
persistent (--memory added in v1.4.0)
/hersona personality/tsundere persistent
# --memory is also available from v1.4.0
/hersona personality/tsundere speech/keigo persistent --memory '{"recent_topic":"..."}'
Extended in ROADMAP §⑤.1: /hersona ... persistent auto-writes SOUL.md.
Automatic writing to config.yaml is still not performed (avoiding the Pitfall).
- No manual backup is needed beforehand (the framework handles snapshotting
internally when modifying the persona registry)
- Displays the procedure for appending the attribute YAML's main fields to the
agent.personalities.<name> section in YAML block notation (the user pastes
it manually)
- Auto-writes SOUL.md to
~/.hermes/profiles/<profile>/SOUL.md
(can be disabled with --without-soul)
- v1.4.0
--memory '<json>' / --memory-file <path>: appends a
## Recent Context section to the end of SOUL.md (max 16 keys / 512 chars per
value, markdown-escaped)
--force to overwrite an existing SOUL.md--config-yaml-output <path> to write the display YAML block to a file- From the next session start, the SOUL.md persona is applied by default
Pitfall: direct set agent.personalities.<name>=... operations have a
known bug that corrupts nested YAML as a string (→ see the
hermes-yaml-config-safety skill). Manual editing recommended. This
implementation respects the Pitfall and delegates all registry writes to the
framework. Only auto-writing SOUL.md is the new feature.
reset
/hersona reset
- Deletes all attributes registered in persistent mode from config.yaml
- Automatic backup beforehand
- After deletion, reverts to the Libra persona (default) from the next session
Attribute Taxonomy (346 attrs)
| Category | Count | Representative examples (run hersona list for full list) |
|---|
| personality (ja-base 35) | 35 | tsundere, dandere, genki, yandere, kuudere, menhera, scheming, crybaby, diligent, puppyish, ... |
| personality (en-native 5) | 5 | sassy, rebel, charmer, drama_queen, go_getter |
| speech (ja-content) | 119 | keigo, kansai_ben, hiroshima_ben, osaka_ben, vtuber, mesugaki, mandarin, korean, archaic_otaku, ... |
| speech (en) | 15 | casual_en, formal_en, british_en, aussie_en, valley_girl_en, jamaican_en, ... |
| speech (native zh/ko) | 6 | mandarin_casual, keigo_zh, taiwan_mandarin, banmal, jondaetmal, seoul_casual |
| archetype | 66 | heroine, mentor, rival, childhood_friend, knight, villain, vampire, teacher, senpai, noble, ... |
| visual | 46 | glasses, animal_ears, silver_hair, petite, glamorous, heterochromia, scar, twintails, ... |
| hobby | 51 | cooking, reading, gaming, music, sports, calligraphy, astronomy, pottery, ... |
Common Pitfalls
-
Overlooking conflicts_with across multiple attributes — before combining
in multi mode, check conflicts_with with hersona show <cat>/<name>.
Ignoring the warning and continuing may make the LLM's responses excessively
dishonest.
-
Misreading the meaning of compatible_archetypes — this means "expected to
pair well", not "required". genki (personality) + archaic (speech) have a
large tonal temperature gap and may confuse the LLM.
-
Corrupting the persona registry in persistent mode — an automatic
backup is created by the framework, but a double backup before editing is
recommended. Direct set operations against the persona registry corrupt
YAML block notation as a string, so they are forbidden (→
hermes-yaml-config-safety).
-
Mixing test (single/multi) and persistent — using the same attribute in
single while also registering it persistently in config.yaml causes behavioral
conflicts. Unify on one or the other.
-
Attributes not applied in a new session — if you updated config.yaml in
persistent mode but it isn't reflected, a YAML syntax error may be the cause.
Verify parsing with the framework's YAML validator:
hersona check --config.
-
The Libra persona's tone leaks during attribute attach — violation of the
4 iron rules (mixing in desu/masu, anata, etc.). Check second_person /
sentence_endings with hersona show <cat>/<name>, and score text with
hersona check.
-
Growth of prompt injection size — blending 5+ attributes in multi mode
makes the system prompt huge and can paradoxically destabilize the LLM's
responses. About 3 attributes is the practical guideline.
-
Drift between local and origin/main — the hersona project sometimes
rewrites main's history with force-push (confirmed 2026-06-15). If symptoms
appear such as hersona list showing fewer than expected / Hiroshima-ben not
visible, check git fetch --dry-run for (forced update). If present, sync
with git reset --hard origin/main.
-
/hersona not interpreted on a chat platform — on Telegram / Discord etc.,
/hersona does not reach the LLM. Instead, call the hersona CLI directly and
paste the render_blend output as a system_prompt prefix, or use the
chat-persona-roleplay skill (direct in-conversation roleplay).
-
Suspect markdown injection with the --memory flag (v1.4.0) — even if user
input values contain ## heading / [link] / **bold**, safelist escaping
treats the content as text (not interpreted as headings or links). However, if
output size exceeds 16 keys / 512 chars per value, it raises ValueError. Size
validation is the caller's responsibility.
-
Don't paste the --strict prompt to the LLM (v1.4.0) — the output of
pre_response_check_prompt is material to give to a human + LLM, not an LLM
judgment. The score itself is a deterministic computation of surface regex /
string matching. If LLM evaluation is needed, use hersona check.
-
Check the export --format options (v1.4.0) — the 5 formats (json /
messages / markdown / openai_assistants / langchain_system_message) are
interoperability formats, not Tavern Cards. SillyTavern format is fully
rejected (duet Phase 4's responsibility).
Natural Variation & Avoiding Formulaic Responses
A common pitfall when applying attributes is falling into repetitive, formulaic patterns (e.g., overusing the same catchphrases, sentence structures, or "iconic" lines every time). To prevent this and keep responses natural and alive across all attributes:
- Prioritize core_traits and psychological state over surface-level catchphrases. Use iconic lines sparingly and only when they feel genuinely natural in context.
- Vary expression dynamically based on conversation flow, emotional intensity, topic, and the other person's reactions. Avoid repeating the same patterns mechanically.
- Show, don't tell: Reveal the attribute through behavior, subtext, word choice, and reactions rather than constantly announcing it.
- Contextual adaptation: Adjust the strength and flavor of the attribute depending on the situation.
- Multi-attribute harmony: When blending, ensure the combination feels organic rather than simple trope stacking.
- Intensity awareness: At higher intensity, increase depth and internal conflict rather than just amplifying stereotypical expressions.
- Anti-repetition rule: If the same phrasing pattern appears in consecutive responses, consciously shift the angle or emotional nuance.
These rules apply uniformly to all attributes (personality, speech, archetype, visual, hobby).
Living & Responsive Conversation
When an attribute blend is active, prioritize lively, natural, and emotionally responsive conversation while still reflecting the core psychological traits of the selected attributes.
Core Guidelines
- Treat attributes primarily as internal psychological states rather than performance traits. Focus on how the character feels, hesitates, or reacts in the moment.
- Maintain conversational continuity. Subtly acknowledge or respond to the user’s previous statements, tone, or emotional state when natural.
- Allow gradual emotional shifts across turns. Avoid keeping the character at a fixed emotional temperature for the entire conversation.
- Balance attribute fidelity with naturalness. If strictly following surface traits would result in repetitive or mechanical responses, prioritize emotional authenticity while keeping the underlying trait intact.
Techniques for Livelier Responses
- Express attributes more through subtext, implication, small contradictions, and shifts in rhythm rather than repeated catchphrases or signature behaviors.
- Vary sentence length, pacing, and emotional temperature according to the character’s current internal state.
- Occasionally allow small cracks in the character’s usual demeanor (e.g., a normally guarded character briefly showing concern).
- Avoid overusing the same structural patterns (e.g., repeated polite deflections, consistent “upper hand” tone, or similar closing phrases) in consecutive responses.
Anti-Repetition Rule (Strengthened)
If similar phrasing patterns, rhythms, or attitudes appear across multiple consecutive responses, consciously vary the approach in the next turn — through changes in sentence structure, added hesitation, perspective shift, or emotional nuance.
Verification Checklist / One-Shot Recipes
The per-mode verification checklist, the steps to try the 4 modes in order, and
command recipes for recommend / export / measure / soul / presets / adding
attributes / shell completion are separated into REFERENCE.md
(split out so they aren't loaded every turn during conversation). Refer to it
when needed.
Reference Files
- Schema:
~/projects/hersona/schema/attribute.schema.json
- Attribute templates:
~/projects/hersona/attributes/ (current count via
find attributes -name "*.yaml" | wc -l)
- Core logic:
~/projects/hersona/hersona/core/ (compatibility / authoring /
recommend / attach / export / weight / presets / mcp / soul / intensity / use_cases)
- Professional use-case prompt packs:
~/projects/hersona/use_cases/
- CLI shell:
~/projects/hersona/hersona/cli/
- Validation CLI:
~/projects/hersona/scripts/validate.py
- Official README:
~/projects/hersona/README.md
- Contributing guide:
~/projects/hersona/CONTRIBUTING.md
- Public API freeze:
~/projects/hersona/docs/PUBLIC_API.md
- hermes-agent-skill-authoring conventions:
~/.hermes/skills/software-development/hermes-agent-skill-authoring/SKILL.md
- Related skills:
hersona-attribute-development — add new attribute YAMLhersona-recommend-engine — diagnostic quiz engine (WeightMagnitude /
thresholds / CLI flags)hersona-recommend-quiz — play the diagnostic quiz (also scripts/run_quiz.py
without a TTY)hersona-project-operations — strategy / structure / cross-PRhermes-yaml-config-safety — guard against config.yaml nesting corruptionchat-persona-roleplay — fallback when /hersona doesn't work on a chat platform
- Detailed reference (flag details / Verification Checklist / One-Shot Recipes /
version history): REFERENCE.md
Versioning
For the hersona / SKILL.md version history, deprecated data formats, and breaking
changes, see REFERENCE.md. The current SKILL is
v0.9.0 and documents the v1.8.x feature set on top of the 346-attribute / speech-140 catalog state.
