WorkBuddy User Guide

Problems It Solves

WorkBuddy is a feature-rich AI workspace integrating connectors, experts, automation, Teams collaboration, human-machine co-editing, and more. Users often encounter specific pain points during usage:

• Configuration and Connection Failures: Connector errors (e.g., error codes 1001, 3002), incompatible environments, or proxy settings preventing tool invocation.
• Unclear Feature Usage: Lack of clarity on creating experts, setting up automation tasks, using human-machine co-editing for documents, or operating the data library and design creative functions.
• Onboarding Barriers for Beginners: No clear starting path amidst numerous features, leading to confusion during initial setup.
• Suboptimal AI Behavior: Inaccurate AI responses, formatting issues, or irrelevant answers, requiring personalization without knowing the methods.
• Inefficient Troubleshooting: Attempts to resolve issues often fail without a systematic diagnostic process.

How the Skill Works

This guide acts as a reference manual for WorkBuddy, employing core capabilities and key steps to address these problems:

Core Capability: Layered Retrieval and Structured Knowledge

• Three-Layer Retrieval System: Starts with quick cards in references/05-quick-cards.md, progresses to deep documents (e.g., references/troubleshooting.md), and finally references official documentation. This avoids overwhelming beginners with lengthy texts.
• Keyword Quick-Reference Table: Maps natural language queries to technical keywords and corresponding documents. For example, "can't connect" maps to MCP failure, automatically matching to references/02-connector-troubleshooting.md.
• Integrated Diagnostic Tools: Provides scripts/check_env.py for one-click environment checks (proxy, connectors, experts), supporting --fix for auto-repairing JSON and proxy configurations, and --collect-logs for exporting sanitized snapshots for deep analysis.
• Auto-Matching Trigger Rules: When WorkBuddy-related issues are mentioned in conversation (e.g., feature names, errors, configurations), the manual loads automatically. It covers 14 scenarios, including connector failures, expert creation, and automation setup.

Key Steps: From Problem to Solution

1. Problem Identification and Matching: Users describe an issue (e.g., "connector error 401"), and the system loads relevant reference files based on trigger rules (e.g., Scenario 2: describing WorkBuddy errors).
2. Step-by-Step Troubleshooting: Follows a tiered repair path—for instance, in references/02-connector-troubleshooting.md, first check Level 1 fix (common cause: proxy not running), then Level 2 fix (verify API credentials), and finally validate (run check_env.py).
3. Personalized Configuration: Uses the Soul.md system to define AI behavior with a chat-based step-by-step guide (asking only one question at a time):
   - Defines six rules covering core personality, speaking style, work principles, etc.
   - For example, setting "disable pleasantries" to reduce AI-like responses, or "one-shot confirmation" for efficiency.
4. Advanced Scenario Support:
   - Automation Tasks: Refer to the RRULE template library in references/04-automation-patterns.md to set scheduled tasks (e.g., daily backups).
   - Team Collaboration: Use references/13-teams-collaboration.md to configure project boards and task workflows.
   - Multi-Device Sync: Check operations like phone remote control to computer or lock-screen remote in references/10-interaction-modes.md.
5. Official Documentation Retrieval: When reference files are insufficient, use WebFetch to actively query links like https://www.codebuddy.cn/docs/workbuddy/Overview for the latest information.

Application Boundaries and Caveats

This guide is designed as read-only reference focused on usage guidance. The following cases are out of scope:

• Pure Programming Issues: E.g., writing functions or debugging code—should be handled directly by AI without passing through this manual.
• Modifying Skill Files Themselves: Requires exiting this skill and requesting AI to edit files directly.
• Version Update Log Details: Documentation may lag; it's recommended to use WebFetch to check the official Changelog.
• Specific Connector API Details: Connector docs are self-described by MCP tools; you can query AI directly.
• Non-Reproducible One-Time Failures: Run check_env.py to obtain a diagnostic report and submit it to AI for analysis.

Handling Ambiguous Issues: For example, if a user says "WorkBuddy is slow," the system first asks clarifying questions to distinguish between network lag, slow response, or too many files, then provides targeted troubleshooting paths. This ensures each interaction focuses on one specific problem without dumping all possibilities.

Usage Principles:
- Retrieval Priority: Quick cards → deep documents → official documents, without skipping layers.
- Read Granularity: Use scripts/quick-search.sh to grep keywords first, then read paragraphs, avoiding full-file loading.
- Update Maintenance: Append troubleshooting experiences to the "Pitfall Experiences" section of corresponding files to keep the manual practical.