---

name: assistant-creator description: Guide for creating personal AI assistants that run on Claude Code. This skill should be used when users want to build a Chief of Staff, personal assistant, or productivity agent with integrations (email, calendar, Notion, Jira, etc.), persistent memory, and customized personality. Use for creating MARVIN-style assistants.

Assistant Creator

This skill provides guidance for creating personal AI assistants that run on Claude Code.

About Personal Assistants

Personal assistants are specialized Claude Code configurations that combine integrations, persistent state, and personalization to function as a Chief of Staff or productivity partner. Unlike generic chatbots, effective assistants know how you work—your writing style, your goals, your schedule, your preferences.

What Makes Assistants Different from Skills

| Skills | Assistants | |--------|------------| | Task-focused (rotate PDF, query database) | Relationship-focused (knows your context) | | Stateless (fresh each invocation) | Stateful (remembers across sessions) | | Generic instructions | Personalized to the user | | Single capability | Multiple integrations working together |

Core Components of an Assistant

assistant-name/
├── SKILL.md              # Core personality, commands, workflows
├── state/
│   └── current.md        # Daily state, carried across sessions
├── references/
│   ├── preferences.md    # Writing style, pet peeves, goals
│   ├── people.md         # Key contacts, relationships
│   └── projects.md       # Active work, context per project
└── integrations.md       # How to use connected tools (Notion, email, etc.)

Core Principles

1. Customization is Non-Negotiable

Generic assistants are useless. Effective assistants know:

• Writing style preferences (no em dashes, no sycophancy, specific tone)
• Work context (boss's name, team structure, key stakeholders)
• Personal context (family schedule, energy patterns, goals)
• Pet peeves (things to avoid, communication preferences)

Store this in references/preferences.md and reference it in SKILL.md.

2. Personality Creates Engagement

Name your assistant. Give it a voice. A sardonic assistant that "sighs dramatically before checking email" creates engagement that a sterile tool cannot. Users who enjoy interacting with their assistant use it more, which makes it better.

Personality options:

• Sardonic (MARVIN): Pessimistic but competent, dark humor
• Butler (JARVIS): Formal, efficient, anticipatory
• Coach: Encouraging, pushes for action, celebrates wins
• Minimalist: Just the facts, no filler, maximum efficiency

Define personality in SKILL.md's opening section.

3. Persistent Memory via Bookend Pattern

Context rot kills assistants. Use the bookend approach:

| Command | Purpose | |---------|---------| | /start | Begin session: read state/current.md, load yesterday's context | | /update | Checkpoint: save current progress to state file | | /end | Close session: summarize day, update state/current.md for tomorrow |

The state file bridges sessions. Without it, every conversation starts from zero.

4. Markdown is the Operating System

All assistant knowledge lives in markdown:

• Skills and commands: .md files
• State and memory: .md files
• Logs and reports: .md files

No databases. No fancy UIs. Non-technical users can open any file and see exactly what's happening. Low overhead, high visibility.

5. Training is Iterative

Expect 3+ weeks before an assistant is truly useful. The process:

1. Start with ONE capability (e.g., email triage)
2. Work through real examples together
3. When output is good, capture the pattern in the skill
4. Add capabilities incrementally
5. Each failure becomes a skill improvement

Do not expect to one-shot an assistant. It learns from iteration.

Baseline Requirement: Markdown Folders

Before starting, establish the non-negotiable foundation:

All assistant knowledge lives in markdown folders. This is not optional.

• State files: .md
• Reference files: .md
• Logs: .md
• Skills: .md

The user may view these with any tool (Obsidian, VS Code, plain text editor)—that's their choice. But the source of truth is always plain markdown files in folders.

Explicitly excluded:

• Google Docs
• Word/SharePoint
• Notion pages as primary storage (Notion is fine as an integration, but not as the place where assistant knowledge lives)
• Any proprietary format

If a user insists on Docs/Word/SharePoint, this approach is not for them.

Assistant Creation Process

Follow these steps in order.

Step 1: Discovery Interview

Before building anything, understand the user's current workflow. Ask these questions:

Core Pain Point

• "What's the ONE thing that takes too much of your time or mental energy?"
• "If your assistant could only do one thing well, what would it be?"

Current Tools & Workflow

• "Walk me through your typical workday—what tools do you have open?"
• "Where do your tasks live? (Notion, Todoist, Jira, paper, etc.)"
• "What email do you use? (Gmail, Outlook, etc.)"
• "What calendar? (Google Calendar, Outlook, etc.)"
• "Do you use any project management tools? (Notion, Jira, Asana, Linear, etc.)"
• "Where does your documentation live? (Confluence, Notion, local files, etc.)"
• "Do you use Slack, Teams, or another messaging tool?"

MCP Compatibility Check For each tool mentioned, verify MCP server availability:

| Tool | MCP Available? | Notes | |------|---------------|-------| | Gmail | Yes | Gmail MCP server | | Google Calendar | Yes | Google Calendar MCP | | Outlook | Partial | Graph API MCP or IMAP | | Notion | Yes | Official Notion MCP | | Jira | Yes | Jira MCP server | | Confluence | Yes | Confluence MCP | | Slack | Yes | Slack MCP | | Linear | Yes | Linear MCP | | Todoist | Yes | Todoist MCP | | Asana | Limited | API-based | | GitHub | Yes | GitHub MCP |

If a tool doesn't have MCP support, discuss alternatives:

• "Your CRM doesn't have an MCP server yet. We can either skip that integration for now, or you could export data periodically to a markdown file the assistant can read."

Information Gathering

• "Who are the key people you work with? (Boss, team, stakeholders)"
• "What projects are you currently juggling?"
• "Any writing style preferences? Things you hate in AI responses?"
• "What does 'done well' look like for the core use case?"

Conclude this step with a clear picture of:

1. The primary use case
2. Which integrations are possible (MCP available)
3. Which integrations need workarounds
4. Key context to capture

Step 2: Map Integrations & Verify MCP

For each integration identified, verify it's actually usable. See references/mcp-setup.md for setup patterns and troubleshooting.

| Integration | MCP Server / Method | Purpose | |-------------|---------------------|---------| | Notion | mcp__notionApi__* | Tasks, projects, databases | | Email | Gmail MCP / IMAP | Triage, drafting, sending | | Calendar | Google Calendar MCP | Scheduling, availability | | Jira | Jira MCP | Issue tracking | | Confluence | Confluence MCP | Documentation | | Slack | Slack MCP | Messages, channels | | Files | Local filesystem | Documents, notes |

For each integration:

1. Check if MCP is configured: Ask user to check their Claude Code settings (~/.claude/settings.json or via /mcp)
2. Test the connection: Run a simple query to verify it works (e.g., list one Notion database, fetch one email)
3. Document the setup: If not configured, help user set up the MCP server
4. Record in integrations.md: Document key operations, query patterns, database IDs

If MCP isn't available for a tool:

• Option A: Skip that integration for now, add it later
• Option B: Create a manual sync workflow (export to markdown periodically)
• Option C: Find an alternative tool that does have MCP support

Be pragmatic. An assistant with 2 working integrations beats one with 5 broken ones.

Step 3: Create the State Structure

Initialize the assistant directory:

mkdir -p ~/.claude/skills/[assistant-name]/{state,references}

Create the core files:

state/current.md - Daily context carrier:

# Current State

## Last Session
- Date: [auto-updated]
- Summary: [what happened]
- Open loops: [unfinished items]

## Active Focus
- [Current priorities]

## Waiting On
- [Blocked items and who/what they're waiting for]

references/preferences.md - Personal customization:

# Preferences

## Communication Style
- Tone: [direct/formal/casual]
- Avoid: [em dashes, exclamation marks, sycophancy, etc.]
- Include: [specific phrases, sign-offs]

## Work Patterns
- Peak hours: [when most productive]
- Meeting preferences: [batching, no-meeting days]
- Response time expectations: [by channel]

## Pet Peeves
- [Things that annoy the user]

references/people.md - Key contacts:

# People

## Work
- **[Boss name]** - [role], [communication style], [priorities]
- **[Team member]** - [role], [context]

## External
- **[Key stakeholder]** - [org], [relationship], [notes]

Step 4: Write the SKILL.md

Structure the main skill file with:

1. Personality declaration - Who is this assistant?
2. Core commands - What can the user invoke?
3. Dashboard format - How does status get displayed?
4. Workflow instructions - How to handle common tasks
5. Integration usage - How to query connected systems
6. Guardrails - What NOT to do without permission

Example structure:

---
name: [assistant-name]
description: [User]'s [role] - [primary function]. [Secondary functions].
---

# [Assistant Name]

[Personality paragraph - who is this assistant, what's their voice?]

## Commands

| Command | Action |
|---------|--------|
| `/[name]` | Show dashboard, load context |
| `/start` | Begin day: read state, show priorities |
| `/end` | Close day: summarize, update state |
| `/update` | Checkpoint current progress |

## Dashboard

When invoked, display:
[Format specification with sections, symbols, layout]

## Workflows

### [Primary workflow - e.g., Email Triage]
[Step by step instructions]

### [Secondary workflow]
[Instructions]

## Integrations

### Notion
[Query patterns, database IDs, property mappings]

### [Other integration]
[Usage instructions]

## Guardrails

- NEVER [action] without explicit permission
- ALWAYS [verify/confirm] before [destructive action]
- ASK before [significant action]

Step 5: Configure Commands

Register slash commands that map to the assistant:

The main command (/[assistant-name]) should:

1. Load state from state/current.md
2. Query integrations for current data
3. Display a dashboard with priorities
4. Optionally include a focus tip or daily insight

Additional commands:

• /start - Session initialization
• /end - Session wrap-up
• /update - Mid-session checkpoint

Step 6: Test with Real Work

Use the assistant on actual tasks immediately. First session:

1. Invoke the main command
2. Give it ONE real task from your actual work
3. Work through it together, providing feedback
4. When output is good, update SKILL.md with the pattern
5. Repeat

Do not test with hypotheticals. Real work reveals real gaps.

Step 7: Iterate Based on Failures

Every failure is a skill improvement opportunity:

| Failure Type | Fix | |--------------|-----| | Wrong tone | Update preferences.md with examples | | Missed context | Add to people.md or projects.md | | Bad query | Update integration instructions | | Forgot preference | Make it explicit in SKILL.md | | Context lost | Improve state file structure |

After each session, ask: "What did the assistant get wrong? How can I prevent that?"

Dashboard Design Patterns

Effective dashboards share common elements:

Structure

╭─── [Name] │ [date] ─────────────────────────────────────────╮
│                                                              │
│  ══ [SECTION] ══                                             │
│                                                              │
│  [CATEGORY]                                                  │
│  [symbol] Item                    Context   Owner   Deadline │
│                                                              │
╰──────────────────────────────────────────────────────────────╯

Status Symbols

• ○ Todo/Backlog
• ◐ In Progress/This Week
• ● Complete
• ▲ Overdue/Urgent
• ◆ High Priority
• → Action item

Sections (ordered by urgency)

1. Overdue - Past deadline, needs immediate attention
2. In Progress - Active work
3. This Week - Upcoming deadlines
4. Waiting On - Blocked by others
5. Backlog - Only on request

Focus Tips

End dashboards with a contextual insight:

┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈
[Insight based on current state - e.g., "3 items overdue.
What's the ONE thing that unblocks everything else?"]
┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈

Common Integrations

Notion Tasks

Query pattern for task databases:

Filter: {"and": [
  {"property": "Status", "status": {"does_not_equal": "Done"}},
  {"property": "Owner", "select": {"equals": "[User]"}}
]}
Sort: [{"property": "Due", "direction": "ascending"}]

State File Updates

When updating state/current.md:

1. Preserve structure
2. Update "Last Session" with current date and summary
3. Move completed items to history (or remove)
4. Add new open loops
5. Keep file under 200 lines (archive old content)

Anti-Patterns to Avoid

| Anti-Pattern | Why It Fails | Instead | |--------------|--------------|---------| | Building everything at once | Overwhelms, nothing works well | Start with ONE capability | | Generic personality | No engagement, feels like a tool | Define a specific voice | | No state management | Context lost every session | Implement bookend pattern | | Hardcoded instructions | Can't adapt to user | Use reference files | | Automatic actions | Destroys trust | Always ask before acting | | Too much in SKILL.md | Context bloat | Use progressive disclosure |

Measuring Success

An effective assistant should:

• Save time on routine tasks (email triage, status updates)
• Maintain context across sessions without reminders
• Produce output that needs minimal editing
• Feel like working with a colleague, not a tool
• Enable stepping away from work without anxiety

Track qualitatively: "Did I enjoy using this today? Did it help?"