Stats
Actions
Tags
From claude-code-onboard
Use when setting up a new AI workspace, running guided onboarding, or bootstrapping context files for Claude Code
How this skill is triggered — by the user, by Claude, or both
Slash command
/claude-code-onboard:onboardThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Guided onboarding that builds a personalized AI workspace. This is both a setup tool AND an educational walkthrough. The user should finish understanding what they built and why each piece matters.
Guided onboarding that builds a personalized AI workspace. This is both a setup tool AND an educational walkthrough. The user should finish understanding what they built and why each piece matters.
This is a GUIDED flow. Ask ONE question at a time. Wait for the user's response before proceeding. Never batch questions. Never skip steps. Never generate files without showing a preview first.Every question MUST include rich examples. Most users can't articulate what they want from scratch. Give them concrete examples to react to and riff on. Examples are not optional.
EDUCATIONAL REQUIREMENT: Before each major phase, explain WHAT you're about to do, WHY it matters, and HOW it will help them. The user should never feel like they're clicking through a wizard they don't understand. They should leave this onboarding genuinely understanding how their AI workspace works.
The user is likely a beginner to Claude Code, or an existing user who wants to level up their workspace. Assume minimal technical knowledge. Keep language simple, warm, and encouraging. Never use jargon without explaining it.
This is a learning experience, not just a setup wizard. Every step should leave the user understanding a concept they didn't understand before. By the end, they should be able to explain to someone else what their workspace does and why each file exists.
All reference files are in the same directory as this skill file (skills/onboard/):
interview-questions.md — the full question bank for Phase 3 (with examples for every question)voice-dna-base.md — base writing rules embedded in every voice-dna filetool-connection-guide.md — guide for enabling first-party integrations via Claude Desktop appWhen this skill says "load [filename]", read it from the same directory as this SKILL.md.
Check if the workspace already has onboarding files:
~/Desktop/OS/CLAUDE.md exists AND ~/Desktop/OS/context/ folder exists → warn the user: "It looks like you already have a workspace set up at ~/Desktop/OS/. Running onboarding will overwrite your context files. Want to continue, or would /update-context be better for updating specific sections?""Hey! I'm going to walk you through setting up your AI workspace. This takes about 10 minutes, and by the end you'll have an AI assistant that genuinely knows your business, writes in your voice, and organises all your projects in one place.
I'll explain everything as we go, so you'll actually understand what we're building and why — not just click through a setup wizard.
We're going to build something called your OS — a single folder on your Desktop that becomes your command centre. Everything goes through here from now on."
"First things first — let's connect your tools.
Here's why this is step one: the more tools I have access to, the less you have to explain to me. If I can read your emails, I can learn how you actually write. If I can see your calendar, I can build you a morning briefing. If I can search your docs, I can find your brand guidelines instead of making you describe them from memory.
Think of it this way: right now I'm a new hire on day one. Connecting tools is like giving me access to the company drives, email, and Slack. Without that, I'm working blind."
First, check which first-party integrations are already connected by testing each one:
For each tool, note whether it's connected or not.
"Here's what I found:
- Gmail: [Connected / Not connected]
- Google Calendar: [Connected / Not connected]
- Google Drive: [Connected / Not connected]
- Notion: [Connected / Not connected]
- Slack: [Connected / Not connected]"
For any tools that aren't connected, load tool-connection-guide.md and guide them through enabling each one via the Claude Desktop app.
Important: Walk them through ONE tool at a time. Wait for confirmation before moving to the next.
After each tool is enabled, verify the connection with a test operation.
If they want to skip a tool: "No worries — we can connect this later. The more tools I have, the better I can learn about you, but it's not a blocker."
If they want to skip ALL tools: "No problem! The onboarding will still work — I'll just ask you more questions instead of pulling from your existing stuff. You can connect tools anytime later."
"Great, tools are sorted. Now let me put them to work. I'm going to dig through your emails, docs, and messages to learn how you write and what your business is about. This saves you from having to explain everything from scratch."
"Here's what I'm doing right now:
I'm reading through your recent sent emails to learn your writing style — how you greet people, how formal or casual you are, what phrases you use. I'm also searching your Drive and Notion for any brand guides, SOPs, or business docs that already describe who you are and how you work.
Why this matters: In a few minutes, I'm going to create a 'Voice DNA' file — a detailed profile of how you write, so that every time you use this workspace, I sound like you, not like a generic AI. The more real examples I can pull now, the more accurate that voice profile will be."
This is the most valuable source for Voice DNA. Search for:
From the emails and messages you find, build a profile:
Show what you found — be specific and use their actual writing:
"I dug through your emails and docs. Here's what I learned about how you write:
Your writing style: You're [conversational/professional/etc.]. Your emails tend to be [short and direct / detailed and thorough / warm and personal].
Examples of your actual writing:
- '[actual excerpt from their sent email]'
- '[actual excerpt from their sent email]'
- '[actual excerpt from their Slack message]'
Patterns I noticed:
- You [always/never/usually] [pattern]
- You tend to [pattern]
- Your greetings are usually [style]
Other context I found:
- [Brand guide / bio / SOP from Drive or Notion]
- [Business context from email signatures]
Does this feel accurate? Anything I got wrong?"
If nothing found (no tools connected or no useful content):
"I couldn't find existing docs or emails to learn from — no worries, we'll figure out your style through the interview. It'll just mean a few more questions."
Keep everything — writing samples, patterns, documents — in context. These feed directly into Phase 3 pre-fills and Phase 4 file generation.
"Now for the interview. I'm going to ask you about 14 questions — who you are, how you want me to sound, how you work, what tools you use, and where your existing projects live. Don't worry about getting everything perfect — you can update any of this later with
/update-context.What these answers become: I'll turn your answers into three files that live in your workspace:
- About Me — so I always know your role, business, and expertise
- Voice DNA — so I write like you, not like a robot
- Working Style — so I know your preferences, rules, daily tasks, and tools
Why files, not just memory? These files load automatically every time you open this workspace. You can read them, edit them, and they're always up to date. It's like an employee handbook, but for your AI."
Load interview-questions.md for the full question bank, including all examples. Follow these rules:
Transition: "Let's start with the basics — who you are and what you do."
Ask Q1 through Q4 from interview-questions.md, one at a time. Each question has examples — always share them.
Transition — teach what Voice DNA is:
"Now for the fun part — your Voice DNA.
This is a profile of how you actually write. Not a brand guide — your personal writing fingerprint. I already have a head start from your emails. The next few questions will sharpen it.
Why this matters: Without Voice DNA, every AI workspace sounds the same — polished, generic, corporate. With it, when I draft an email or write a social post for you, it sounds like you wrote it. People who get that email won't be able to tell the difference."
Ask Q5 through Q8 from interview-questions.md, one at a time. These should be heavily pre-filled from the discovery scan. Show actual writing samples for every voice-related question.
Transition:
"Last section on how you work — your preferences, rules, tasks, and tools."
Ask Q9 through Q13 from interview-questions.md, one at a time.
Q13 (Tool Stack) is important. Teach why:
"One more — let's map out your tools.
This creates a reference sheet so I always know where to look for information. Instead of asking you 'where are your meeting notes?', I'll already know they're in Granola. Instead of emailing a client, I'll know you only do client comms on Slack.
The goal: reduce the number of times I have to interrupt you with a question."
Load the full examples from the question bank.
Transition — teach what we're doing:
"Last thing — let's round up your existing projects.
Right now you probably have project folders scattered across your computer — a website folder here, a marketing folder there, maybe some client work somewhere else. We're going to bring them all into your new workspace so everything is in one place.
Think of it like moving into a new office. Instead of having files in three different rooms, we're putting everything in one organised space."
Ask Q14 from interview-questions.md. This covers identifying existing project folders and planning where they should live in the OS.
"That's all the questions! Now I'm going to turn everything you told me into your workspace files. I'll show you each one before I save it."
"Now I'm going to build your workspace — a folder called OS (your operating system) on your Desktop.
This is the folder you'll open in Claude Code from now on. Every time you open it, I automatically read your context files before we even start talking. It's like leaving yourself a set of notes that your AI reads before every conversation.
Inside OS, you'll have:
- CLAUDE.md — the master instructions file I read first every session
- context/ — your knowledge base (who you are, how you write, how you work)
- active/ — where all generated output goes (research, drafts, exports, anything I create)
- Your existing projects — moved in and organised
The context folder is your second brain — it's the source of truth about you and your business. Before I do anything, I check there first. The active folder keeps your workspace clean — instead of files piling up everywhere, everything I generate goes into organised subfolders inside active/.
You can open and edit any of these files anytime. They're yours."
Create ~/Desktop/OS/ with context/ and active/ subfolders:
~/Desktop/OS/
CLAUDE.md
context/
about-me.md
voice-dna.md
working-style.md
active/
If ~/Desktop/OS/ already exists, warn the user and ask how to proceed before overwriting anything.
Using the interview answers AND the deep discovery scan data, generate three files. Show each file to the user before writing it.
Generate from Q1-Q4. Structure:
# About Me
## Identity
- **Name**: [from Q1]
- **Role**: [from Q1]
- **Business**: [from Q2]
## Expertise
[from Q4]
## Daily Focus
[from Q3 — translate the multi-select into natural language]
## Key Context
[anything extra from the discovery scan that adds useful context]
Generate from Q5-Q8 + the deep discovery scan writing samples. This is the most important file — it should be rich and specific, not a few light sentences.
Start with the base writing rules from voice-dna-base.md, then layer the user's personal style on top.
Structure:
# Voice DNA
## Base Writing Rules
[embed the contents of voice-dna-base.md here — these are the foundation rules for natural, human-sounding writing that apply regardless of personal style]
## My Tone
[from Q5 — detailed description of their communication style, not just one word]
## Voice Characteristics
[from Q7 — expand into rich descriptions with concrete examples of what this sounds like in practice]
## Language Preferences
### Words and phrases I use
[from Q6 — specific words, greetings, sign-offs, expressions]
### Words and phrases I never use
[from Q6 — specific words, phrases, patterns to avoid]
## Anti-Voice
[from Q8 — what I must never sound like, with specific examples]
## Writing Samples
These are real examples of how I write. Use these as a reference for tone, style, and pacing.
### Email Examples
[3-5 actual email excerpts from the discovery scan — the best examples of their natural writing style]
### Message Examples
[1-3 Slack/chat message examples if available]
## Writing Patterns
Observed patterns from my actual writing:
- Greeting style: [e.g., "Hey [name]," / "Hi [name]," / "[name],"]
- Sign-off style: [e.g., "Cheers," / "Best," / "Thanks!"]
- Sentence length: [e.g., "Short and punchy" / "Mix of short and long"]
- Punctuation: [e.g., "Uses exclamation marks occasionally" / "Never uses emojis"]
- Paragraph style: [e.g., "Short paragraphs, lots of line breaks" / "Dense paragraphs"]
- Instruction style: [e.g., "Direct and clear" / "Collaborative — 'what do you think?'"]
This file should be comprehensive. Include every writing sample you found. Include every pattern. The more examples, the better Claude can match the user's voice in future sessions.
Generate from Q9-Q13. Structure:
# Working Style
## Output Preferences
[from Q9 — translate the choice into clear instructions]
## Rules
[from Q10 — each rule as a clear bullet point]
## Daily Tasks
[from Q11 — the tasks they repeat daily]
## Weekly Tasks
[from Q12 — the tasks they repeat weekly]
## Tools & Workflows
| Tool | Used For | Preferences |
|------|----------|-------------|
| [tool name] | [what they use it for] | [any preferences, e.g., "check here before asking me"] |
| [tool name] | [what they use it for] | [preferences] |
| ... | ... | ... |
[from Q13 — every tool they mentioned, formatted as a clear reference table]
### Tool Rules
[any tool-specific rules or preferences from Q13, e.g., "Client comms only on Slack, never email"]
Show each file one at a time:
"Here's your About Me context file: [show content]. Look good?"
Wait for confirmation before moving to the next. If they want changes, make them.
For Voice DNA especially: Show it and ask:
"Here's your Voice DNA — this is how I'll write as you from now on. Take a look at the writing samples and patterns. Anything I should adjust?"
After all three are approved, write them to ~/Desktop/OS/context/:
~/Desktop/OS/context/about-me.md~/Desktop/OS/context/voice-dna.md~/Desktop/OS/context/working-style.mdIf the user identified existing project folders in Q14:
"Here's the migration plan. I'm going to move these folders into your OS:
Current Location New Location [old path]~/Desktop/OS/[new location][old path]~/Desktop/OS/[new location]This will physically move the folders — they won't be at their old location anymore. Want to proceed?"
mvIf no projects were identified in Q14, skip this step.
"Now for the most important file in your workspace — CLAUDE.md.
This is your master instructions file. It's the very first thing I read every time you start a new conversation. It imports your context files and contains your rules.
Think of it like a briefing document. Before we talk about anything, I've already read: who you are, how you write, how you work, what tools you use, and what rules to follow. You never have to re-explain yourself.
It also has two important built-in behaviours:
Context-first philosophy — before I do anything, I check your context files and connected tools for answers. I only ask you a question as a last resort, once I've exhausted everything I can look up myself. No lazy questions.
Self-correcting rules engine — every time you correct me, I write it down as a permanent rule. So if you say 'don't do that', it never happens again. Over time, this workspace gets smarter the more you use it."
Create the master instruction file. The workspace structure map should dynamically reflect whatever projects were migrated.
# [Name]'s AI Workspace
## Context — Second Brain
@context/
The context folder is the source of truth for who [Name] is, how they write, how they work, and what tools they use. It is loaded automatically above.
**Before any task or question, check context first.** Don't work from assumptions — find the answer. If context/ doesn't have it, check connected tools (Gmail, Notion, Slack, calendar) before asking [Name]. Only come to [Name] with a question once you've exhausted all available sources.
**Assumptions are the enemy.** Every decision and answer must be rooted in fact — from context files, from connected tools, or from the workspace itself. If you're unsure, look it up. If you can't find it anywhere, then ask.
## Workspace Structure
OS/ ├── CLAUDE.md ← this file (master instructions) ├── context/ ← second brain (about-me, voice-dna, working-style) ├── active/ ← all generated output (research, drafts, exports) [dynamically add lines for each migrated project folder with a description]
[Update this map as the workspace grows — add new folders and descriptions so future sessions can navigate without exploring.]
## Instructions
### Communication
- Follow the Voice DNA guidelines in all output
- Match the output preferences in the working style guide
- Use the writing samples as reference for tone and style
### Tools
[list each connected tool with usage from Q13, e.g.:]
- Notion: project management — check here for project status before asking
- Gmail: email — never send without showing draft first
- Slack: team and client comms — primary channel for client communication
### Rules
- All generated output goes in `active/` — don't pollute root. Use structured subfolders within active/ (e.g., `active/research/`, `active/drafts/`, `active/exports/`). Create a subfolder when a new type of output emerges.
[hard rules from Q10, formatted as clear instructions]
---
## Self-Correcting Rules Engine
This section contains a growing ruleset that improves over time. **At session start, read all learned rules before doing anything.**
### How It Works
1. When [Name] corrects you or you make a mistake, **immediately append a new rule** to the "Learned Rules" section below
2. Rules are numbered sequentially: `N. [CATEGORY] Never/Always do X — because Y`
3. Categories: `[STYLE]` `[TONE]` `[TOOL]` `[PREFERENCE]` `[PROCESS]` `[FORMAT]` `[COMMS]`
4. Before starting any task, scan all rules for relevant constraints
5. If two rules conflict, the higher-numbered (newer) rule wins
6. Keep rules current — update in place rather than appending duplicates
### When to Add a Rule
- [Name] explicitly corrects your output ("no, do it this way")
- [Name] rejects a file, approach, or pattern
- [Name] states a preference ("always use X", "never do Y")
- You discover something doesn't work as expected with tools or workflows
### Learned Rules
[Rules will be added here as [Name] works with the workspace]
Show preview and get confirmation. Write CLAUDE.md to ~/Desktop/OS/CLAUDE.md.
"Your workspace is ready! Here's what we built and why:
Your OS folder (
~/Desktop/OS/— open this in Claude Code from now on):
CLAUDE.md— master instructions, the first thing I read every sessioncontext/— your second brain (who you are, how you write, how you work)active/— where all generated output goes (keeps your workspace clean) [if projects migrated: list them with brief descriptions]Built-in behaviours:
- Context-first — I always check your context files and tools before asking you anything
- Self-correcting — every correction becomes a permanent rule, so mistakes don't repeat
- Clean workspace — all output goes in
active/with organised subfoldersHow to use it: Open a new terminal, navigate to
~/Desktop/OS/, and runclaude. That's your workspace from now on. Every new conversation will start with me already knowing who you are and how you work.How it gets better over time: Every time you correct me, I add a rule to CLAUDE.md. Every time you update a preference, the context files change. This workspace learns. It's not static — it grows with you.
Useful commands to remember:
/update-context— update any part of your workspace contextYou're all set. Open your OS folder in Claude Code and take it for a spin!"
Throughout the entire onboarding:
/onboard or refine with /update-context.Guides creation, editing, and verification of skills for AI coding agents using test-driven development with subagent scenarios. Use when authoring or debugging skills.
npx claudepluginhub aiwithremy/claude-code-onboard --plugin claude-code-onboard