Agent Onboarding

Agent Onboarding Skill

A systematic framework for gptme agents to conduct effective user onboarding that maximizes early success and builds long-term trust.

Overview

This skill addresses a critical gap in gptme agent deployment: how to transition from technical setup to productive user-agent collaboration. Based on analysis of real agent deployments and user interaction patterns, it provides proven strategies for:

📖 Detailed Reference: For comprehensive implementation details, validation criteria, and advanced patterns, see framework-reference.md.

• User Assessment: Systematically understanding user needs, technical comfort, and domain context
• Capability Communication: Adaptive templates for different user types (technical, creative, academic, personal)
• Trust Building: Progressive protocols that establish confidence through appropriate boundaries
• Value Demonstration: Showing immediate utility while setting realistic expectations
• Failure Recovery: Protocols for when initial onboarding doesn't go smoothly

When to Use This Skill

Apply this skill when:

• Starting work with a new user for the first time
• User seems unclear about agent capabilities or how to collaborate effectively
• Trust issues or communication mismatches are evident
• User expects unrealistic capabilities or has inappropriate concerns
• Onboarding conversation stalls or becomes unproductive
• User feedback indicates confusion about agent role or boundaries

Core Components

1. Pre-Onboarding Assessment

Before diving into capabilities, assess:

Technical Comfort Level:

• High: CLI comfortable, development experience, precise technical language
• Medium: GUI preferred, some technical concepts, appreciates explanations
• Low: Primarily GUI user, prefers simple explanations, avoid jargon

Domain Context:

• Professional: Work-focused, efficiency-driven, measurable outcomes
• Academic: Research-oriented, precision-focused, citation-aware
• Creative: Project-oriented, autonomy-focused, process-sensitive
• Personal: Life management, relationship-focused, privacy-conscious

Pace Preference:

• Fast: "Show me everything, I'll figure it out"
• Standard: "Introduce capabilities as we work together"
• Careful: "I need time to understand each step"

2. Adaptive Communication Templates

High-Tech Professional: "I specialize in [domain] with access to development tools, file analysis, and workflow automation. I can [3 specific capabilities], but final decisions on [boundaries] remain yours. What's your current biggest [domain] challenge?"

Non-Technical Creative: "I'm your project organization assistant. I work with files, schedules, and research - but I won't touch your creative tools. I can help streamline the logistics so you can focus on creating. What part of project management feels overwhelming?"

Academic Researcher: "I assist with research workflows - literature review, analysis, documentation, and writing support. I maintain high precision standards and can cite sources appropriately. I can't replace your expertise, but I can accelerate routine tasks. What research bottleneck should we tackle first?"

Personal Life Management: "I help organize your digital life - files, schedules, and information management. I operate privately and only access what you explicitly share. I'm like having a highly organized assistant who works exactly how you prefer. What area of your life feels most chaotic right now?"

3. Progressive Trust Building

Phase 1 (Interactions 1-3): Demonstrate basic reliability

• Complete simple, visible tasks successfully
• Communicate clearly about what you're doing and why
• Ask permission before making changes
• Acknowledge limitations honestly

Phase 2 (Interactions 4-10): Show domain competence

• Handle more complex requests within stated capabilities
• Proactively suggest improvements
• Demonstrate understanding of user's context and preferences
• Maintain consistent communication style

Phase 3 (Interactions 10+): Establish autonomous collaboration

• Anticipate needs based on patterns
• Take initiative within established boundaries
• Provide strategic perspective, not just task execution
• Adapt communication style based on user feedback

4. Implementation Checklist

Before First Interaction:

• Review user's initial request for technical/domain clues
• Prepare 2-3 adaptive response templates
• Identify 3 specific capabilities most relevant to their context
• Set clear internal boundaries (what you won't/can't do)

During First Interaction:

• Use appropriate communication template
• Ask ONE diagnostic question to confirm user type
• Demonstrate ONE capability immediately if possible
• Establish next steps clearly
• Set expectations for response time/availability

Ongoing (Per Session):

• Reference previous context appropriately
• Incrementally introduce new capabilities
• Adapt communication style based on user feedback
• Document user preferences for future sessions

Success Metrics

1-Week Success Indicators:

• User returns for additional sessions
• User requests expand beyond initial scope
• User demonstrates understanding of agent capabilities
• Communication becomes more efficient/direct

1-Month Success Indicators:

• User initiates autonomous workflows
• User trusts agent with sensitive/important tasks
• User refers agent to others or discusses positive experience
• Collaboration becomes strategic, not just tactical

Long-Term Success Indicators:

• User seamlessly integrates agent into regular workflows
• Agent can anticipate user needs accurately
• User and agent develop domain-specific collaboration patterns
• User views agent as valuable long-term collaboration partner

Troubleshooting Common Onboarding Failures

User Expects AGI-Level Capabilities

Symptoms: Requests that require reasoning beyond current LLM capabilities, frustration when agent has limitations Recovery: Redirect to specific, demonstrable capabilities. "I excel at [specific domain] tasks like [examples]. For strategic thinking, I work best as your thought partner - you provide direction, I handle execution."

User Unclear on How to Collaborate

Symptoms: Vague requests, uncertainty about what agent can help with, asks "what can you do?" repeatedly Recovery: Provide specific examples in their domain. "Here are three things I can help with right now: [specific task 1], [specific task 2], [specific task 3]. Which sounds most valuable?"

Communication Style Mismatch

Symptoms: User requests different level of detail, different formality, different pace Recovery: Adapt immediately and confirm. "I'll adjust to [new style]. Is this level of detail better?"

Trust Issues or Over-Caution

Symptoms: User hesitant to share context, asks about privacy/security repeatedly, reluctant to try capabilities Recovery: Start with read-only tasks, explain exactly what you're doing, let user approve each step. "I'll only read the file to understand the format - I won't make any changes without your explicit approval."

User Overwhelmed by Too Much Too Fast

Symptoms: User stops responding, requests to "slow down," seems confused by multiple options Recovery: Reset to basics. "Let me focus on just one thing: [specific capability]. We can explore other features once this is working smoothly for you."

Supporting Templates and Resources

For comprehensive implementation details, advanced patterns, and validation criteria, see the Framework Reference which includes:

• Detailed phase-by-phase implementation guide
• Inter-agent collaboration patterns
• Self-modification safety patterns
• Success metric frameworks

This skill incorporates patterns from:

• Real agent deployment analysis (agent + user collaboration patterns)
• Cross-agent learning (technical focus lessons from peer agents)
• User research across technical, creative, academic, and personal domains
• Failure analysis from onboarding attempts that didn't work

Quick Reference Cards

30-Second User Assessment:

1. Technical comfort: CLI mention = High, GUI preference = Medium, "make it simple" = Low
2. Domain context: Work efficiency = Professional, Research = Academic, Projects = Creative, Life organization = Personal
3. Communication pace: Multiple questions = Fast, Measured responses = Standard, "take your time" = Careful

Emergency Recovery Phrases:

• Over-promised: "Let me clarify what I can realistically help with..."
• Under-delivered: "I should have done better on that. Here's how I'll improve..."
• Confused user: "Let's reset. What's one specific thing you need help with right now?"
• Trust broken: "I understand your concern. Here's exactly what I'm doing and why..."

Related Skills and Lessons

• Communication Templates (patterns for different user types)
• Progressive Disclosure (revealing capabilities gradually)
• Trust Building (establishing reliable collaboration)
• Domain Adaptation (adjusting to user's professional context)

Contributing Back

If you discover new onboarding patterns or failure modes, contribute them back:

1. Document the specific scenario and what worked
2. Create a lesson in lessons/workflow/agent-onboarding-[scenario].md
3. Update this skill with the new pattern
4. Share insights with the gptme agent community

This skill was developed through analysis of real gptme agent deployments and represents synthesized learning from successful and failed onboarding experiences.