# Jup

> jup: Agent Skills Manager ✨

- Skill: `andrader/jup` (Agent Skill)
- Install (CLI): `npx skillmds@latest add andrader/jup`
- Raw SKILL.md: https://api.skillmd.com/api/skills/andrader/jup/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: andrader (https://skillmd.com/u/andrader)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/andrader/jup

---

# jup: Agent Skills Manager ✨

`jup` is a lightweight Python-based command-line tool designed to manage and synchronize "agent skills" across various AI assistant directories (e.g., Gemini, Copilot, Claude). It allows users to install skills from GitHub repositories or local directories, keeping them organized via a lockfile and syncing them to target locations using symlinks or file copies.

## Core Concepts

- **Skills**: A directory containing a `SKILL.md` file.
- **Syncing**: Linking or copying skills from your local cache (`~/.jup/skills/`) to agent-specific directories (e.g., `~/.gemini/skills/`).
- **Lockfile**: A central record of all installed skill sources and their metadata.

## Usage Instructions

### Adding Skills
You can add skills from GitHub repositories, URLs, or local paths.

- **GitHub Repository**: `jup add owner/repo`
- **GitHub URL**: `jup add https://github.com/owner/repo/tree/branch/path`
- **Versioning**: `jup add owner/repo@v1.0.0` (Supports tags, SHAs, or branches).
- **Exact Path**: `jup add owner/repo/path/to/skill` (Faster installation for large repos).
- **Targeting**:
  - `--agent (-a) name`: Install to specific agent(s).
  - `--scope user|local`: Set target scope.
  - `--dir path`: Install to a custom directory (overrides agent/scope).
- **Options**:
  - `--category (-c) name`: Category (default: `misc`).
  - `--skills name1,name2`: Select specific skills from a collection.

### Listing Skills
Check the status of your skills with flexible aliases:
- `jup list` or `jup ls`: Shows installed skills, versions, and origins.
- `jup ls skills`: Alias for `jup list`.
- `jup ls agents` or `jup ls agent`: Lists configured harness providers.
- `jup ls config`: Shows current configuration.
- `jup list --json`: Outputs status in clean, machine-readable format.

### Syncing
Push your managed skills to agents:
- `jup sync`: Updates all links/copies in configured agent directories.
- `jup sync --update` (or `jup up`): Checks GitHub for updates.

### Searching Registry
- `jup find query`: Search the `skills.sh` registry.
- `jup find query -it`: Interactive mode to preview and install skills.

### Configuration
Manage your environment:
- `jup config show`: View current settings (renamed `global` scope to `user`).
- `jup config set sync-mode copy`: Switch from symlinks to file copies.

## Agent Specifics
`jup` supports built-in paths for:
- `gemini`: `~/.gemini/skills`
- `copilot`: `~/.copilot/skills`
- `claude`: `~/.claude/skills`
- `cursor`: `~/.cursor/skills`
- `codex`: `~/.codex/skills`
- `antigravity`: `~/.gemini/antigravity/skills`
- `default`: `~/.agents/skills`

You can add custom agents with `jup agent add`.