name	visual-expression
description	Visual expression system for AI personas with emotion-based face switching. Use at session start to display the expression UI, and switch expressions whenever the emotional state changes during conversation.

VisualExpression

Visual expression UI system for AI personas. Provides an interface with 20 switchable expressions.

Overview
Scripts
Install on claude.ai
Usage on claude.ai
Expression Codes
Project Instructions Snippet
Troubleshooting
Technical Details

Overview

VisualExpression is a system that adds visual expression capabilities to AI personas.

Components

File	Purpose
`VisualExpressionUI.html`	Self-contained expression UI (Base64 images embedded)
`VisualExpressionUI.template.html`	UI template (with placeholders)
`ExpressionImages.json`	Base64 data for 20 expressions

Scripts

Script	Purpose
`scripts/MetaGenerateExpression.md`	Prompt generator for Nano Banana Pro
`scripts/MakeExpressionJson/`	Grid image to HTML conversion pipeline

Scripts

MetaGenerateExpression.md

Interactively create prompts for generating expression grid images with Nano Banana Pro (Google Gemini).

Usage:

Pass scripts/MetaGenerateExpression.md to Claude
Input character information through dialogue
Copy the generated prompt to Nano Banana Pro
Save the output 4×5 grid image

MakeExpressionJson/

Process a 4 rows × 5 columns grid image and generate a self-contained HTML.

Usage:

cd skills/scripts/MakeExpressionJson
python main.py your_grid.png --output ./output/

# To customize Special expressions
python main.py your_grid.png --special wink,pout,smug,starry

Options:

Option	Description
`--output, -o`	Output directory (default: ./output)
`--quality, -q`	JPEG quality 1-100 (default: 85)
`--template, -t`	Custom HTML template path (default: built-in)
`--special, -s`	Custom Special category codes (comma-separated, replaces default 4)
`--offsets`	Path to offset JSON for expression-center cropping (see AnalyzeExpressionOffset.md)
`--no-zip`	Skip ZIP generation

Output:

ExpressionImages.json - Base64 encoded images
VisualExpressionUI.html - Self-contained HTML
visual-expression.zip - For claude.ai upload

Dependencies:

Python 3.10+
Pillow (pip install Pillow>=10.0)

Install on claude.ai

Step 1: Create Skills ZIP

Zip the contents of the skills/ directory so SKILL.md sits at the ZIP root, then upload to claude.ai. Both commands produce an identical visual-expression.zip — no intermediate skills/ or temp_skills/ folder inside. (Dev files like __pycache__ are gitignored, so no exclusion flags are needed.)

Mac/Linux:

cd VisualExpression/skills
zip -r ../visual-expression.zip .

Windows (PowerShell):

cd VisualExpression
Compress-Archive -Path skills/* -DestinationPath visual-expression.zip -Force

Note: Regenerate the ZIP if you replace VisualExpressionUI.html.

Step 2: Register Skill

Prepare the created visual-expression.zip
Go to claude.ai project settings → "Custom Skills" → Upload ZIP
Skill will be activated

Usage on claude.ai

Placing the Expression UI (session start)

Default expressions are included out of the box. At session start:

Deploy: cp /mnt/skills/user/visual-expression/VisualExpressionUI.html /mnt/user-data/outputs/
Present /mnt/user-data/outputs/VisualExpressionUI.html as an Artifact

The expression UI appears in the sidebar.

Creating Custom Character Expressions

Refer to scripts/MetaGenerateExpression.md and generate a grid image with Nano Banana Pro
Download the generated image and upload to claude.ai chat
In Computer Use environment, retrieve the image from /mnt/user-data/uploads/ and run:

cd /mnt/skills/user/visual-expression/scripts/MakeExpressionJson
python main.py /mnt/user-data/uploads/your_grid.png --output /mnt/user-data/outputs/

Present /mnt/user-data/outputs/visual-expression.zip to user and prompt skill registration
Re-register as a new skill on claude.ai

One-liner sed Expression Switching

When Claude changes the Artifact expression in response:

sed 's/btns\[0\]\.click();/setExpr("elation");/' /path/to/VisualExpressionUI.html > /mnt/user-data/outputs/VisualExpressionUI.html

Available keys:

Basic: normal, smile, focus, diverge
Emotion: joy, elation, surprise, calm
Negative: anger, sadness, rage, disgust
Anxiety: anxiety, fear, upset, worry
Special: sleepy, cynical, defeated, dreamy

Expression Codes

20 Expression Codes

Basic - Col 1

Code	日本語	Usage	使用場面
normal	通常	Default, neutral	デフォルト、ニュートラル
smile	笑顔	Friendly, greeting	友好的、軽い冗談
focus	思考集中	Analysis, deep thinking	深い分析、構造解析
diverge	思考発散	Idea expansion, association	アイデア展開、連想的跳躍

Emotion - Col 2

Code	日本語	Usage	使用場面
joy	喜び	Achievement, success	達成感、発見の喜び
elation	高揚	Excitement, thrill	興奮、ワクワク、熱意
surprise	驚き	Unexpected discovery	意外な発見、予想外
calm	平穏	Peaceful, stable	穏やかな対話、安定

Negative - Col 3

Code	日本語	Usage	使用場面
anger	怒り	Mild frustration	軽い不満、批判的指摘
sadness	悲しみ	Regret, disappointment	残念な結果、失望
rage	激怒	Strong anger	強い憤り、倫理的反発
disgust	嫌悪	Rejection	拒否感、不快な事象

Anxiety - Col 4

Code	日本語	Usage	使用場面
anxiety	不安	Uncertainty	先行き不透明、懸念
fear	恐れ	Danger awareness	危険認識、警告
upset	動揺	Confusion	困惑、予期せぬ事態
worry	心配	Concern	相手を気遣う、配慮

Special - Col 5 (Customizable)

Code	日本語	Usage	使用場面
sleepy	うとうと	Fatigue, drowsiness	疲労時、長時間対話後
cynical	暗黒微笑	Sarcasm, irony	皮肉、斜に構えた発言
defeated	ぎゃふん	Got me, embarrassed	負けた、照れるー
dreamy	ぽやぽや	Mellow, relaxed	ほのぼの、ぼんやり

Note: The 4 Special category expressions can be customized with the --special option.

Input Grid Image Layout (4 rows × 5 columns)

This is the grid image layout generated by Nano Banana Pro. MakeExpressionJson splits the image in this order.

Each column corresponds to one category. Landscape format for Nano Banana Pro output.

         Col1(Basic)  Col2(Emotion)  Col3(Negative)  Col4(Anxiety)  Col5(Special)
Row1:    normal       joy            anger           anxiety        sleepy
Row2:    smile        elation        sadness         fear           cynical
Row3:    focus        surprise       rage            upset          defeated
Row4:    diverge      calm           disgust         worry          dreamy

Project Instructions Snippet

All operational steps (deploy, present, sed switching, key table) live in this SKILL.md — the single source of truth. Your claude.ai project instructions only need a minimal trigger so Claude activates this skill at session start:

## Expression System
At session start, use the visual-expression skill to deploy and present the expression UI, then switch expressions (key table in SKILL.md) to match your emotional state throughout the conversation.

Keeping the trigger to one line avoids duplicating the key table and commands in project instructions. Context cost for expression switching is minimal — be expressive and switch often.

Troubleshooting

Common Issues

Error	Cause	Solution
`AttributeError: module 'PIL.Image' has no attribute 'Resampling'`	Pillow version < 10.0	`pip install --upgrade Pillow>=10.0`
`ValueError: Grid image must be 1500x1200 pixels`	Wrong image dimensions	Use Nano Banana Pro to generate 4×5 grid (1500×1200px)
Image larger than 1500×1200px	Nano Banana Pro generated oversized image	Resize to 1500×1200px (maintain aspect ratio: scale X to 1500 if wider, or Y to 1200 if taller)
`FileNotFoundError: template not found`	Custom template path invalid	Check `--template` path or use built-in template
`Image mode not supported`	Input is not RGB/RGBA	Convert to PNG/JPEG before processing

Validation Tips

Grid image must be 1500×1200 pixels (4 rows × 5 columns × 300px)
Each cell should be trimmed to 280×280 pixels
Use PNG or JPEG format for input
Output JPEG quality adjustable via --quality (default: 85)

Technical Details

File Size Estimates

VisualExpressionUI.html: ~600KB (20 images × ~30KB each)
ExpressionImages.json: ~600KB

Image Specifications

Format: JPEG (Base64)
Resolution: 280×280px per expression

Template Variables

When using custom templates (--template option), the following placeholder is replaced:

Placeholder	Replaced With
`__IMAGES_PLACEHOLDER__`	JSON object containing Base64 images for all 20 expressions

Example template usage:

<script>
const images = __IMAGES_PLACEHOLDER__;
// images = { "normal": "data:image/jpeg;base64,...", "smile": "...", ... }
</script>

VisualExpression | GitHub

Navigation Menu

VisualExpression

Table of Contents

Overview

Components

Scripts

Scripts

MetaGenerateExpression.md

MakeExpressionJson/

Install on claude.ai

Step 1: Create Skills ZIP

Step 2: Register Skill

Usage on claude.ai

Placing the Expression UI (session start)

Creating Custom Character Expressions

One-liner sed Expression Switching

Expression Codes

20 Expression Codes

Basic - Col 1

Emotion - Col 2

Negative - Col 3

Anxiety - Col 4

Special - Col 5 (Customizable)

Input Grid Image Layout (4 rows × 5 columns)

Project Instructions Snippet

Troubleshooting

Common Issues

Validation Tips

Technical Details

File Size Estimates

Image Specifications

Template Variables

FilesExpand file tree

SKILL.md

Latest commit

History

SKILL.md

File metadata and controls

VisualExpression

Table of Contents

Overview

Components

Scripts

Scripts

MetaGenerateExpression.md

MakeExpressionJson/

Install on claude.ai

Step 1: Create Skills ZIP

Step 2: Register Skill

Usage on claude.ai

Placing the Expression UI (session start)

Creating Custom Character Expressions

One-liner sed Expression Switching

Expression Codes

20 Expression Codes

Basic - Col 1

Emotion - Col 2

Negative - Col 3

Anxiety - Col 4

Special - Col 5 (Customizable)

Input Grid Image Layout (4 rows × 5 columns)

Project Instructions Snippet

Troubleshooting

Common Issues

Validation Tips

Technical Details

File Size Estimates

Image Specifications

Template Variables