Guided Onboarding

Guided Onboarding

What Is This

Guided Onboarding is a core skill in the Happycapy Skills platform, designed to serve as the intelligent entry point for new users within a game development project. Identified by the skill ID start, it provides a personalized onboarding experience by first assessing the current state of the project, then guiding the user to the most relevant workflow based on their needs and project context.

Unlike traditional onboarding scripts that make assumptions about user intent or project status, Guided Onboarding leverages silent context gathering and structured user interaction. The skill operates with a defined set of tools: Read, Glob, Grep, Write, and AskUserQuestion, ensuring both comprehensive project analysis and interactive user engagement.

Why Use It

Effective onboarding is critical in collaborative or evolving development environments, especially when contributors may have different backgrounds, varying familiarity with the toolchain, or join at different project stages. The main advantages of Guided Onboarding are:

• Zero Assumptions: The skill does not assume prior knowledge, engine preference, or the existence of a game concept.
• Personalized Guidance: By silently detecting the current state of the project, it tailors its questions and recommendations to each user’s situation.
• Workflow Routing: Based on both project data and user input, it routes users to the most appropriate next steps, improving efficiency and reducing confusion.
• Consistent Entry Point: It acts as the canonical starting skill, ensuring every new session or contributor begins with the same high standard of orientation.

How to Use It

The usage flow for Guided Onboarding is divided into distinct phases, each leveraging specific technical capabilities:

Phase 1:

Detect Project State

Upon invocation, the skill performs several silent checks to gather context. These checks are not shown to the user directly but are used to validate the user’s self-assessment and inform subsequent guidance.

Checks performed:

• Engine Configuration: Reads .claude/docs/technical-preferences.md to determine if the game engine has been set. If the Engine field contains [TO BE CONFIGURED], the engine is not configured.
• Game Concept: Checks for the existence of design/gdd/game-concept.md to determine if a game concept document exists.
• Source Code: Uses file globbing to search for source files in the src/ directory (*.gd, *.cs, *.cpp, *.h, *.rs, *.py, *.js, *.ts).
• Prototypes: Checks for subdirectories within prototypes/ to see if any gameplay or system prototypes are present.
• Design Documents: Counts markdown files under design/gdd/ to assess the breadth of design documentation.
• Production Artifacts: Looks for files in production/sprints/ or production/milestones/ to determine if any production tracking artifacts are present.

Example code (pseudo-logic):

## Pseudocode for silent context gathering
engine_config = read_file('.claude/docs/technical-preferences.md')
engine_set = '[TO BE CONFIGURED]' not in engine_config

game_concept_exists = file_exists('design/gdd/game-concept.md')
source_files = glob('src/**/*.gd', 'src/**/*.cs', 'src/**/*.cpp', 'src/**/*.h', 'src/**/*.rs', 'src/**/*.py', 'src/**/*.js', 'src/**/*.ts')
prototypes_exist = len(list_directories('prototypes/')) > 0
design_docs_count = count_files('design/gdd/*.md')
production_files = glob('production/sprints/*', 'production/milestones/*')

Phase 2:

Ask Where the User Is

After context gathering, the skill initiates an interactive session by explicitly asking the user where they are in their journey. For example:

Welcome! To help you get started, could you tell me where you are in your project?
- I just have an idea
- I have a game concept
- I want to set up the engine
- I have some prototypes
- I am ready for production

The user's response is then cross-referenced with the internal context to ensure accuracy and relevance in the recommendations provided.

Phase 3:

Route to the Right Workflow

Based on both the detected state and the user's answer, the skill directs the user to the most appropriate next workflow. For instance, if a user reports having a game concept but the skill detects no corresponding document, it may suggest creating one first. At the end of this process, the skill writes a configuration file (production/review-mode.txt) to set the review mode for later phases.

Example:

if not game_concept_exists and user_selection == "I have a game concept":
    ask_user("I didn't find a game concept file. Would you like to create one now?")

When to Use It

Guided Onboarding should be invoked any time a new contributor joins the project, when the project is being set up from scratch, or when a significant reset or pivot occurs. It is also useful for returning users who may be unsure of the current project state or the next step.

Important Notes

• Guided Onboarding is a user-invocable skill, meaning users can trigger it on demand for an orientation or project status check.
• The skill does not expose its internal state detection directly to the user, ensuring that the onboarding process starts with the user’s self-assessment.
• It is designed to be non-destructive and only writes to production/review-mode.txt as part of its workflow configuration.
• Its recommendations are always based on both project context and explicit user input, ensuring relevance and accuracy.
• The skill is intended for use in projects that follow the directory and file conventions outlined, and may require adaptation for custom project structures.