When to use this skill

Use this skill when you need to:

Design new bot commands and syntax
Implement command parsing and validation
Create help and documentation systems
Handle command errors gracefully
Design multi-parameter command formats
Implement command aliases and shortcuts
Build hierarchical help menus

How to use it

Command Design Principles

Prefix Convention: Use @ to distinguish bot commands
Simple Syntax: Keep commands short and memorable
Clear Feedback: Always respond with success/error messages
Help System: Provide comprehensive, contextual help
Validation: Validate inputs before processing

Command Categories

Query Commands (Read-Only)

Commands that display information without modifying state:

@schedule # View broadcast schedule @members # View member rotation table @help # Show help menu @help schedule # Show specific help topic

Implementation Pattern:

if command == 'schedule': schedule_info = get_group_schedule_for_display(group_id) reply_text = format_schedule_display(schedule_info)

elif command == 'members': reply_text = get_member_schedule_summary(group_id)

elif command == 'help': topic = args[0] if args else None reply_text = get_help_message(topic)

Configuration Commands (Settings)

Commands that modify group settings:

@time 18:00 # Set broadcast time @day mon,wed,fri # Set broadcast days @cron mon,thu 20 15 # Set days and time together

Implementation Pattern:

elif command == 'time': if not args: reply_text = "❌ 請指定時間，例如：@time 18:00" else: try: time_str = args[0] hour, minute = parse_time(time_str)

        # Update schedule
        if group_id not in group_schedules:
            group_schedules[group_id] = {}
        group_schedules[group_id]['hour'] = hour
        group_schedules[group_id]['minute'] = minute
        save_group_schedules(group_schedules)
        
        reply_text = f"✅ 推播時間已設為 {hour:02d}:{minute:02d}"
    except ValueError as e:
        reply_text = f"❌ 時間格式錯誤：{e}"

def parse_time(time_str): """Parse time string HH:MM""" parts = time_str.split(':') if len(parts) != 2: raise ValueError("請使用 HH:MM 格式，例如 18:00")

hour = int(parts[0])
minute = int(parts[1])

if not (0 &#x3C;= hour &#x3C;= 23):
    raise ValueError("小時必須在 0-23 之間")
if not (0 &#x3C;= minute &#x3C;= 59):
    raise ValueError("分鐘必須在 0-59 之間")

return hour, minute

3. Data Management Commands

Commands that modify member data:

@week 1 Alice,Bob # Set week 1 members @addmember 1 Charlie # Add member to week 1 @removemember 1 Alice # Remove member from week 1 @clearweek 1 # Clear week 1 @reset # Reset all data (dangerous!)

Implementation Pattern:

elif command == 'week': if len(args) < 2: reply_text = "❌ 格式：@week 週數成員1,成員2\n例如：@week 1 小明,小華" else: try: week_num = int(args[0]) members_str = args[1] members = [m.strip() for m in members_str.split(',')]

        result = update_member_schedule(week_num, members, group_id)
        
        if result['success']:
            reply_text = f"✅ {result['message']}"
        else:
            reply_text = f"❌ {result['message']}"
    except ValueError:
        reply_text = "❌ 週數必須是數字"

Help System Design

Main Help Menu

def get_help_message(topic=None): """ Get help message for specific topic or general help

Args:
    topic: Help topic (schedule, members, groups) or None for main menu
"""
if topic is None:
    return """

📖 垃圾輪值提醒 Bot 使用指南

🔍 查詢指令： @schedule - 查看本群組推播排程 @members - 查看本群組完整輪值表

⚙️ 排程設定： @time 18:30 - 設定本群組推播時間 @day mon,thu - 設定本群組推播星期 @cron tue,fri 20 15 - 同時設定星期和時間

👥 成員管理： @week 1 Alice,Bob - 設定第1週成員 @addmember 1 Charlie - 添加成員到第1週 @removemember 1 Alice - 從第1週移除成員

💡 詳細說明： @help schedule - 排程管理指令說明 @help members - 成員管理指令說明 @help groups - 群組管理指令說明 """

elif topic == 'schedule':
    return """

⚙️ 排程管理指令詳細說明

📅 查看排程： @schedule 顯示本群組的推播時間、星期和下次執行時間

⏰ 設定推播時間： @time 18:00 設定每天推播的時間（24小時制）

📆 設定推播星期： @day mon,wed,fri 設定一週中哪幾天要推播可用的星期：mon, tue, wed, thu, fri, sat, sun

🔧 一次設定時間和星期： @cron mon,thu 20 15 等同於：@day mon,thu + @time 20:15

💡 範例： @time 09:00 → 設定每天 09:00 推播 @day mon,wed,fri → 設定週一三五推播 @cron tue,thu 17 30 → 設定週二四 17:30 推播 """

elif topic == 'members':
    return """

👥 成員管理指令詳細說明

📋 查看成員： @members 顯示所有週次的成員安排和目前是第幾週

➕ 設定週次成員： @week 1 小明,小華設定第1週由小明和小華負責如果該週已有成員，會被新成員取代

✏️ 添加成員到週次： @addmember 2 小強將小強加入第2週（不會覆蓋原有成員）

➖ 移除週次成員： @removemember 1 小明將小明從第1週移除

🗑️ 清空週次： @clearweek 2 清空第2週的所有成員

💡 範例： @week 1 Alice,Bob → 第1週：Alice, Bob @week 2 Charlie → 第2週：Charlie @addmember 1 David → 第1週：Alice, Bob, David @removemember 1 Bob → 第1週：Alice, David """

elif topic == 'groups':
    return """

🏢 多群組功能說明

本 Bot 支援同時管理多個群組，每個群組都有獨立的： • 成員輪值表 • 推播時間設定 • 推播星期設定

🤖 自動群組管理： • Bot 加入群組時會自動記錄 • Bot 離開群組時會自動清理資料 • 每個群組的排程完全獨立運作

📊 群組資料隔離： • A群組的成員設定不會影響B群組 • A群組設定週一推播，B群組可設定週二推播 • 所有指令都只影響當前群組

💡 最佳實踐：

在每個群組中分別設定推播時間
使用 @schedule 確認設定正確
使用 @members 查看當前群組輪值表 """

else:

    return f"❌ 未知的說明主題：{topic}\n\n使用 @help 查看可用主題"

2. Contextual Help

Provide help when users make mistakes:

Missing arguments

if len(args) < 2: reply_text = ( "❌ 參數不足\n\n" "正確格式：@week 週數成員1,成員2\n" "範例：@week 1 小明,小華\n\n" "使用 @help members 查看詳細說明" )

Invalid format

except ValueError: reply_text = ( "❌ 格式錯誤\n\n" "時間格式：HH:MM (24小時制)\n" "範例：@time 18:00\n\n" "使用 @help schedule 查看詳細說明" )

Input Validation

Number Validation

def validate_week_number(week_str): """Validate week number input""" try: week_num = int(week_str) if week_num < 1: raise ValueError("週數必須大於 0") return week_num except ValueError as e: raise ValueError(f"週數必須是正整數：{e}")

Time Validation

def validate_time(time_str): """Validate time string HH:MM""" if ':' not in time_str: raise ValueError("請使用 HH:MM 格式")

parts = time_str.split(':')
if len(parts) != 2:
    raise ValueError("請使用 HH:MM 格式")

hour, minute = int(parts[0]), int(parts[1])

if not (0 &#x3C;= hour &#x3C;= 23):
    raise ValueError("小時必須在 0-23 之間")
if not (0 &#x3C;= minute &#x3C;= 59):
    raise ValueError("分鐘必須在 0-59 之間")

return hour, minute

3. Day Validation

def validate_days(days_str): """Validate days string""" valid_days = {'mon', 'tue', 'wed', 'thu', 'fri', 'sat', 'sun'} days = [d.strip().lower() for d in days_str.split(',')]

invalid = [d for d in days if d not in valid_days]
if invalid:
    raise ValueError(
        f"無效的星期：{', '.join(invalid)}\n"
        f"可用的星期：{', '.join(sorted(valid_days))}"
    )

return days

Best Practices

Consistent Prefix

Always use @ for commands
Makes it clear what's a command vs normal chat

Short Memorable Names

@schedule not @show_schedule_information
@time not @set_broadcast_time

Progressive Disclosure

Main help shows overview
Topic help shows details
Error messages show examples

Emoji Usage

✅ for success
❌ for errors
📅, 🗑️, 👥 for visual categorization
Helps scanning/readability

Multi-Language Support (Optional)

LANG = os.getenv('BOT_LANGUAGE', 'zh-TW')

MESSAGES = { 'zh-TW': { 'help_title': '📖 使用指南', 'success': '✅ 設定成功', # ... }, 'en-US': { 'help_title': '📖 Help Guide', 'success': '✅ Success', # ... } }

Testing Commands

Test command parsing

test_inputs = [ ("@time 18:00", "time", ["18:00"]), ("@week 1 Alice,Bob", "week", ["1", "Alice,Bob"]), ("@help schedule", "help", ["schedule"]), ]

for input_text, expected_cmd, expected_args in test_inputs: parts = input_text[1:].split() command = parts[0].lower() args = parts[1:] if len(parts) > 1 else []

assert command == expected_cmd
assert args == expected_args

Reference Links

See main.py for full command implementations
See README.md for user-facing command documentation

command-design

Safety Notice

Copy this and send it to your AI assistant to learn

Missing arguments

Invalid format

Test command parsing

Source Transparency

Related Skills

deployment-railway

multi-group-architecture

scheduling-system