# OakShelf

> OakShelf is an open-source home for agent capabilities: a package manager, registry, resolver, and adapter layer for agent skills, tools, and workflows. It gives agent capabilities a versioned package lifecycle and links verified packages into AI agents. Claude and Codex adapters ship today, and adapters for more harnesses are planned.

OakShelf treats agent skills as software: packages have manifests, immutable semantic versions, deterministic bundles, dependency graphs, pinned digests, and a lockfile. The installed copy is provider-neutral and stays the source of truth. Agent adapters project compatible skill entrypoints into `.claude/skills/` or `.codex/skills/`, project-locally or globally.

## Core lifecycle

```text
package directory
  -> validate
  -> deterministic .oakpack bundle
  -> publish to registry
  -> resolve semantic version and dependencies
  -> download and verify SHA-256 digests
  -> install static files
  -> write oakshelf.lock.json
  -> link compatible skills into an agent
```

## Key capabilities

- Package skills, tools, and workflows as plain files plus `oakshelf.json`.
- Resolve recursive dependency graphs with cycle and conflict detection.
- Publish immutable package versions to a registry.
- Pin exact versions and digests in `oakshelf.lock.json`.
- Verify installed files and linked agent projections for drift.
- Inspect installed packages and preview candidate updates with `oak diff`.
- Link and unlink packages in Claude and Codex without executing package code.
- Install project-locally or into a user-level global store.
- Approve, sync, detect outdated packages, and roll back lockfile changes.

## Trust boundary

OakShelf verifies transport and storage integrity: installed bytes match the published package and the digest pinned in the lockfile. It does not review package instructions, vouch for publisher identity, scan for malware, audit licenses, or sandbox an agent. A package can be faithfully delivered and still be harmful. Read package files before linking them into an agent.

## Included examples

- `@recipes/meal-planner`: a composed workflow that depends on recipe intake, recipe personalization, and a calendar-invite tool.
- `@my-company/client-onboarding`: an illustrative company workflow composed from intake, policy-review, and internal policy packages.
- `@oakshelf/hello-skill`: a minimal skill package.

## Status

OakShelf is open source and in early access. The package lifecycle works end to end; the hosted registry and CLI distribution are still early. Marketplace features are not the current focus.

## Links

- Website: https://oakshelf.co/
- Source and quickstart: https://github.com/getoakshelf/oakshelf
- Trust model: https://github.com/getoakshelf/oakshelf/blob/main/TRUST.md
- Early access: https://oakshelf.co/#early-access
- Email: hello@oakshelf.co