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.