The Library

A meta-skill for private-first distribution of agentics (skills, agents, and prompts) across agents, devices, and teams.

Why

The Library solves a specific problem: we've built powerful agentics scattered across repos, devices, and teams. They're duplicated, out of sync, and hard to coordinate. This gives us a single reference catalog to distribute them privately.

What It Is

The Library is a single skill whose only job is to manage other skills. It's a catalog of references — local file paths and GitHub repo URLs — that point to where your agentics live. Nothing is copied or installed until we ask for it.

Think of it as a package.json for agent capabilities — but instead of packages, you're managing skills, agents, and prompts. Instead of a registry, you're pointing at your own private GitHub repos and local paths.

This is a pure agent application. There are no scripts, no CLIs, no dependencies, no build tools. The entire application is encoded in SKILL.md and a set of cookbook instructions that teach the agent exactly what to do. The agent IS the runtime. This matters because:

• Any agent harness that reads skill files can run it (Claude Code, Pi, etc.)
• You can modify behavior by editing markdown, not code
• The skill can be extended, forked, and adapted instantly
• An orchestrator agent can chain library commands without any tooling overhead

Why It Exists

As we build with AI agents, you accumulate skills, custom agents, and prompts — potentially hundreds of them. We need to:

• Reuse them across projects without copy-pasting
• Distribute them to your agents running on other devices (Mac mini, remote servers, cloud sandboxes)
• Share them with your team without making everything public
• Keep them private — these are specialized capabilities built for competitive edge
• Stay in sync — one source of truth, not 10 stale copies

Existing solutions don't fit:

• Global ~/.claude/* — exposes everything to every agent. Global is the opposite of specialized.
• Claude Code plugins — requires marketplace infrastructure, manifests, and locks you into one platform.
• Single monorepo — doesn't reflect reality. You build agentics in specific codebases for specific use cases.

How It Works

The Catalog (library.yaml)

default_dirs:
  skills:
    - default: .claude/skills/
    - global: ~/.claude/skills/
  agents:
    - default: .claude/agents/
    - global: ~/.claude/agents/
  prompts:
    - default: .claude/commands/
    - global: ~/.claude/commands/

library:
  skills:
    - name: my-skill
      description: What this skill does
      source: /Users/me/projects/tools/skills/my-skill/SKILL.md
      requires: [agent:helper-agent]
    - name: remote-skill
      description: A skill from a private repo
      source: https://github.com/myorg/private-skills/blob/main/skills/remote-skill/SKILL.md
  agents: []
  prompts: []

The catalog stores pointers, not copies. Skills live in their source repos. You pull on demand.

Source Formats

Format	Example
Local filesystem	/absolute/path/to/SKILL.md
GitHub browser URL	https://github.com/org/repo/blob/main/path/to/SKILL.md
GitHub raw URL	https://raw.githubusercontent.com/org/repo/main/path/to/SKILL.md

The source points to a specific file. The system pulls the entire parent directory (skills include scripts, references, assets — not just the markdown file).

For private repos, authentication uses SSH keys or GITHUB_TOKEN automatically.

Typed Dependencies

Dependencies use typed references to avoid name collisions:

requires: [skill:base-utils, agent:reviewer, prompt:task-router]

Dependencies are resolved and pulled first, recursively.

Prerequisites

• Claude Code (or a compatible agent harness that reads .claude/skills/ — e.g., Pi)
• git — for cloning sources and syncing the catalog
• gh (optional) — GitHub CLI for forking, cloning, and private repo access. Install: brew install gh or see gh docs
• GitHub SSH key or GITHUB_TOKEN — for accessing private repos (not needed if using gh auth login)
• just (optional) — for justfile shortcuts. Install: brew install just or see just docs

Installation

Clone the repo into your global skills directory, and it becomes a /library slash command available in every Claude Code session.

1. Clone to Global Skills Directory

Clone your fork into ~/.claude/skills/library. This path is what makes /library available as a global slash command in Claude Code.

# Using git
mkdir -p ~/.claude/skills/library
gh repo clone pixelkode/agent-library ~/.claude/skills/library

2. Configure

Open ~/.claude/skills/library/SKILL.md and update the ## Variables section with your fork URL. The agent reads these variables at runtime to know where to sync the catalog.

# Before (template defaults)
- **LIBRARY_REPO_URL**: `<your forked repo url>`

# After (your values)
- **LIBRARY_REPO_URL**: `https://github.com/yourname/the-library.git`

The other two variables (LIBRARY_YAML_PATH and LIBRARY_SKILL_DIR) are correct by default if you cloned to ~/.claude/skills/library/.

3. Verify

Start a new Claude Code session anywhere. /library list should work and show an empty catalog.

Quick Start

Here's the typical workflow: build → catalog → distribute → use.

Add a skill to the catalog

You built a deploy skill in one of your repos. Register it:

/library add deploy skill from https://github.com/yourorg/infra-tools/blob/main/skills/deploy/SKILL.md

This adds a reference to library.yaml and pushes the update to your fork.

Use it in another project

On another device, repo, or agent:

/library use deploy

This pulls the skill from the source repo into .claude/skills/deploy/.

Want it globally available on this machine?

/library use deploy install globally

Push changes back

You improved the skill locally. Push the update to the source repo:

/library push deploy

Now every device that runs /library sync gets the latest version.

Sync everything

Pull the latest version of all installed items:

/library sync

Commands

Command	What It Does
/library add <details>	Register a new entry in the catalog
/library use <name>	Pull from source into local directory (install or refresh)
/library push <name>	Push local changes back to the source
/library remove <name>	Remove from catalog and optionally delete local copy
/library list	Show full catalog with install status
/library sync	Re-pull all installed items from source
/library search <keyword>	Find entries by name or description

Justfile Shortcuts

The included justfile lets you run library commands from your terminal without an interactive Claude session.

just list                  # List catalog
just use my-skill          # Pull a skill
just push my-skill         # Push changes back
just add "name: foo, description: bar, source: /path/to/SKILL.md"
just sync                  # Re-pull all installed items
just search "keyword"

Architecture

~/.claude/skills/library/     # The Library skill (globally installed)
    SKILL.md                  # Agent instructions — the brain
    library.yaml              # Your catalog of references
    cookbook/                  # Step-by-step guides for each command
        install.md
        add.md
        use.md
        push.md
        remove.md
        list.md
        sync.md
        search.md
    justfile                  # CLI shorthand for all commands
    README.md                 # This file

Design Principles

• Private-first: Built for your specialized custom agentics. Not a public marketplace.
• Reference-based: The catalog stores pointers, not copies. Skills live in their source repos.
• Pure agent: No scripts, no build tools. The SKILL.md teaches the agent everything it needs to know.
• Agent-agnostic: Default target is .claude/skills/ but supports any directory for any agent harness.
• Catalog, not manifest: Entries define what's available, not what's installed. Pull on demand.

The Agentic Stack

Layer	Purpose
Skills	Raw capabilities — what an agent can do
Agents	Scale + parallelism + specialization
Prompts	Orchestration — coordinate skills and agents
Justfile	Terminal access without an interactive session
The Library	Distribution across devices, teams, and agents