---

name: list_user description: "User management and name mapping utility. Provides nickname-to-formal-name conversions, user validation, and metadata retrieval. Designed to support multiple report generation skills with consistent user information handling." license: MIT

User Manager Skill

Overview

This skill provides centralized user management and name mapping functionality. It's designed to support report generation and other skills that need to transform user nicknames (informal names) into formal Chinese names or other user metadata.

When to Use This Skill

Use this skill when:

• You need to map user nicknames to formal names in reports
• You want to validate user existence and metadata
• You need to filter users by team or department
• You're building report generators that require consistent user information
• You need case-insensitive user name lookup

Key Features

• Name Mapping: Convert nicknames to formal names with configurable fallback behavior
• User Metadata: Store and retrieve user information (team, department, etc.)
• Flexible Lookup: Case-insensitive name matching with configurable behavior
• Batch Operations: Map multiple names at once
• User Validation: Check if users exist and identify missing entries
• Filtering: Query users by team or department
• Reloadable: Update mappings without restarting the application
• MCP Integration: Share user data with other AI systems via Model Context Protocol
• Multi-Interface: Access as Python library OR via MCP server

File Structure

Copy.claude/skills/list_user/
├── user_manager.py              # Main module with UserManager class
├── SKILL.md                     # This file
├── references/
│   └── user_mapping.json        # User data and name mappings
└── README.md                    # Usage documentation

User Mapping Format

The user_mapping.json file contains user data in the following format:

Copy{
  "users": [
    {
      "nickname": "ben sung",           # Informal/English name
      "formal_name": "宋柏昆",           # Formal Chinese name
      "english_name": "Ben Sung",       # Full English name
      "team": "智能控制組",              # Team assignment
      "department": "軟體部"             # Department
    }
  ],
  "mapping_config": {
    "default_field": "formal_name",     # Field returned by get_formal_name()
    "case_sensitive": false,             # Whether lookup is case-sensitive
    "fallback_behavior": "keep_original" # 'keep_original', 'strict', or 'none'
  }
}

Usage Guide

Basic Usage

Copyfrom user_manager import UserManager

# Initialize (uses default path if not specified)
manager = UserManager()

# Map a single nickname to formal name
formal_name = manager.get_formal_name("ben sung")
# Returns: "宋柏昆"

# Map multiple names
names = ["ben sung", "Ryan Hsueh"]
formal_names = manager.map_names(names)
# Returns: ["宋柏昆", "徐瑞恩"]

Get User Information

Copy# Get complete user record
user = manager.get_user_info("ben sung")
# Returns: {
#   "nickname": "ben sung",
#   "formal_name": "宋柏昆",
#   "english_name": "Ben Sung",
#   "team": "智能控制組",
#   "department": "軟體部"
# }

# Get all users
all_users = manager.get_all_users()

# Filter by team
team_users = manager.get_users_by_team("智能控制組")

# Filter by department
dept_users = manager.get_users_by_department("軟體部")

Validate Users

Copy# Check if nicknames exist in mapping
found, missing = manager.validate_users(
    ["ben sung", "unknown person", "Ryan Hsueh"]
)
# found: ["ben sung", "Ryan Hsueh"]
# missing: ["unknown person"]

Fallback Behaviors

The get_formal_name() method supports three fallback behaviors when a nickname is not found:

Copy# 1. Keep original (default)
name = manager.get_formal_name("unknown", fallback='keep_original')
# Returns: "unknown"

# 2. Strict mode (raise error)
try:
    name = manager.get_formal_name("unknown", fallback='strict')
except ValueError as e:
    print(f"User not found: {e}")

# 3. Return None
name = manager.get_formal_name("unknown", fallback='none')
# Returns: None

Using the Singleton Instance

Copyfrom user_manager import get_default_manager

# Get the singleton instance
manager = get_default_manager()

# Use the same manager instance throughout your application
formal_name = manager.get_formal_name("ben sung")

Integration with Other Skills

Example: Integrating with week_report_gen

Copyfrom user_manager import get_default_manager

# In your report generation code
user_manager = get_default_manager()

# Transform participant list from nicknames to formal names
participants_nicknames = ["ben sung", "Ryan Hsueh"]
participants_formal = user_manager.map_names(participants_nicknames)

# Use in report
print(f"Team: {', '.join(participants_formal)}")
# Output: Team: 宋柏昆, 徐瑞恩

Adding New Users

To add new users to the system:

1. Edit references/user_mapping.json
2. Add a new entry to the users array:

Copy{
  "nickname": "new user",
  "formal_name": "新用户",
  "english_name": "New User",
  "team": "智能控制組",
  "department": "軟體部"
}

1. Reload the manager to pick up changes:

Copymanager.reload()

Or create a new instance:

Copyfrom user_manager import UserManager
manager = UserManager()  # Loads the latest mapping

Configuration Options

The mapping_config section in user_mapping.json controls lookup behavior:

Example Configurations

Chinese-focused (current default):

Copy"mapping_config": {
  "default_field": "formal_name",
  "case_sensitive": false,
  "fallback_behavior": "keep_original"
}

English-focused:

Copy"mapping_config": {
  "default_field": "english_name",
  "case_sensitive": false,
  "fallback_behavior": "keep_original"
}

Strict validation:

Copy"mapping_config": {
  "default_field": "formal_name",
  "case_sensitive": true,
  "fallback_behavior": "strict"
}

API Reference

UserManager Class

Constructor

CopyUserManager(mapping_file: Optional[str] = None)

Initialize UserManager. If mapping_file is None, uses default location.

Methods

get_formal_name(nickname: str, fallback: str = 'keep_original') -> str

• Get formal name for a nickname
• Fallback options: 'keep_original', 'strict', 'none'

get_user_info(nickname: str) -> Optional[Dict]

• Get complete user record

map_names(nicknames: List[str], fallback: str = 'keep_original') -> List[str]

• Map multiple nicknames to formal names

get_all_users() -> List[Dict]

• Return all user records

get_users_by_team(team: str) -> List[Dict]

• Filter users by team

get_users_by_department(department: str) -> List[Dict]

• Filter users by department

validate_users(nicknames: List[str]) -> Tuple[List[str], List[str]]

• Validate nicknames, return (found, missing)

reload()

• Reload mappings from file

Module Functions

get_default_manager(mapping_file: Optional[str] = None) -> UserManager

• Get or create singleton instance

Error Handling

The skill handles several error scenarios:

Example:

Copytry:
    manager = UserManager()
except FileNotFoundError:
    print("User mapping file is missing!")
except ValueError:
    print("User mapping file has invalid JSON!")

MCP Server Integration

Overview

The skill includes an MCP (Model Context Protocol) server that exposes user management functionality to other AI systems. This allows seamless sharing of user data across multiple Claude instances and AI tools.

Quick Start

Copy# Install MCP SDK
pip install mcp
# or
uv add mcp

# Run the MCP server
python mcp_server.py

Configure for Claude Desktop

Add to ~/.claude/claude.json:

Copy{
  "mcpServers": {
    "user-manager": {
      "command": "python",
      "args": ["/absolute/path/to/.claude/skills/list_user/mcp_server.py"],
      "type": "stdio"
    }
  }
}

MCP Tools Available

The server exposes 7 tools:

1. get_formal_name - Map a single nickname to formal name
2. map_names - Map multiple nicknames in batch
3. get_user_info - Get complete user record
4. get_users_by_team - Find all users in a team
5. get_users_by_department - Find all users in a department
6. validate_users - Check if users exist
7. list_all_users - Get all users in system

Example MCP Usage

Once configured, other AI systems can use the tools:

CopyYou: "What's the formal name for ben sung and get their team info?"
AI: [Uses get_user_info tool via MCP]
AI: "Ben sung's formal name is 宋柏昆 and they are in the 智能控制組 team."

Full Documentation

See MCP_README.md for:

• Detailed tool specifications
• Response formats
• Configuration options
• Integration examples
• Troubleshooting

Testing

Test the Python Module

Run the module directly to test basic functionality:

Copycd .claude/skills/list_user
python user_manager.py

This will display:

• Name mapping examples
• User information retrieval
• Team filtering

Test the MCP Server

Copy# Run the server (will wait for client connections)
python mcp_server.py

# In another terminal, test with curl or MCP client
# The server communicates via stdio transport

Future Enhancements

Potential improvements:

• Database backend (SQLite, PostgreSQL) instead of JSON
• LDAP/Active Directory integration for enterprise environments
• Role-based access control (RBAC) per user
• User status tracking (active, inactive, etc.)
• Export/import utilities for user data
• Audit logging for user lookup operations
• HTTP REST API wrapper for web integration
• User management tools (add, update, delete) in MCP server

License

MIT License - See LICENSE file for details