our-claude-skills/custom-skills/_ourdigital-shared/README.md

# OurDigital Shared Environment

Shared configuration, dependencies, and installation tools for OurDigital Skills package.

## Quick Install

```bash
# Clone the repository (on new machine)
git clone https://github.com/ourdigital/our-claude-skills.git
cd our-claude-skills/custom-skills/_ourdigital-shared

# Run installer
./install.sh
```

## Installation Options

```bash
./install.sh                  # Full interactive install
./install.sh --update         # Update existing installation
./install.sh --uninstall      # Remove installation
./install.sh --validate       # Check installation status
./install.sh --commands       # Only install/update global slash commands
./install.sh --skip-creds     # Skip credentials setup
./install.sh --skip-venv      # Skip virtual environment
./install.sh --help           # Show all options
```

## What Gets Installed

| Component | Location | Description |
|-----------|----------|-------------|
| Global slash commands | `~/.claude/commands/` | Symlinks to repo commands (work from any project) |
| Environment file | `~/.env.ourdigital` | API keys and secrets |
| Config directory | `~/.ourdigital/` | Configuration and credentials |
| Virtual environment | `.venv-ourdigital/` | Python dependencies |

## Global Slash Commands

All custom skills are installed as **global slash commands** via symlinks. This means you can use them from any project directory in Claude Code:

```bash
# These work from ANY project, not just our-claude-skills/
/seo-technical https://example.com
/reference-curator "Claude Code best practices"
/ourdigital-research "topic"
/notebooklm-agent
/gtm-audit https://example.com
```

### How It Works

The installer symlinks all `.md` files from `.claude/commands/` in the repo to `~/.claude/commands/`:

```
~/.claude/commands/
├── lint.md                    # Original global command
├── test.md                    # Original global command
├── seo-technical.md -> /path/to/our-claude-skills/.claude/commands/seo-technical.md
├── seo-keyword-strategy.md -> ...
├── reference-curator.md -> ...
└── ...                        # ~40 symlinked commands
```

Since they're symlinks, pulling repo updates automatically refreshes the commands.

### Updating Commands

After pulling new changes or adding new commands:

```bash
./install.sh --commands    # Re-scan and symlink any new commands
```

## Directory Structure

```
~/.claude/commands/           # Global slash commands (symlinks)
~/.ourdigital/
├── config.yaml               # Global configuration
├── credentials/              # Service account JSONs
│   └── *.json
└── logs/                     # Installation logs

~/.env.ourdigital             # Environment variables (chmod 600)
```

## Manual Setup

If you prefer manual setup:

### 1. Create directories
```bash
mkdir -p ~/.ourdigital/credentials
chmod 700 ~/.ourdigital ~/.ourdigital/credentials
mkdir -p ~/.claude/commands
```

### 2. Symlink global commands
```bash
ln -s /path/to/our-claude-skills/.claude/commands/*.md ~/.claude/commands/
```

### 3. Copy environment template
```bash
cp .env.ourdigital.template ~/.env.ourdigital
chmod 600 ~/.env.ourdigital
```

### 4. Edit credentials
```bash
nano ~/.env.ourdigital
# Add your API keys
```

### 5. Create virtual environment
```bash
python3 -m venv .venv-ourdigital
source .venv-ourdigital/bin/activate
pip install -r requirements/base.txt
```

## Credentials Required

| Service | Variable | How to Get |
|---------|----------|------------|
| Notion | `NOTION_API_TOKEN` | [Notion Integrations](https://www.notion.so/my-integrations) |
| Ghost Blog | `GHOST_BLOG_ADMIN_KEY` | Ghost Admin > Integrations |
| Ghost Journal | `GHOST_JOURNAL_ADMIN_KEY` | Ghost Admin > Integrations |
| Figma | `FIGMA_ACCESS_TOKEN` | [Figma Settings](https://www.figma.com/developers/api#access-tokens) |

### Using 1Password CLI

If you have 1Password CLI (`op`) installed:
```bash
# Sign in
eval $(op signin)

# Installer will auto-fetch credentials
./install.sh
```

## Validation

Check your installation status:

```bash
# Quick check
./install.sh --validate

# Detailed check
python scripts/validate_install.py --verbose
```

## Cross-Machine Sync

To sync skills to another machine:

```bash
# On new machine
git clone https://github.com/ourdigital/our-claude-skills.git
cd our-claude-skills/custom-skills/_ourdigital-shared
./install.sh

# Credentials need to be set up separately (security)
# Either use 1Password CLI or manually copy ~/.env.ourdigital
```

## Troubleshooting

### Permission denied
```bash
chmod +x install.sh
```

### Python version
```bash
# Check version (need 3.11+)
python3 --version

# Use pyenv if needed
pyenv install 3.11
pyenv local 3.11
```

### Missing credentials
```bash
# Check what's missing
python scripts/validate_install.py --verbose
```

### Commands not showing in Claude Code
```bash
# Check symlinks are intact
ls -la ~/.claude/commands/

# Re-install commands
./install.sh --commands
```

## File Reference

| File | Purpose |
|------|---------|
| `install.sh` | Main installer script |
| `.env.ourdigital.template` | Environment template |
| `config/ourdigital.yaml` | Default configuration |
| `requirements/base.txt` | Common dependencies |
| `requirements/code.txt` | Claude Code dependencies |
| `scripts/validate_install.py` | Installation validator |