📦 arc

arc

Agentic skill package manager.

Install, discover, and share skills, tools, agents, and prompts
with capability-based trust and multi-source registries.

---

Your Agent Needs More Skills

Claude Code skills are powerful but non-distributable. Each user's skill directory is a local collection with no mechanism for discovery, installation, or sharing between users.

arc is apt install for agentic skills. It manages the full lifecycle — search a registry, review capabilities, install with one command, audit what's running.

arc search doc                # Find packages across all sources
arc install _DOC              # Install with capability review
arc audit                     # See your total attack surface

What It Installs

arc handles multiple artifact types:

Type	Installed To	What It Is
Skill	~/.claude/skills/{name}/	Directory with SKILL.md + workflows
Tool	~/.claude/bin/{name} + PATH shim	CLI command you can run directly
Agent	~/.claude/agents/{name}.md	Persona file -- auto-discovered as subagent_type
Prompt	~/.claude/commands/{name}.md	Slash command template
Library	~/.config/metafactory/pkg/repos/	Multi-artifact repo containing skills, tools, etc.
Action	~/.config/metafactory/actions/{name}/	Pulse action (action.json + action.ts)
Rules	~/.claude/skills/{name}/	Configurable rules templates (e.g. CLAUDE.md generators)

---

Quick Start

# Install arc
git clone https://github.com/the-metafactory/arc.git
cd arc && bun install && bun link

# Fetch the community registry
arc source update

# Search and install
arc search doc
arc install _DOC

Requires Bun (v1.0+) and Git. Optional: GitHub CLI (gh) for release notes in arc info. See QUICKSTART.md for the full walkthrough.

---

Commands

Package Management

arc install <name-or-url>     # Install from registry or git URL
arc list                      # List installed packages
arc info <name>               # Show details, capabilities, and release notes
arc audit                     # Audit capability surface (summary + cross-tier warnings)
arc audit --verbose           # Full pairwise capability combination list
arc disable <name>            # Disable (preserves repo)
arc enable <name>             # Re-enable a disabled package
arc remove <name>             # Completely uninstall
arc verify <name>             # Verify manifest integrity

Upgrades

arc upgrade --check           # Check for available upgrades (compares against registry)
arc upgrade                   # Upgrade all packages
arc upgrade <name>            # Upgrade a specific package
arc self-update               # Update arc itself (git pull + bun install)
arc upgrade-core <version>    # Upgrade core (symlink management)

Discovery

arc search <keyword>          # Search all configured sources

Source Management

arc source list               # Show configured registry sources
arc source add <n> <url>      # Add a source (--tier official|community|custom)
arc source update             # Refresh indexes from all sources (like apt update)
arc source remove <name>      # Remove a source

Catalog

The catalog is a local catalog.yaml tracking available artifacts (built-in skills, agents). It complements the registry — the registry is for community-published packages, the catalog is for known artifacts you may want to install.

arc catalog list              # List catalog with install status
arc catalog search <keyword>  # Search catalog by name or description
arc catalog add <name>        # Add entry (--from-registry to pull from sources)
arc catalog remove <name>     # Remove entry from catalog
arc catalog use <name>        # Install from catalog (resolves deps)
arc catalog sync              # Re-pull all installed catalog entries
arc catalog push <name>       # Push local changes back to source
arc catalog push-catalog      # Commit and push catalog.yaml to git remote

Scaffolding

arc init my-skill             # Scaffold a new skill repo
arc init my-tool --type tool  # Scaffold a tool
arc init my-agent --type agent
arc init my-prompt --type prompt

Each scaffold includes arc-manifest.yaml, package.json, README.md, .gitignore, and type-specific files (SKILL.md + workflows, agent persona, prompt template, or tool entry point).

Bundle and Publish

arc bundle [path]             # Create a .tar.gz from a package directory
arc bundle --output out.tar.gz  # Custom output path
arc publish [path]            # Bundle, upload, and register on metafactory
arc publish --dry-run         # Validate without uploading
arc publish --tarball f.tar.gz  # Publish from existing tarball
arc publish --scope <ns>      # Override publish namespace
arc publish --source <name>   # Target specific metafactory source

Authentication

arc login                     # Authenticate with metafactory (device code flow)
arc login --source <name>     # Authenticate with a specific source
arc logout                    # Remove authentication token

---

How It Works

  sources.yaml             Registry Sources              arc                  Your Machine
  ────────────             ────────────────              ───────                  ────────────
       │                          │                         │                         │
       │  community hub           │                         │                         │
       │  personal (custom)       │                         │                         │
       │─────────────────────────►│                         │                         │
       │                          │                         │                         │
       │                          │  source update          │                         │
       │                          │  (fetch REGISTRY.yaml)  │                         │
       │                          │◄────────────────────────│                         │
       │                          │                         │                         │
       │                          │  cached indexes         │                         │
       │                          │────────────────────────►│  search "doc"           │
       │                          │                         │  (queries cached files)  │
       │                          │                         │                         │
       │                          │                         │  install _DOC           │
       │                          │                         │  → git clone            │
       │                          │                         │─────────────────────────►
       │                          │                         │                         │
       │                          │                         │  read arc-manifest.yaml │
       │                          │                         │  display capabilities   │
       │                          │                         │  user confirms          │
       │                          │                         │                         │
       │                          │                         │  symlink → skills/      │
       │                          │                         │  record in packages.db  │
       │                          │                         │─────────────────────────►
       │                          │                         │                         │

The flow:

1. arc source update fetches REGISTRY.yaml from each source in sources.yaml and caches locally
2. arc search queries the cached indexes across all enabled sources
3. arc install resolves the package from the registry, clones the source repo via git
4. Reads arc-manifest.yaml — the capability declaration
5. Displays capabilities and risk level for user approval
6. Creates symlinks to the appropriate Claude directory
7. For tools: runs bun install and creates CLI shim on PATH
8. Records metadata in SQLite (packages.db)

No npm. No Docker. Just git clone, symlinks, and a manifest.

---

Multi-Source Registry

arc supports multiple registry sources, like apt's sources.list:

# ~/.config/metafactory/sources.yaml (auto-created on first run)
sources:
  - name: community
    url: https://raw.githubusercontent.com/mellanon/pai-collab/main/skills/REGISTRY.yaml
    tier: community
    enabled: true

Add additional sources:

arc source add my-team https://raw.githubusercontent.com/my-org/registry/main/REGISTRY.yaml --tier community
arc source update            # Fetch indexes from all sources

Search aggregates results across all enabled sources, showing the source name and trust tier for each match.

---

Trust Model

Trust flows from the source, not the package:

Tier	Install Behavior	Example Source
official	Auto-approves, minimal display	Upstream maintained packages
community	Shows capabilities, requires confirmation	Community registries
custom	Risk warning, full capability review	Direct git URL installs

Capability Declarations

Every package declares what it accesses in arc-manifest.yaml:

capabilities:
  filesystem:
    read: ["~/.claude/MEMORY/"]
    write: ["~/.claude/MEMORY/WORK/"]
  network:
    - domain: "*.atlassian.net"
      reason: "Jira REST API"
  bash:
    allowed: true
    restricted_to: ["bun src/jira.ts *"]
  secrets: ["JIRA_URL", "JIRA_API_TOKEN"]

Audit

arc audit shows your total attack surface and detects dangerous capability compositions across installed packages:

• Summary mode (default): grouped composition stats + cross-tier warnings only
• Verbose mode (--verbose): full pairwise list of all capability combination warnings

Cross-tier warnings surface when a community package's capabilities combine dangerously with your personal packages — the actually interesting signals. Same-tier combinations (your own skills) are summarized as expected.

---

Package Format

A package is a git repo with arc-manifest.yaml at root:

arc-skill-example/
├── arc-manifest.yaml       # Capability declaration (required)
├── skill/                  # Skill directory (skills)
│   ├── SKILL.md
│   └── workflows/
├── agent/                  # Agent directory (agents)
│   └── AgentName.md
├── prompt/                 # Prompt directory (prompts)
│   └── prompt-name.md
├── src/                    # Source code (tools, skills with CLI)
│   └── tool.ts
├── package.json            # Bun dependencies (optional)
└── README.md

arc-manifest.yaml

name: _DOC
version: 1.0.0
type: skill                 # skill | tool | agent | prompt
tier: community

author:
  name: mellanon
  github: mellanon

provides:
  skill:
    - trigger: "doc"
  cli:
    - command: "bun src/doc.ts"
      name: "doc"

depends_on:
  tools:
    - name: bun
      version: ">=1.0.0"

capabilities:
  filesystem:
    read: []
    write: ["**/*.html"]
  network: []
  bash:
    allowed: false
  secrets: []

---

Running Tests

bun test                    # All 457 tests
bun test:unit               # Unit tests only
bun test:commands           # Command tests
bun test:e2e                # End-to-end lifecycle tests

Tests run in isolated temp directories — never touch real ~/.claude/ or ~/.config/.

---

Versioning

Packages use semver. The canonical version lives in arc-manifest.yaml:

version: 1.2.0

Convention: bump the version, tag the commit, create a GitHub Release:

# After updating arc-manifest.yaml version to 1.2.0
git tag v1.2.0
git push origin v1.2.0
gh release create v1.2.0 --title "v1.2.0" --notes "## What Changed
- Added new workflow for X
- Fixed Y bug in Z"

Tags must match the manifest version (tag v1.2.0 ↔ manifest version: 1.2.0).

GitHub Releases are the changelog — no separate CHANGELOG.md needed. arc info fetches and displays release notes directly via the gh CLI.

Registry entries include a version field to advertise the latest available version. arc upgrade --check compares installed versions against registry versions. Pinned installs (arc install MySkill@1.2.0) are planned for a future release.

---

Publishing

arc supports publishing packages to the metafactory registry. This is the counterpart to arc install @scope/name -- you bundle your package locally and publish it to the registry where others can install it.

Quick Publish

# 1. Authenticate (one-time)
arc login

# 2. Set your namespace in arc-manifest.yaml
#    namespace: my-namespace

# 3. Publish
arc publish

How Publishing Works

arc publish
  1. Read arc-manifest.yaml
  2. Validate: name, version (semver), type, capabilities
  3. Create .tar.gz (excludes .git, node_modules, .env, test/, etc.)
  4. Upload tarball to R2 storage (content-addressed by SHA-256)
  5. Verify SHA-256: client hash must match server hash
  6. Auto-create package entry on first publish
  7. Register version (immutable -- cannot overwrite)

Scope Resolution

The publish namespace is resolved in priority order:

1. --scope flag: arc publish --scope my-namespace
2. namespace field in arc-manifest.yaml
3. Account default from /auth/me API

Bundle Exclusions

By default, these patterns are excluded from the tarball:

.git, node_modules, .env, .env.*, *.db, *.sqlite, .DS_Store, Thumbs.db, .specify, test, tests, dist, *.log, .wrangler, .claude

Override in arc-manifest.yaml:

bundle:
  exclude:
    - "*.tmp"
    - "coverage"
  include:
    - "test"           # Override default exclusion

Dry Run

Preview what would be published without uploading:

arc publish --dry-run
# [DRY RUN] Would publish @my-namespace/my-skill v1.0.0
#   SHA-256:  abc123...
#   Source:   metafactory

Pre-built Tarballs

Skip the bundle step and publish an existing tarball:

arc bundle --output my-skill-1.0.0.tar.gz
# ... inspect tarball contents ...
arc publish --tarball my-skill-1.0.0.tar.gz

Size Limits

• Tarballs exceeding 50MB are rejected before upload
• Tarballs exceeding 10MB produce a warning

Version Immutability

Published versions cannot be overwritten. To publish changes, bump the version in arc-manifest.yaml first:

# After editing arc-manifest.yaml to version: 1.1.0
arc publish

Re-running arc publish with the same version returns a clear error: "Version 1.0.0 already exists. Published versions are immutable."

Requirements

• Authenticated with arc login
• Valid arc-manifest.yaml with name (lowercase alphanumeric), version (semver), and type
• A README.md is recommended but not required
• All capabilities must be honestly declared

---

Acknowledgments

• SkillSeal by Ian McCutcheon — Cryptographic signing framework for Claude Code skills (future integration)
• SpecFlow by Jens-Christian Fischer — The arc-manifest.yaml capability format is adapted from SpecFlow's manifest schema
• Debian Project — The multi-tier trust model is inspired by Debian's main/contrib/non-free architecture

License

MIT