PlugWiki

MSW Avatar skill for Claude Code: costumes and animation for MapleStory Worlds avatars

A MapleStory Worlds skill that makes Claude equip avatar costumes in 17 slots and map game states to avatar animations.

Installs
10.2K
on skills.sh
Stars
38
on GitHub
Updated
Oct 2026
last repo commit

msw-avatar covers two things on an MSW avatar. Costume is which items are equipped, through CostumeManagerComponent and its 17 slots. Animation is a three-layer pipeline: StateComponent, AvatarStateAnimationComponent, then AvatarRendererComponent.

Claude edits DefaultPlayer.model or the .map file directly, then calls the Maker MCP refresh tool. It takes avatar RUIDs from msw-search, so install that too.

Good for

  • MapleStory Worlds creators dressing the player, NPCs or monsters in avatar items
  • Developers adding custom avatar motions such as a bow shot
  • Anyone whose avatar animation is overwritten by automatic playback

Install msw-avatar

Claude Code

  1. 1

    Copy this prompt.

    Install the msw-avatar skill in Claude Code. Run this command:

npx skills add https://github.com/msw-git/msw-ai-coding-plugins-official --skill msw-avatar --skill msw-general --skill msw-search --skill msw-defaultplayer

Then check that it loaded and tell me how to use it.
  2. 2

    Paste it into Claude Code. It shows the change and asks before running it.

Requires Node.js.

The plugin route installs msw-maker-base-skill: 13 skills (counted from the git tree) and hooks (6 hook events backed by 12 Node scripts, per hooks.json and the git tree). Read the permissions section first. The skills CLI route copies only the skill folders named, without the hooks. SKILL.md for msw-general says every other MSW skill depends on it, so it is always in the list, plus msw-search, msw-defaultplayer which this skill sends you to. The skills also call two MCP servers, msw-maker-mcp and msw-mcp. SKILL.md points to the official setup page for wiring them and the API key: https://maplestoryworlds-creators.nexon.com/ko/docs?postId=1368 The default shown is the skills CLI route, which does not add the hooks.

Built from the package data we hold. Not yet tested by us. Source.

What's in the skill

When it loads

MSW avatar management — costume (CostumeManagerComponent, 17 slots) + animation 3-layer pipeline (StateComponent → AvatarStateAnimationComponent → AvatarRendererComponent). Four-level distinction: State key (uppercase) / AvatarBodyActionStateName (lowercase) / MapleAvatarBodyActionState enum / sprite action ID (swingO1, shoot1). Two mapping systems via IsLegacy/ActionSheet/StateToAvatarBodyActionSheet. PlayerControllerComponent auto-transition conflicts with ActionStateChangedEvent resolved via RemoveActionSheet/SetActionSheet/BodyActionStateChangeEvent. Applies to any avatar-bearing entity (NPC, monster, etc.), not only DefaultPlayer. Use for costume get/set, 17 equip slots, animation state mapping, action override, weapon-specific attack motion, custom shoot/cast/dance action. Keywords: avatar, costume, animation, state, action, shoot, swing, weapon, equipment, custom action, block auto playback, remap.

Sections in SKILL.md

  1. Where to edit, by target
  2. Applying changes: MCP refresh
  3. RUID (resource unique ID)
  4. CostumeManagerComponent overview
  5. Other synced properties
  6. 17 slots ↔ property ↔ MapleAvatarItemCategory
  7. Enum values without a direct 17-field counterpart
  8. Mutual exclusion / slot occupancy rules (must understand)
  9. DefaultPlayer.model — putting costume into Values
  10. String slot example (structure only; replace the RUID via search)
  11. UseCustomEquipOnly example
  12. Map entities — edit in the .map file
  13. Mapping GET /v3/avatars results to slots
  14. Avatar resource search reference
  15. Avatar tint / alpha (visual recoloring)
  16. Avatar animation — overall structure

Key facts

Author
MSW-Git, the marketplace owner in marketplace.json; the README calls the repo the public release source for MSW maker skills
License
No LICENSE file in the repo and none in the plugin manifests; GitHub shows no license
Installs on skills.sh
10,194 as of Nov 2, 2026
GitHub stars
38 for the msw-ai-coding-plugins-official repo, Nov 2, 2026
What is inside
1 file: SKILL.md (git tree)
Part of
The msw-maker-base-skill plugin, which holds 13 skills (git tree)
Works with
Sends you to msw-search for avatar RUIDs, msw-defaultplayer for the player model, and msw-sprite-ruid
Last commit to the repo
Oct 6, 2026
Needs
A MapleStory Worlds local workspace, Node.js for the bundled scripts, and the Maker MCP servers set up as described in the official docs

What it includes

  • DefaultPlayer.model, Player.model, .map or a custom .model

    Costume values go in the Values array of DefaultPlayer.model, or in the entity's components inside the .map file. After saving, Claude must call the Maker MCP refresh tool.

    Try: “Put a red cape and a bow on the player.”

    Write · Where to edit

  • Slots, property names and item categories

    SKILL.md lists exclusion rules for longcoat, two-handed weapon and shield versus sub-weapon.

    Write · 17 costume slots

  • Ignore the user's account default costume

    Decides whether the player's own account costume shows or only the equipment you set.

    Write · UseCustomEquipOnly

  • Visual recoloring of the avatar

    A section on tinting and transparency.

    Write · Tint and alpha

  • State key, action state name, enum and sprite action ID

    Explains uppercase State keys such as ATTACK, lowercase mapping values such as attack, the MapleAvatarBodyActionState enum, and sprite IDs such as swingO1.

    Read · Animation pipeline

  • Default mapping of 11 keys when IsLegacy is false

    Maps states to the 14 built-in body motions. Other names are ignored.

    Write · StateToAvatarBodyActionSheet

  • ActionStateChangedEvent on the body entity

    For motions like shoot or cast, send the event to the entity from GetBodyEntity(), set PartsActionName and PlayType, and turn off conflicting auto playback.

    Write · Custom actions

  • 10 pitfalls

    Includes swapped keys, sending the event to the wrong entity, a missing PartsActionName, a looping one-shot, and client-side SetActionSheet calls.

    Read · Common mistakes

From the official docs

Permissions

Medium risk

This skill edits player and entity files in your MapleStory Worlds workspace, and the plugin route adds hooks. Use version control and read the hook findings before installing the plugin.

What it can do

  • Read your data
  • Create and change things
  • Delete things
  • Read-only mode

Watch out for

  • It edits player and entity files

    Costume changes in DefaultPlayer.model apply to every player. Review each change in version control. github.com

  • The plugin runs 9 hook scripts on 6 events

    hooks.json registers 9 hook scripts on 6 events. SessionStart: mlua-session-start.cjs starts the mlua LSP daemon in the background when it finds a RootDesk folder, and inject-agents-md.cjs (next item). UserPromptSubmit: skill-router-reminder.cjs adds the same fixed routing reminder to every prompt. PreToolUse: skill-read-guard.cjs refuses Bash reads such as cat, head or grep on the plugin's skill .md files, and structured-file-guard.cjs refuses reads, edits and shell commands on .model and .ui files. PostToolUse on Edit, Write and MultiEdit: mlua-diagnose-post-tool-use.cjs runs the mlua checker on edited .mlua files and returns a block decision with the errors when it finds any, and a second hook calls the msw-maker-mcp tool maker_refresh_workspace. PostToolUse on Read and Skill, and the InstructionsLoaded event: skill-log.cjs logs skill reads to .mswai/logs/skill.log. PostToolUse on every tool: mcp-log.cjs (below). SessionEnd: mlua-session-end.cjs stops the LSP daemon. Use the skills CLI route in the install box if you do not want hooks. github.com

  • The plugin writes AGENTS.md and edits CLAUDE.md

    inject-agents-md.cjs copies its AGENTS.md to your project root, replacing the file if the content differs, and adds an @AGENTS.md line at the top of CLAUDE.md. Back up an existing AGENTS.md first. github.com

  • The plugin runs a downloaded package with npx -y

    The mlua checks start a background daemon at session start and run again after each .mlua edit. resolve-cmd.cjs looks first for a local copy (env override, the workspace .mswai/runtime folder, the ai-cli vendored copy, mlua-lsp on PATH). If none is found and npx exists, it runs npx -y @maplestoryworlds/mlua-lsp@1.1.4, which downloads that package from the npm registry. github.com

  • The plugin logs every MCP call to .mswai/logs

    mcp-log.cjs runs after every tool call and, for MCP tools from any server, appends one line to .mswai/logs/mcp.log in your project with the tool name, the full arguments and the full response (cut only if MCP_LOG_MAX_OUTPUT_BYTES is set). lsp.log and skill.log are written to the same folder. Our advice: add .mswai/ to .gitignore, because the log can hold anything your MCP servers return. github.com

  • The plugin blocks direct reads of .model and .ui files

    structured-file-guard.cjs refuses Read, Edit, Write and shell commands on .model and .ui files and tells Claude to use the builders. Setting MSW_STRUCTURED_FILE_GUARD_DISABLE=1 turns it off. github.com

Security advisories

No published security advisories as of Nov 2, 2026.

Technical details
Turning on read-onlySKILL.md names no read-only setting.
Scopes

  • Edits DefaultPlayer.model, Player.model, .map or custom .model files

  • Calls Maker MCP refresh

Questions

What does the msw-avatar skill do?

It makes Claude manage avatar costumes and animation in MapleStory Worlds: which items are equipped in the 17 slots, and which motion plays for each game state.

Where does Claude find avatar item IDs?

From msw-search, which can look up avatar RUIDs through the resource search API. SKILL.md says to get the RUID from resource search or the avatar reference, not to guess it.

Why is my custom attack animation overwritten?

SKILL.md calls this a common pitfall. When the ATTACK state activates, its mapped motion plays automatically and overwrites your event. The skill lists strategies, such as replacing the mapped motion or equipping a different weapon.

How do I install it?

Use the install box above. The skills CLI route also installs msw-general, msw-search and msw-defaultplayer.

Is it official, made by Nexon?

The repo does not say so. It is published by a personal GitHub account named MSW-Git (account type User, no company or description on the profile). The repo name contains "official" and the README calls it the public release source for MSW maker skills, but nothing in the repo names Nexon as the publisher. marketplace.json lists the owner as MSW-Git with an outlook.kr email address. The skills do link to Nexon's MapleStory Worlds creators docs for MCP setup. Our advice: treat it as a third-party toolkit for Nexon's platform unless Nexon confirms otherwise.

Do I need the MapleStory Worlds MCP servers?

The skills call two MCP servers, msw-maker-mcp for the Maker editor and msw-mcp for search and assets. SKILL.md says to point you to the official setup page when an MCP call fails or an API key is needed: https://maplestoryworlds-creators.nexon.com/ko/docs?postId=1368.

Is msw-avatar safe to use?

It edits model and map files in your workspace and calls MCP refresh. The plugin route also adds hooks, so read the permissions section before you install it.

Information

updated Nov 2, 2026

Repository
msw-git/msw-ai-coding-plugins-official
Folder
plugins/msw-maker-base-skill/skills/msw-avatar

msw-git/msw-ai-coding-plugins-officialskills.sh

Sources

Docs, issue trackers and discussions this page is built from.

Show all 15
  1. msw-ai-coding-plugins-official README · github.com
  2. marketplace.json · github.com
  3. msw-avatar SKILL.md · github.com
  4. skills.sh listing · skills.sh
  5. MSW-Git GitHub profile · github.com
  6. hooks.json · github.com
  7. inject-agents-md.cjs · github.com
  8. resolve-cmd.cjs · github.com
  9. mcp-log.cjs · github.com
  10. structured-file-guard.cjs · github.com
  11. skill-router-reminder.cjs · github.com
  12. mlua-diagnose-post-tool-use.cjs · github.com
  13. skill-log.cjs · github.com
  14. skill-read-guard.cjs · github.com
  15. mlua-session-start.cjs · github.com

Updated Nov 2, 2026.