Loom documentation

Loom is a package manager for AI skills. It installs, inspects, and authors reusable skills for AI agents such as Claude Code, OpenAI Codex, and Cursor.

A skill is a folder of instructions and helper files an agent loads to do a job well — writing PDFs, building slide decks, designing artifacts, and so on. Loom does for those skills what Homebrew does for command-line tools: a shared repository of manifests describes where each skill lives and how to fetch it, and Loom weaves the payload into your agent's skills folder on request.

A manifest never contains the skill payload itself. It only describes how to obtain and place a skill, in the spirit of a Homebrew formula. That keeps the repository small and lets skills live in their own upstream projects, maintained by the people who wrote them.

Concepts

Four nouns carry the whole system. If the mental model is right, every command follows from it.

The flow from recipe to installed skill:

skills/pdf.yml            loom install pdf           ~/.claude/skills/pdf/
the recipe        ───▶   fetch + verify      ───▶   the payload
name, source URL,         clone at the pinned         SKILL.md and its
ref, subdir               ref, check the entry        helper files

Installation

Loom is a single Rust binary. Pick whichever route suits you.

Homebrew (macOS & Linux)

brew install wess/packages/loom

Install script (macOS & Linux)

curl -fsSL https://raw.githubusercontent.com/wess/loom/main/scripts/install.sh | sh

It detects your OS and architecture, downloads the matching release, verifies its checksum, and drops loom on your PATH. Set LOOM_VERSION to pin a version, or LOOM_BIN_DIR to choose the install directory.

Prebuilt binaries

Grab a .tar.gz for your platform from the releases page — builds are published for macOS and Linux on both x86_64 and aarch64 — then extract loom onto your PATH.

From source

Needs a Rust toolchain; get one from rustup.rs.

cargo install --git https://github.com/wess/loom

Or clone first, to read the source or work on it:

git clone https://github.com/wess/loom
cd loom
cargo install --path .

Requirements

Confirm the install and check the environment in one step:

loom --version
loom doctor

loom doctor verifies that git is reachable, that Loom's home directory is writable, that config.json parses, and that the manifest repository can be read. It exits successfully even when it finds problems — read its output, do not just check the exit code.

Quickstart

Sync the repository first. Loom searches a local clone of it, and until that clone exists there is nothing to search.

# sync the manifest repository (do this first)
loom update

# search the repository
loom search pdf

# read the details before installing
loom info pdf

# install into the default agent (Claude Code)
loom install pdf

# see what's installed
loom list

By default Loom installs into Claude Code at ~/.claude/skills. Target a different agent with --agent:

loom install pdf --agent codex

Keep everything current by refreshing the recipes, then acting on them:

loom update    # pull the newest manifests
loom upgrade   # reinstall skills whose pinned version moved

CLI reference

Every command Loom ships with. Run loom <command> --help for full flags. Loom exits non-zero and prints an error: line to stderr when a command fails.

Consuming skills

Authoring skills

Environment

Manifest format

A manifest is a YAML file named <skill_name>.yml (or .yaml) that lives in a Loom repository's skills/ folder. It describes how to fetch and lay down exactly one skill.

name: pdf              # unique id, lowercase, no whitespace
version: 1.0.0         # the version this manifest pins
description: Read, fill, and generate PDF documents.
homepage: https://github.com/anthropics/skills
license: MIT
authors:
  - Anthropic <support@anthropic.com>
keywords:
  - pdf
  - documents
compatibility:
  - claude-code
  - codex

source:
  type: git            # git | archive
  url: https://github.com/anthropics/skills
  ref: v1.0.0          # git tag, branch, or commit (git sources)
  # sha256: <hex>      # required for archive sources
  subdir: skills/pdf   # folder inside the source that is the skill

install:
  entry: SKILL.md      # the file an agent loads first
  files: []            # explicit paths to include; empty copies everything

Field reference

Sources

Git sources are shallow-cloned with the system git at the pinned ref. Because a shallow clone cannot check out an arbitrary commit by branch name, Loom silently retries with a full clone and a git checkout when the ref is a commit SHA. Tags and branches take the fast path.

source:
  type: git
  url: https://github.com/you/skills
  ref: v1.2.0          # tag and branch: fast. commit SHA: slower fallback.
  subdir: changelog

Archive sources are downloaded over HTTPS, verified against sha256, and unpacked as a gzip tarball. Many tarballs wrap their contents in a single top-level directory; Loom descends into it automatically, so subdir is always relative to the real project root.

source:
  type: archive
  url: https://example.com/skills-1.2.0.tar.gz
  sha256: 9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08
  subdir: changelog

Compute the checksum before you commit the manifest:

curl -sL https://example.com/skills-1.2.0.tar.gz | shasum -a 256

What install does on disk

1. Validate the manifest. Hard errors stop here, before any network access.
2. Fetch the source into ~/.loom/cache/build/<name>/.
3. Resolve subdir against the checkout. A missing subdir is an error.
4. Delete <agent skills dir>/<name>/ if it exists, then recreate it.
5. Copy the payload in — the whole subdir, skipping .git, or just the paths in install.files.
6. Confirm install.entry exists in the target. A missing entry file fails the install.
7. Record the install in ~/.loom/state.json and clean up the scratch directory.

Lint rules

loom lint separates errors, which make a manifest uninstallable, from warnings, which are advisory quality nits. Only errors fail the command, and only errors block an install or a publish.

Lint is offline and instant. It cannot tell you whether a subdir exists or an entry file is really there — that is what loom test is for.

Agents

An agent is a name, a label, and a directory. Loom ships with three and treats the first as the default:

Run loom agents to see them with their resolved paths. The same skill may be installed into several agents at once; each install is tracked separately, so you can upgrade or remove one without disturbing the others.

Teach Loom about a new agent by adding it to ~/.loom/config.json. The id becomes a valid --agent value immediately — there is nothing to register or rebuild.

Configuration & state

Everything Loom owns lives under a single prefix, ~/.loom, mirroring the way Homebrew keeps a self-contained one. Override it with the LOOM_HOME environment variable — useful for trying Loom without touching your real setup, and for isolating it in CI.

~/.loom/
  config.json     agents, default agent, repository settings
  state.json      the registry of installed skills
  cache/
    repo/         the synced clone of the manifest repository
    build/        scratch dirs used during install and test
    generate/     scratch clones used by `loom generate`

LOOM_HOME=/tmp/loom-sandbox loom doctor

config.json

Written with defaults the first time any command runs. Edit it freely; Loom re-reads it every invocation.

{
  "agents": {
    "claude-code": { "label": "Claude Code", "skills_dir": "~/.claude/skills" },
    "codex":       { "label": "OpenAI Codex", "skills_dir": "~/.codex/skills" },
    "cursor":      { "label": "Cursor",       "skills_dir": "~/.cursor/skills" }
  },
  "default_agent": "claude-code",
  "repo_path": null,
  "repo_url": "https://github.com/wess/loom"
}

state.json

The registry of what is installed where. list, upgrade, and remove all read it, which is why removal only ever deletes a path Loom itself recorded.

{
  "installed": [
    {
      "name": "pdf",
      "version": "0.1.0",
      "agent": "claude-code",
      "path": "/Users/you/.claude/skills/pdf",
      "source_url": "https://github.com/anthropics/skills"
    }
  ]
}

Deleting a skill folder by hand leaves a stale record behind. loom remove tolerates that — it drops the record even when the path is already gone.

Authoring a skill

Contributing a skill means adding a manifest to the repository. The payload stays in your own repo, where you maintain it.

1. Write the skill. A folder with a SKILL.md at its root, pushed to a git repository and tagged.
2. Author a manifest with loom init (interactive) or loom new (bare template).
3. Point it at the payload — source.url and source.subdir together must name the directory holding your SKILL.md.
4. Lint it to catch missing or malformed fields, offline.
5. Test it — Loom fetches and stages the payload without installing, proving the source resolves.
6. Publish it as a pull request against the repository's skills/ folder.

loom init --url https://github.com/you/skills --ref v1.0.0 --out .
loom lint my-skill.yml       # offline field validation
loom test my-skill.yml       # does it actually fetch?
loom install ./my-skill.yml  # try it in your own agent first
loom publish my-skill.yml    # dry run; add --execute to open the PR

loom init walks you through every field, validating as you type, and can pre-fill its answers by inspecting an existing repository. It reads SKILL.md front matter for the name, description, and keywords, sniffs a LICENSE file for an SPDX id, and derives the author from the repo owner.

What makes a good skill

• The description is the interface. It is what an agent matches against when deciding whether to load the skill, and what a human reads in search results. Say what the skill does and when to reach for it.
• Pin a tag, not a branch. A manifest pointing at main installs something different every week. Tag a release and pin the tag.
• Keep the entry file small. SKILL.md is loaded up front. Push detail into sibling files the skill references, and the agent will read them on demand.
• Bump version when the payload moves. loom upgrade compares version strings. A new tag behind an unchanged version is invisible to it.

Publishing

loom publish automates the fork-branch-commit-PR dance through the GitHub CLI. It defaults to a dry run that prints its plan and changes nothing:

loom publish my-skill.yml

output

==> Publishing my-skill 0.1.0 to wess/loom
  → fork wess/loom to your account (if needed)
  → clone your fork and branch loom/my-skill
  → copy my-skill.yml to skills/my-skill.yml
  → commit "Add my-skill 0.1.0" and push
  → open a PR into wess/loom

warning: dry run — nothing was changed. re-run with --execute to open the PR.

Authenticate gh once, then run it for real:

gh auth login
loom publish my-skill.yml --execute

The manifest is re-validated before anything is pushed, so a manifest with a hard error can never reach a pull request. Point at a different upstream with --repo <url> if you maintain your own collection.

Importing a repo

Already have a repository full of skills? loom generate clones it, finds every folder containing a SKILL.md, reads its front matter, and drafts a manifest for each.

# print the drafts to stdout, touching nothing
loom generate https://github.com/you/skills --ref v1.0.0

# or write one file per discovered skill
loom generate https://github.com/you/skills --ref v1.0.0 --out skills/

Generation infers what it can:

These are drafts. Read each one — a description that reads well inside a SKILL.md is often far too long for a search result — then loom lint and open a PR. create is an alias for the same command.

The website index

This site's search is powered by a generated index at docs/skills.json, produced by reading every manifest in the repository's skills/ folder:

loom index                        # defaults to docs/skills.json
loom index --out docs/skills.json  # or name the destination

The output is a small JSON document the Browse page fetches at runtime:

{
  "generated_by": "loom 0.1.0",
  "count": 287,
  "skills": [
    {
      "name": "pdf",
      "version": "0.1.0",
      "description": "Read, fill, and generate PDF documents.",
      "homepage": "https://github.com/anthropics/skills",
      "license": null,
      "authors": ["anthropics"],
      "keywords": [],
      "compatibility": ["claude-code"],
      "source": "https://github.com/anthropics/skills"
    }
  ]
}

The docs/ folder is a dependency-free static site with no build step, served as a project page under wess.io/loom/. Every internal link is relative for that reason.

Troubleshooting

When something is wrong and the message does not say what, start with loom doctor, then loom info <skill> to see exactly which manifest Loom resolved and where it came from.

FAQ

Does the repository host the skills themselves?

No. It holds manifests only — a few hundred bytes of YAML each. Skills live in their authors' repositories and are fetched at install time. Contributing a skill never means uploading a payload.

Can I install a skill from a private repo?

Yes, if your git can already clone it. Loom shells out to the system git, so it inherits your SSH keys and credential helper. Use an SSH URL in source.url.

Can I install a manifest without publishing it?

Yes. Anywhere a skill name is accepted, a path to a local .yml works too: loom install ./my-skill.yml. This is how you should test a manifest before opening a PR.

Why does loom upgrade say a skill is up to date when upstream changed?

Upgrade compares the manifest's version string against what you installed. A manifest pinned to a moving ref like main keeps the same version while its upstream advances, so upgrade sees no change. Force a refetch with loom install <skill>, which always reinstalls.

Can I run my own repository of manifests?

Yes. Point repo_url at your own git repository, or set repo_path to a local folder of .yml files. loom publish --repo <url> targets a different upstream for a single command.

How do I remove Loom entirely?

Delete the binary (cargo uninstall loom) and its state directory (rm -rf ~/.loom). Installed skills are plain folders in your agents' skills directories — remove them with loom remove beforehand, or delete them by hand afterwards.