Manage, sync, and export AI Agent Skills across coding tools.

---

loadout stores skills in the Agent Skills open standard format (YAML frontmatter + Markdown) and loads them into Claude Code, Codex, Gemini CLI, Cursor, GitHub Copilot, and ChatGPT.

Install

# Clone and install locally
git clone https://github.com/wiggleji/loadout.git
cd loadout
npm install
npm run build
npm link

After npm link, the loadout command is available globally.

Quick Start

# 1. Initialize loadout
loadout init

# 2. Create a skill
loadout create my-skill -d "TypeScript best practices" -t "typescript,code-style"

# 3. Edit the skill instructions
#    Open ~/.loadout/skills/my-skill/SKILL.md in your editor

# 4. Load the skill into your AI tool (interactive)
loadout load my-skill

The load command prompts you to pick which AI tool to load into:

? Which AI tool do you want to load skills into?
❯ Claude Code       — Generates CLAUDE.md in current directory
  Codex (OpenAI)    — Generates AGENTS.md in current directory
  Gemini CLI        — Generates GEMINI.md in current directory
  Cursor            — Generates .cursor/rules/{name}.mdc
  GitHub Copilot    — Generates .github/instructions/{name}.instructions.md
  ChatGPT           — Generates chatgpt-instructions/{name}.md

Select one with arrow keys and press Enter. The skill is exported to the chosen format in your current working directory.

Skill Format

Skills follow the Agent Skills spec. Each skill is a directory under ~/.loadout/skills/:

my-skill/
├── SKILL.md          # YAML frontmatter + markdown instructions
├── scripts/          # Optional executable code
├── references/       # Optional reference docs (inlined on export)
└── assets/           # Optional templates, data

Example SKILL.md:

---
name: my-skill
description: TypeScript best practices
version: 0.1.0
tags:
  - typescript
  - code-style
globs:
  - "*.ts"
  - "*.tsx"
alwaysApply: false
---

# TypeScript Best Practices

- Use strict mode
- Prefer `const` over `let`
- Use ESM imports with `.js` extensions
- Define types with interfaces, not type aliases, when possible

Commands

Skill Management

loadout init                    # Initialize ~/.loadout/
loadout create <name>           # Create a new skill
  -d, --description <desc>     #   Skill description
  -t, --tags <tags>            #   Comma-separated tags
loadout list                    # List all skills
loadout show <name>             # Show skill details
loadout validate [name]         # Validate against Agent Skills spec
loadout delete <name>           # Delete a skill
loadout import <path>           # Import a skill from a directory

Loading & Exporting

# Interactive — pick your AI tool from a menu
loadout load [names...]
  -o, --output <dir>           #   Output directory (default: .)

# Direct — specify the format explicitly
loadout export <format> [names...]
  -o, --output <dir>           #   Output directory (default: .)

Supported formats:

Format	Output File	Tool
claude-code	CLAUDE.md	Claude Code (Anthropic CLI)
codex	AGENTS.md	OpenAI Codex CLI
gemini-cli	GEMINI.md	Google Gemini CLI
cursor	.cursor/rules/{name}.mdc	Cursor
copilot	.github/instructions/{name}.instructions.md	GitHub Copilot
chatgpt	chatgpt-instructions/{name}.md	ChatGPT

If no skill names are given, all skills are exported.

Cloud Sync

Sync skills across devices via Google Drive or iCloud.

loadout login                   # Interactive — pick Google Drive or iCloud
loadout logout                  # Interactive — pick provider to log out
loadout sync                    # Bidirectional sync
loadout push [names...]         # Push skills to cloud
loadout pull [names...]         # Pull skills from cloud
loadout status                  # Show sync status

Google Drive — works on all platforms. Requires a one-time OAuth setup (see Google Drive Setup below):

loadout login                   # Select "Google Drive" → prompts for credentials on first run → opens browser
loadout sync                    # Bidirectional sync

iCloud — macOS only, no credentials needed. Uses your local iCloud Drive directory (~/Library/Mobile Documents/com~apple~CloudDocs/.loadout/). Skills are synced automatically by macOS to all devices signed into the same Apple ID.

loadout login                   # Select "iCloud" → verifies iCloud Drive exists
loadout sync

iCloud sync is not supported on Windows or Linux. An error will be shown if you try.

Configuration

loadout config                  # Show all config
loadout config <key>            # Get a value
loadout config <key> <value>    # Set a value

Key settings:

Key	Default	Description
skillsDir	~/.loadout/skills	Skills directory
conflictStrategy	last-write-wins	Sync conflict resolution (last-write-wins, local-wins, remote-wins, manual)
cloudProvider	—	Cloud provider (google-drive, icloud)
autoSync	false	Auto-sync on push/pull

Google Drive Setup

To sync skills via Google Drive, you need to create your own Google OAuth credentials (free, takes ~5 minutes).

1. Create a Google Cloud Project

1. Go to Google Cloud Console
2. Click Select a project (top bar) → New Project
3. Name it anything (e.g. loadout) → Create

2. Enable the Google Drive API

1. Go to APIs & Services > Library
2. Search for Google Drive API
3. Click it → Enable

3. Configure the OAuth Consent Screen

1. Go to APIs & Services > OAuth consent screen
2. Select External → Create
3. Fill in:
   • App name: loadout (or anything you like)
   • User support email: your email
   • Developer contact email: your email
4. Click Save and Continue through the remaining steps (Scopes, Test users) — defaults are fine
5. On the Test users step, add your own Google email address

While in "Testing" mode, only the test users you add can log in. This is fine for personal use. To let anyone log in, you'd need to publish and verify the app with Google.

4. Create OAuth Credentials

1. Go to APIs & Services > Credentials
2. Click + Create Credentials → OAuth client ID
3. Application type: Desktop app
4. Name: loadout (or anything)
5. Click Create
6. Copy the Client ID and Client Secret

5. Log In

loadout login
# Select "Google Drive"
# Paste your Client ID and Client Secret when prompted
# Browser opens → sign in with Google → done

Your credentials are saved locally — you only need to enter them once. On subsequent logins, loadout login goes straight to the browser OAuth flow.

You can also set them manually if you prefer:

loadout config googleDrive.clientId <your-client-id>
loadout config googleDrive.clientSecret <your-client-secret>
loadout login    # Select "Google Drive" → opens browser directly

Examples

Load a skill into Claude Code

loadout create typescript-rules -d "TypeScript conventions"
# Edit ~/.loadout/skills/typescript-rules/SKILL.md

cd ~/my-project
loadout load typescript-rules
# Select "Claude Code" → writes CLAUDE.md in ~/my-project/

Export all skills to Cursor

cd ~/my-project
loadout export cursor
# Writes .cursor/rules/{name}.mdc for each skill

Import an existing skill

# If you have a skill directory somewhere
loadout import ~/Downloads/my-shared-skill
loadout list  # Now shows my-shared-skill

Sync across devices (Google Drive)

# On device A
loadout login            # Select "Google Drive", enter OAuth credentials
loadout push

# On device B
loadout login            # Select "Google Drive", enter same OAuth credentials
loadout pull

Sync across Macs (iCloud)

# On Mac A
loadout login            # Select "iCloud"
loadout push

# On Mac B — skills appear automatically via iCloud Drive
loadout login            # Select "iCloud"
loadout pull

Development

npm install          # Install dependencies
npm run build        # Build with tsup
npm test             # Run tests (vitest)
npm run typecheck    # Type check
npm run dev          # Watch mode build

Project Structure

src/
├── cli/             # Commander setup + 16 commands
├── lib/
│   ├── skill/       # Types, parser, serializer, validator, manager
│   ├── sync/        # Engine, manifest, differ, resolver, lock
│   ├── providers/   # CloudProvider interface, Google Drive, iCloud
│   ├── export/      # 6 exporters (cursor, copilot, chatgpt, claude-code, codex, gemini-cli)
│   ├── auth/        # Google OAuth, iCloud auth, credential store
│   └── config/      # Types, defaults, loader
└── utils/           # FS helpers, hash, logger, errors

License

MIT