Skip to content
Skills Library
AI & agents · Tool integration

visual-expression

/visual-expression

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.

Licence
MIT
Last repository change
04.10.2026

Assessment and security

95/ 100Class: good
Format20 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
49
Scripts
40
HTML comments
0
URLs in SKILL.md
1
Deprecation

No signals detected. Repository changed on 04.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What to check before installing
  • 40 scripts in this package. Review them before installing, as Claude may execute them.

Scripts: scripts/MakeExpressionJson/__init__.py, scripts/MakeExpressionJson/adapters/__init__.py, scripts/MakeExpressionJson/adapters/file_constants.py, scripts/MakeExpressionJson/adapters/file_writer.py, scripts/MakeExpressionJson/adapters/protocols.py, scripts/MakeExpressionJson/adapters/skills_locator.py, scripts/MakeExpressionJson/adapters/zip_packager.py, scripts/MakeExpressionJson/domain/__init__.py,

What it does and when to use it

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.

Original author 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.

How it works

  1. Table of Contents
  2. Overview
  3. Scripts
  4. Install on claude.ai
  5. Usage on claude.ai
  6. Expression Codes
  7. Project Instructions Snippet
  8. Troubleshooting
  9. Technical Details
Original SKILL.md headings · 280 lines, 1,301 words
SKILL.md preview
---
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.

## Table of Contents

- [Overview](#overview)
- [Scripts](#scripts)
- [Install on claude.ai](#install-on-claudeai)
- [Usage on claude.ai](#usage-on-claudeai)
- [Expression Codes](#expression-codes)
- [Project Instructions Snippet](#project-instructions-snippet)
- [Troubleshooting](#troubleshooting)
- [Technical Details](#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:**
1. Pass `scripts/MetaGenerateExpression.md` to Claude
2. Input character information through dialogue
3. Copy the generated prompt to Nano Banana Pro
4. Save the output 4×5 grid image

### MakeExpressionJson/

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

**Usage:**
```bash
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:**
```bash
cd VisualExpression/skills
zip -r ../visual-expression.zip .
```

**Windows (PowerShell):**
```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

1. Prepare the created `visual-expression.zip`
2. Go to claude.ai project settings → "Custom Skills" → Upload ZIP
3. 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:

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

The expression UI appears in the sidebar.

### Creating Custom Character Expressions

1. Refer to `scripts/MetaGenerateExpression.md` and generate a grid image with Nano Banana Pro
2. Download the generated image and upload to claude.ai chat
3. In Computer Use environment, retrieve the image from `/mnt/user-data/uploads/` and run:
```bash
cd /mnt/skills/user/visual-expression/scripts/MakeExpressionJson
python main.py /mnt/user-data/uploads/your_grid.png --output /mnt/user-data/outputs/
```
4. Present `/mnt/user-data/outputs/visual-expression.zip` to user and prompt skill registration
5. Re-register as a new skill on claude.ai

### One-liner sed Expression Switching

When Claude changes the Artifact expression in response:

```bash
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:

```markdown
## 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:
```html
<script>
const images = __IMAGES_PLACEHOLDER__;
// images = { "normal": "data:image/jpeg;base64,...", "smile": "...", ... }
</script>
```

---

**VisualExpression** | [GitHub](https://github.com/Bizuayeu/Plugins-Weave)
Files in this package (49)
  • ExpressionImages.json 613 KB
  • SKILL.md 10 KB
  • VisualExpressionUI.html 618 KB
  • VisualExpressionUI.template.html 5 KB
  • scripts/AnalyzeExpressionOffset.jp.md 6 KB
  • scripts/AnalyzeExpressionOffset.md 5 KB
  • scripts/MetaGenerateExpression.jp.md 6 KB
  • scripts/MetaGenerateExpression.md 6 KB
  • scripts/MakeExpressionJson/__init__.py 1 KB
  • scripts/MakeExpressionJson/main.py 7 KB
  • scripts/MakeExpressionJson/py.typed 1 KB
  • scripts/MakeExpressionJson/adapters/__init__.py 1 KB
  • scripts/MakeExpressionJson/adapters/file_constants.py 1 KB
  • scripts/MakeExpressionJson/adapters/file_writer.py 3 KB
  • scripts/MakeExpressionJson/adapters/protocols.py 2 KB
  • scripts/MakeExpressionJson/adapters/skills_locator.py 3 KB
  • scripts/MakeExpressionJson/adapters/zip_packager.py 4 KB
  • scripts/MakeExpressionJson/domain/__init__.py 1 KB
  • scripts/MakeExpressionJson/domain/builders.py 4 KB
  • scripts/MakeExpressionJson/domain/definitions.py 3 KB
  • scripts/MakeExpressionJson/domain/grid_layout.py 4 KB
  • scripts/MakeExpressionJson/domain/models.py 1 KB
  • scripts/MakeExpressionJson/domain/validators.py 3 KB
  • scripts/MakeExpressionJson/tests/__init__.py 1 KB
  • scripts/MakeExpressionJson/tests/conftest.py 2 KB
  • scripts/MakeExpressionJson/tests/test_base64_encoder.py 3 KB
  • scripts/MakeExpressionJson/tests/test_constants.py 11 KB
  • scripts/MakeExpressionJson/tests/test_error_cases.py 5 KB
  • scripts/MakeExpressionJson/tests/test_file_constants.py 3 KB
  • scripts/MakeExpressionJson/tests/test_grid_layout.py 5 KB
  • scripts/MakeExpressionJson/tests/test_gridconfig_removal.py 2 KB
  • scripts/MakeExpressionJson/tests/test_html_builder.py 8 KB
  • scripts/MakeExpressionJson/tests/test_import_structure.py 1 KB
  • scripts/MakeExpressionJson/tests/test_integration.py 6 KB
  • scripts/MakeExpressionJson/tests/test_main.py 4 KB
  • scripts/MakeExpressionJson/tests/test_main_cli.py 2 KB
  • scripts/MakeExpressionJson/tests/test_main_errors.py 9 KB
  • scripts/MakeExpressionJson/tests/test_main_zip.py 3 KB
  • scripts/MakeExpressionJson/tests/test_module_structure.py 5 KB
  • scripts/MakeExpressionJson/tests/test_protocols.py 5 KB
  • scripts/MakeExpressionJson/tests/test_skills_locator.py 8 KB
  • scripts/MakeExpressionJson/tests/test_splitter.py 11 KB
  • scripts/MakeExpressionJson/tests/test_validators.py 6 KB
  • scripts/MakeExpressionJson/tests/test_zip_packager.py 4 KB
  • scripts/MakeExpressionJson/usecases/__init__.py 1 KB
  • scripts/MakeExpressionJson/usecases/base64_encoder.py 2 KB
  • scripts/MakeExpressionJson/usecases/html_builder.py 3 KB
  • scripts/MakeExpressionJson/usecases/image_splitter.py 5 KB
  • scripts/MakeExpressionJson/usecases/protocols.py 3 KB

Versions

The database has no other skills named visual-expression.

Database snapshot: 13.11.2026 · package version 3ba9a29efbb0 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100langchain-expression-language-chains
    Use this skill when composing modular, streaming, and inspectable LLM invocation pipelines using LangChain Expression Language.
  • 85character-sim
    Speak as a specified character from their current knowledge, voice, and emotional state. Use for skill-only workflows that need in-character conversation, voice discovery, or relationship pressure tests.
  • 100n8n-expression-syntax
    Validate n8n expression syntax and fix common errors. Use when writing n8n expressions, using {{}} syntax, accessing $json/$node variables, troubleshooting expression errors, or working with webhook data in workflows.
  • 100n8n-expression-syntax
    Validate n8n expression syntax and fix common errors. Use when writing n8n expressions, using {{}} syntax, accessing $json/$node variables, troubleshooting expression errors, or working with webhook data in workflows.
  • 100qe-n8n-expression-testing
    n8n expression syntax validation, context-aware testing, common pitfalls detection, and performance optimization. Use when validating n8n expressions and data transformations.
  • 100visual-interest-expression
    This skill should be used when the user is defining brand personality in design, choosing between illustration and photography, adding motion or animation, creating visual motifs, ensuring layout variety, customizing CSS framework defaults, or calibrating the level of creative…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.