you.md

Getting Started

you.md is an identity context protocol that any AI agent can read. Think of it as a .env file for your identity -- your bio, projects, values, communication style, and preferences, all in one place.

Web Quickstart

1. 1Sign up at you.md/sign-up -- takes 30 seconds
2. 2Pick a username and claim your profile
3. 3The You Agent builds your identity through conversation
4. 4Open the shell, type /share to get your shareable context link

CLI Quickstart

$ curl -fsSL https://you.md/install.sh | bash

1. 1Install the global CLI with the curl bootstrapper. If you prefer npm directly, run npm install -g youmd@latest.
2. 2Run youmd login to authenticate
3. 3Run youmd init -- the agent builds your identity through conversation
4. 4Run youmd push to publish your profile
5. 5Run you to meet U, then type /share to get your context link

Claude Code Integration

Most you.md users work inside Claude Code, Cursor, or similar AI coding tools. Here's how to use you.md directly from your coding environment.

Setup

1. 1Open a regular terminal (not inside Claude Code) and run curl -fsSL https://you.md/install.sh | bash once, then you to let U guide login, pull, or identity setup
2. 2Run youmd login to authenticate
3. 3Run youmd push to publish your profile
4. 4Now switch to Claude Code — all non-interactive commands work from here

Commands That Work Inside Claude Code

These commands are non-interactive and work perfectly in Claude Code, Cursor, Copilot, and any AI coding tool:

Recommended Workflow

The most powerful workflow: let your coding agent update your identity context as you work together.

1. 1Tell Claude Code: "add my preference for terminal-native UI to my you.md private context" — it can run youmd private notes append "prefers terminal-native UI"
2. 2After a coding session, tell your agent: "extract any preferences or facts about me from this conversation and save them to my you.md" — it can run youmd memories add commands
3. 3Edit your .youmd/ files directly (they're just markdown) and run youmd push to sync
4. 4Use youmd sync --watch in a regular terminal to auto-push on every file save
5. 5Share your context with any new agent: youmd link create generates a URL you can paste into any AI conversation

Your identity stays up to date across every tool. Every agent knows who you are from the first message.

Share Your Identity

The core feature. Once your identity is built, share it with any AI agent in seconds. The /share command works in both the web shell and the CLI.

/share Command

Type /share in either the web shell terminal or inside you on the CLI. Both generate the same copyable block:

> /share

--- BEGIN YOU.MD CONTEXT ---
name: Houston Golden
role: Founder & builder
projects: you.md, ...
values: ship fast, build in public
preferences: terminal-native, monochrome
--- END YOU.MD CONTEXT ---

[copied to clipboard]

Paste this into any AI conversation -- Claude, ChatGPT, Cursor, Copilot, or any agent. It instantly knows your bio, projects, values, and preferences.

Use /share --private to include your private layer (contact info, internal notes, sensitive preferences). Only share this with agents you trust.

Context Links

Shareable context links look like https://you.md/ctx/[username]/[token]. Any agent can fetch that scoped URL directly to load your context into its conversation.

Sync

You.md works across web and CLI. Create your profile on either platform and keep them in sync.

Connecting Web + CLI

The CLI uses the same email and verification-code flow as the web app -- no separate API token needed for your own account.

1. 1Create your profile on either web or CLI
2. 2youmd login -- press Enter to open browser sign-in, or type the same email you use on the web and paste the verification code in-terminal
3. 3youmd pull downloads your web profile to local files
4. 4Edit files in any editor (Cursor, Obsidian, VS Code)
5. 5youmd push compiles and publishes back to you.md
6. 6youmd sync --watch auto-syncs on every file save

Local File Structure

.youmd/
  profile/
    about.md
    now.md
    projects.md
    values.md
    links.md
  preferences/
    agent.md
    writing.md
  voice/
    voice.md
    voice.linkedin.md
  you.json
  you.md
  manifest.json

CLI Reference

Install with curl -fsSL https://you.md/install.sh | bash as the default path, or use npm i -g youmd@latest directly if you prefer. The CLI covers the full identity lifecycle -- identity, auth, sync, sharing, memory, projects, and skills.

Identity

Auth & Sync

Access & Sharing

Memory & Context

Projects

Skills

Skills

Skills are identity-aware markdown templates that turn your you.md profile into actionable outputs. They use {{var}} interpolation to inject your identity data at runtime -- so the output is always personalized to you.

Overview

A skill is a .md file with template variables. When you run a skill, the CLI resolves each {{var}} against your you.json bundle and renders the final output. Skills can generate CLAUDE.md files, project scaffolding, cover letters, outreach messages, or anything else that benefits from knowing who you are.

# {{name}}'s Project Context

## Who You Are
{{bio}}

## Your Stack
{{preferences.tools}}

## Communication Style
{{voice.style}}

## Current Focus
{{now}}

Install skills from the public registry, create your own, or publish them for others. The skill system is fully local-first -- installed skills live in .youmd/skills/ and sync with push/pull.

CLI Commands

The youmd skill namespace has 18 core subcommands covering the full skill lifecycle:

Bundled Skills

Every you.md install ships with six built-in skills. These are always available and kept in sync with CLI updates.

init-project

The youmd skill init-project command is the fastest way to make a repo identity-aware. It sets up four things:

1. 1AGENTS.md -- the repo-visible instruction layer with workflow rules and your generated identity context
2. 2CLAUDE.md -- the Claude-specific entrypoint with a managed You.md bootstrap block
3. 3project-context/ -- the canonical repo context directory, filled additively per file
4. 4.you/ plus host-linked skills -- the generated additive layer and tool-specific discovery surfaces

$ youmd skill init-project
  install claude-md-generator ready
  install project-context-init ready
  .you/ created AGENT.md, STACK-MAP.md, project-context/README.md
  agent instruction files created AGENTS.md; created CLAUDE.md
  project-context/ created TODO.md, FEATURES.md, CHANGELOG.md, PROMPTS.md ...
  link .claude/skills/youmd/ /path/to/repo/.claude/skills/youmd
  done -- your repo is identity-aware

Skill Sync

Installed skills are stored in your local .youmd/skills/ directory and tracked in your bundle manifest. When you run youmd push, your skill installs are synced to the cloud. When you run youmd pull on another machine, your skills come with it.

Use youmd skill sync to explicitly reconcile local and remote skill state without a full push/pull cycle.

Agent Directives

Directives are instructions embedded in your you.md identity that tell AI agents how to behave when working with you. They live in your preferences layer and are included in every context share.

Unlike skills (which are templates you run), directives are passive -- they ride along with your identity and shape how agents respond to you. Think of them as persistent system prompts keyed to your identity.

# Agent Directives

## Tone
Direct and concise. No filler. No corporate speak.

## Code Style
Prefer functional patterns. Use TypeScript strict mode.
Never add comments that restate the code.

## Workflow
Act decisively -- don't ask permission for obvious next steps.
Show progress, don't go silent.
Address every part of multi-part messages.

When an agent reads your context (via /share, a context link, or the API), your directives are included automatically. Any agent that respects your you.md will follow them.

API

You.md has 30+ HTTP endpoints for programmatic access. All authenticated endpoints use Bearer token auth with ym_ prefixed API keys.

Public Endpoints

# Fetch a public profile (JSON)
GET /api/v1/profiles?username=houstongolden

# List all profiles
GET /api/v1/profiles

# Check username availability
GET /api/v1/check-username?username=newuser

# Resolve a context link (plain text for agents)
GET /ctx/{username}/{token}

# Start passwordless auth
POST /api/auth/send-verification
{ "email": "...", "type": "login" }

# Start passwordless signup
POST /api/auth/send-verification
{ "email": "...", "type": "signup", "username": "...", "displayName": "..." }

# Verify code and optionally issue an API key
POST /api/auth/verify-code
{ "email": "...", "code": "...", "issueApiKey": true }

# Read the current cookie-backed web session
GET /api/auth/session

Context links at /ctx/username/token return identity context optimized for AI consumption. Use scope "full" to include private context.

Authenticated Endpoints

Include your API key as a Bearer token. Generate keys from the shell (/settings) or via CLI (youmd keys create).

Authorization: Bearer ym_your_api_key_here

# Your profile
GET  /api/v1/me

# Bundle management
POST /api/v1/me/bundle          # Save bundle
POST /api/v1/me/publish         # Publish latest

# Sources
GET  /api/v1/me/sources         # List connected sources
POST /api/v1/me/sources         # Add a source URL

# Memories
GET  /api/v1/me/memories        # List (optional: ?category=fact&limit=10)
POST /api/v1/me/memories        # Save from external agent

# Context links
POST /api/v1/me/context-links   # Create
GET  /api/v1/me/context-links   # List
DELETE /api/v1/me/context-links # Revoke

# Private context
GET  /api/v1/me/private         # Read private data
POST /api/v1/me/private         # Update private data

# LLM Chat
POST /api/v1/chat               # Non-streaming
POST /api/v1/chat/stream        # SSE streaming

# Enrichment
POST /api/v1/scrape             # Scrape a URL
POST /api/v1/research           # Web research via Perplexity
POST /api/v1/enrich-x           # X/Twitter enrichment
POST /api/v1/enrich-linkedin    # LinkedIn enrichment

Skills API

Programmatic access to the skill registry and your installed skills. Public endpoints are unauthenticated. Install, usage, and publish endpoints require a Bearer token.

# Browse the public skill registry
GET /api/v1/skills

# Fetch a single skill by name (includes full template content)
GET /api/v1/skills?name=claude-md-generator

# List your installed skills (authenticated)
GET /api/v1/me/skills

# Publish a skill to the registry (authenticated)
POST /api/v1/me/skills
{ "name": "...", "description": "...", "content": "...", "version": "1.0.0", "scope": "shared" }

# Record a skill install (authenticated)
POST /api/v1/me/skills/install
{ "skillName": "..." }

# Track skill usage (authenticated)
POST /api/v1/me/skills/usage
{ "skillName": "...", "context": "cli" }

# Remove an installed skill (authenticated)
POST /api/v1/me/skills/remove
{ "skillName": "..." }

MCP Server

You.md exposes a JSON-RPC 2.0 MCP endpoint so AI agents (Claude, Cursor, Windsurf) can natively query identity context. Discover the server via the /.well-known/mcp.json endpoint.

# MCP discovery — auto-configure any MCP-compatible client
GET /.well-known/mcp.json

# JSON-RPC 2.0 MCP endpoint
POST /api/v1/mcp
Content-Type: application/json

# Example: list available tools
{ "jsonrpc": "2.0", "method": "tools/list", "params": {}, "id": 1 }

# Example: get a user's identity
{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "get_identity",
    "arguments": { "username": "houstongolden", "format": "compact" }
  },
  "id": 2
}

Available MCP tools: get_identity, search_profiles, get_my_identity (authenticated). Configure via CLI:

npx --yes youmd@latest mcp --install claude --auto
npx --yes youmd@latest mcp --install cursor --auto
youmd mcp --json             # Print the exact MCP config JSON

Privacy

You.md uses a two-layer privacy model:

Access tokens can be generated from the shell via /tokens. Each token has configurable scope and can be revoked at any time.

Dashboard Commands

The web shell supports the following slash commands: