Skip to main content

What `arc skill` Is Today (and What It Is Not)

Robert
AFSARCCLIAgentArchitectureEverything is Context

If you install ARC and type arc skill, you get a short list of names: daemon, afs, blocklet, mcp. You can print one of those texts, or copy it into .claude/skills/ / .agents/skills/. That is what the command does today.

It is easy to read “skill” and expect something bigger—especially after GitHub CLI’s gh skill (search / install / update agent skills from GitHub) or after you notice that AFS itself has /.skills under mounts. This piece separates three different things people call “skill”, shows the exact steps for the CLI surface that exists, and states the design gap we still need to close.

Full flag tables live in the arc skill reference.

Three “skills”, one overloaded word

LayerWhereWho uses itManaged by arc skill today?
Bundled booklets (L0)Inside the arc binaryHumans or agents that need “how do I start?”Yes — list / show / install
Host agent skills.claude/skills/, .agents/skills/ on diskClaude Code, Codex, etc.Only as install target of L0 booklets — not list/update/remove of arbitrary skills
AFS provider skills/{mount}/.skills/** on a live daemonAgents exploring a mounted providerNo — use arc afs ls/read/exec (and explain)

If the article only said “arc skill teaches agents ARC,” that was too narrow and slightly wrong: install already points at host skill directories, and AFS already has a skill tree that this command does not inventory.

What you can do right now (paste-friendly)

0. Version check

bash
arc --version          # need a build that has `skill` (≈ 2.0.0-beta.30+)
arc skill --help

No skill in arc --help → upgrade the binary first.

1. See the bundled catalog

bash
arc skill list
arc skill list --json

You get names + one-line descriptions + “prefer show <name> over show all.”

2. Read one booklet

bash
arc skill show daemon
arc skill show afs

Typical flow those booklets describe:

  1. arc service status → start only if needed
  2. arc afs ls / · explain / · read /.knowledge
  3. For UI/WM: session under /dev/ui, then panels — samples in the afs booklet

Prefer one name. arc skill show all dumps everything; it is for offline/debug, not the default.

3. Drop a booklet into host agent folders

From a project directory:

bash
cd /path/to/your-project
arc skill install afs
ls .agents/skills/afs/SKILL.md .claude/skills/afs/SKILL.md

Source of truth is still the CLI build. After upgrading arc, re-run install if you want the files updated.

4. Provider skills on a live world (not via arc skill)

bash
export ARC_INSTANCES_DIR=/tmp/arc-skill-instances
arc service start --instance skill-demo --home /tmp/arc-skill-demo --port 19890
arc afs ls /
# when a mount ships skills:
arc afs ls /some-mount/.skills
arc afs read /some-mount/.skills/SKILL.md

That path is AFS, not arc skill. Confusing them is how readers get lost.

What gh skill does that we do not (yet)

gh skill is a package manager for agent skills: search, preview, install from GitHub, list what is installed, update, publish.

arc skill today is closer to:

  • a built-in help pack for ARC itself, plus
  • a one-way copy into host skill directories.

It does not yet:

  • list skills already installed under .claude/skills / .agents/skills (except what you just installed from ARC)
  • search / install third-party skills from a registry
  • inventory /.skills across mounts
  • uninstall or update host skills generically

That gap is intentional under-delivery from the first ship (avoid over-engineering), but after using the docs it is obvious the name skill invites the fuller product. The original idea issue is ArcBlock/arc#1398; the narrow L0 catalog landed under epics #3549 / #3595.

Design direction (proposal, not shipped)

Treat arc skill as the CLI for agent skills around ARC, with explicit sources:

text
arc skill list [--source bundled|host|afs|all]
arc skill show <id> [--source …]
arc skill install <id>   # bundled → host (today); later: remote registry
arc skill search …       # later
# inventory-only first for afs/host; mutate carefully

Constraints that should stay true:

  1. L0 booklets stay short and offline — no daemon required for bundled.
  2. Live AFS remains truth for mounts and actions — booklets must not invent paths.
  3. Do not become a second package ecosystem for everything on earth — prefer composing with host tools (gh skill where GitHub is the source) and AFS where ARC owns the mount.

Until that lands, documentation and this article should say “bundled catalog + host install”, not “the skill system.”

When this surface is (and is not) enough

Enough when: you need a clean agent or a teammate to bootstrap daemon → AFS → blocklet without reading the monorepo.

Not enough when: you expect arc skill list to show everything installed for Claude Code, or every provider skill on the daemon. Use host-directory listing / AFS ls …/.skills for those, or wait for the multi-source CLI.

Keep going

Referenced here

Products

  • ARC active

    The runtime for Blocklets. It gives a developer a place to run an application described as a Blocklet, together with the resources that Blocklet declares it needs.

Terms

  • AFS

    AFS (Agentic File System) turns the files, services, and active work relevant to a task into an inspectable resource view. Instead of handing an agent an undifferentiated machine or a pile of APIs, it gives the task a world with names and boundaries.