git:20260713.91b8789 to git:20260713.3175600

# skilltap — Complete Documentation

> Source: https://skilltap.dev/llms-full.txt

> Generated from the current website documentation.

---

<!-- Source: https://skilltap.dev/guide/what-is-skilltap -->

# What is skilltap?

skilltap gives agents an easy way to help you look after the tooling on your

computer. It adopts, reconciles, and updates native marketplaces, plugins,

complete skill directories, and shared instruction files across Codex and

Claude Code.

The harnesses remain authoritative for their own formats. skilltap uses native

lifecycle commands when they exist, records desired state separately from

observed state, and reports when a resource cannot move faithfully between

harnesses.

That cross-harness handoff is a core part of skilltap: a marketplace or plugin

built for Claude can still provide compatible skills and components in Codex,

## What it manages

- Marketplace registrations and native plugins.

- Standalone skills, where the complete directory containing top-level

`SKILL.md` is the resource.

- Global and project instruction files, with `AGENTS.md` canonical.

- Source revisions and updates for resources managed by skilltap.

- Optional user-level background update checks.

## What it does not do

skilltap does not search marketplace catalogs, recommend extensions, provide a

public registry, run a terminal dashboard, or support older skilltap state.

Callers provide explicit marketplace, plugin, skill, and project identities.

## The operating loop

1. Enable the Codex and Claude adapters you use.

2. Adopt existing native configuration into skilltap's inventory.

3. Review a clear plan.

4. Synchronize safe, faithful changes.

5. Use status to inspect health, drift, updates, and required decisions.

Start with [Getting Started](./getting-started).

---

<!-- Source: https://skilltap.dev/guide/getting-started -->

# Getting Started

## Install

The plugin is skilltap's primary distribution surface. Add the marketplace,

then install or enable the plugin in the harness you already use:

```bash

# Claude Code

claude plugin marketplace add nklisch/skilltap --scope user

claude plugin install skilltap@skilltap --scope user

# Codex (marketplace registration)

codex plugin marketplace add nklisch/skilltap

codex plugin add skilltap@skilltap

```

Both harnesses install the plugin natively after registration. Older Codex

builds without `plugin add` can install or enable it through `/plugins`.

### Install the standalone binary

After marketplace setup, use the online installer when you want the binary

directly or need to set up a harness without its plugin flow:

```bash

# macOS or Linux

curl -fsSL https://skilltap.dev/install.sh | sh

# Or Homebrew

brew install nklisch/skilltap/skilltap

```

The installer verifies the release checksum, installs the user-level binary,

and invokes `skilltap bootstrap` to detect Claude Code and Codex independently.

Harness absence or an unsupported native lifecycle is reported as attention;

the verified binary remains available. The executable is the authoritative

command discovery surface:

```console

skilltap bootstrap --help

```

Verify the binary:

```bash

skilltap --version

```

## Use skilltap through your agent

The easiest human workflow is to describe the result you want. Your Codex or

Claude agent can inspect the CLI, plan the work, and use skilltap on your

behalf. Try prompts such as:

> Use skilltap to check whether this computer's Codex and Claude environments

> are healthy.

> Use skilltap to adopt my existing Claude configuration and show what would

> change before syncing it to Codex.

> Use skilltap to sync my global plugins, skills, and shared instructions.

> Explain any drift or incompatibility and ask before accepting a partial

> result.

> Use skilltap to install `formatter@example-plugins` for this project in both

> harnesses.

Agents should use `skilltap --help` and leaf-command help for exact syntax,

start with `status` or `plan` when appropriate, and bring judgment calls back

to you. You can still run every command directly; there is no separate agent

mode.

## Inspect before configuring

`status` works before skilltap configuration exists and does not mutate the

machine:

```bash

skilltap status

```

When `config.toml` is absent, neither Codex nor Claude is considered enabled.

`status` may report what is installed, but it does not infer management policy,

create the skilltap configuration directory, or write any harness file.

## Enable native harnesses

Enable only the harnesses you want skilltap to manage:

```bash

skilltap harness enable codex

skilltap harness enable claude

skilltap harness list

```

Enabling an adapter records policy. It does not adopt or modify native

configuration.

## Adopt and synchronize

Adopt global resources from enabled harnesses, inspect the proposed changes,

then apply them:

```bash

skilltap adopt

skilltap plan

skilltap sync

```

Adoption changes skilltap inventory only. Synchronization performs the planned

native operations and verifies the result by observing the harnesses again.

For a project, add `--project`; to name another location, pass a path:

```bash

skilltap status --project

skilltap adopt --project ~/src/example

skilltap plan --project ~/src/example

```

Bare scoped commands operate globally. `--target codex`, `--target claude`, or

`--target all` independently selects the harnesses involved.

Each resource has a stable logical ID and one concrete global or project scope.

Together they form its exact resource key. Equal logical IDs in global scope

and different projects are separate managed instances.

Next, see [Managing Environments](./managing-environments) and

[Shared Instructions](./instructions).

---

<!-- Source: https://skilltap.dev/guide/managing-environments -->

# Managing Environments

skilltap separates desired inventory from fresh native observations. That makes

the direction explicit: `adopt` brings native configuration into inventory;

`sync` applies inventory to managed harnesses.

Codex-native global paths resolve under

`${CODEX_HOME:-$HOME/.codex}`. This override does not move skilltap state and

never moves the canonical global instruction file at `~/AGENTS.md`.

## Adopt native state

```bash

skilltap adopt --from codex

skilltap adopt --from claude --project

```

Adoption preserves source and scope, coalesces resources only when identity and

semantics match, and leaves conflicts for a caller to resolve. It never invokes

native mutation.

Claude project-shared declarations are still observed because they can affect

the effective project environment. They are reported as visible,

non-adoptable evidence: skilltap does not import them into its personal project

scope, and there is no shared-scope adoption selector.

## Register explicit resources

```bash

skilltap marketplace add <source>

skilltap plugin install <plugin>@<marketplace>

skilltap skill install <source>

```

Marketplace sources and resource identities come from the caller. skilltap

does not browse or search their contents.

A desired resource is identified by its logical ID plus its exact concrete

scope. This scope-bearing resource key is used consistently by inventory,

observations, dependencies, plans, and apply state. The same logical ID can

therefore coexist globally and in multiple projects.

A standalone skill is its whole directory, not only `SKILL.md`. Compatible

skills use the standard `.agents/skills/<name>/` representation; adapters add

harness-specific links or managed copies only where the harness requires them.

## Plan before mutation

```bash

skilltap plan

skilltap plan --project --target claude

skilltap plan --all-scopes --json

```

Plans classify operations as native, faithful equivalent, managed

materialization, partial, unsupported, conflicting, or no-op. Every native

project file that may change appears in the plan.

Logical resource and component selectors are resolved only across the scopes

selected by the command. Each resulting operation carries the exact scoped

resource key, and the selector's scope must match the operation's scope.

Mutation authority comes only from a verified capability profile compiled into

skilltap for the exact observed harness executable and version. Runtime probes

may preserve or narrow that authority; they never widen it. Unknown harness

versions remain observable but receive no mutation authority.

## Apply and verify

```bash

skilltap sync

```

Safe independent operations may proceed even when another resource needs a

decision. A partial or lossy foreground operation requires explicit `--yes`.

That acknowledgment never overrides invalid configuration, missing required

components, drift, or native harness policy.

After mutation, skilltap observes the targets again. Repeating the same sync

against unchanged inputs produces no changes.

## Delegate the workflow, not the decision

Humans can ask an agent for a high-level outcome instead of assembling a

command sequence. For example:

> Use skilltap to make this project's Codex and Claude plugin setup match, but

> show me anything partial or incompatible before you proceed.

The agent should inspect status, produce a plan, apply only authorized work,

and explain any next action skilltap reports. A request to use skilltap does

not authorize the agent to conceal drift, bypass a required acknowledgment, or

choose which unsupported behavior is acceptable.

---

<!-- Source: https://skilltap.dev/guide/instructions -->

# Shared Instructions

`~/AGENTS.md` is the canonical global instruction file. skilltap bridges native

harness locations to it so Codex and Claude Code share one maintained source.

```bash

skilltap instructions status

skilltap instructions setup

skilltap instructions repair

```

By default, Claude's `CLAUDE.md` is a symlink to the canonical `AGENTS.md`.

Configuration may instead select a managed import file. Existing independent

instruction files are conflicts until their contents are reconciled; skilltap

does not silently choose one.

For a project, `AGENTS.md` at the resolved project root is canonical. A

`CLAUDE.md` bridge is created only when Claude needs it. If both files contain

independent content, status reports the conflict and repair requires explicit

approval before replacing the Claude file.

Scope follows the common contract:

```bash

skilltap instructions status # global

skilltap instructions status --project # current project

skilltap instructions setup --project ~/src/example

```

---

<!-- Source: https://skilltap.dev/guide/updates -->

# Updates and Daemon

The self-hosted plugin and one-line installer use the same binary bootstrap

boundary. `skilltap bootstrap` resolves the latest supported release, verifies

its checksum, and performs an atomic user-level install. Existing binaries are

updated within their current major by default; pass `--allow-major` for an

explicit major-version upgrade. A failed verification preserves the prior

binary. Run `skilltap bootstrap --help` for the executable contract.

skilltap tracks native versions, requested Git refs, resolved commit SHAs, and

content fingerprints for managed resources. Marketplace, plugin, and skill

update commands use that provenance rather than rediscovering resources.

```bash

skilltap marketplace update

skilltap plugin update

skilltap skill update

skilltap status

```

Git-backed managed resources have an update when their resolved commit SHA

changes. Pins remain fixed until inventory changes. Local drift blocks

overwrite and appears in status.

## Optional background operation

```bash

skilltap daemon enable

skilltap daemon status

skilltap daemon run

skilltap daemon disable

```

The daemon uses the same application services as foreground commands. It may

check for updates or apply operations classified as safe by policy. It never

acknowledges partial compatibility, overwrites drift, edits conflicted

instructions, or installs newly observed resources. Items that need judgment

remain pending for a foreground plan.

---

<!-- Source: https://skilltap.dev/reference/cli -->

# CLI Reference

skilltap is a clear, non-interactive CLI that works well from a terminal or an

agent. Running it without a subcommand prints concise help and exits with an

input error.

## Executable help is authoritative

This page is a conceptual index, not a second command grammar. The compiled

binary owns names, arguments, validators, meaningful flags, and exit guidance.

Ask the executable whenever an agent needs exact syntax:

```console

$ skilltap --help

$ skilltap <command-family> --help

$ skilltap <command-family> <operation> --help

```

The public command families are:

| Family | Purpose | Start with |

| --- | --- | --- |

| Harness | Enable, disable, and inspect Codex/Claude policy | `skilltap harness --help` |

| Adopt | Import native resources into desired state | `skilltap adopt --help` |

| Status | Inspect desired, observed, and managed health | `skilltap status --help` |

| Plan | Preview operations without mutating native state | `skilltap plan --help` |

| Sync | Apply the selected desired-state operations | `skilltap sync --help` |

| Marketplaces | Register, update, remove, and list native marketplace registrations | `skilltap marketplace --help` |

| Plugins | Install, update, remove, and list plugins | `skilltap plugin --help` |

| Skills | Install, update, remove, and list complete skill directories | `skilltap skill --help` |

| Instructions | Set up and repair canonical `AGENTS.md` bridges | `skilltap instructions --help` |

| Daemon | Opt into, inspect, run, or disable background updates | `skilltap daemon --help` |

The standalone `adopt`, `status`, `plan`, and `sync` commands are the state

control-plane operations. Their exact scope, target, selection, and

acknowledgment flags are shown by their leaf help pages.

There is no `init` command. The first mutating command creates skilltap's

configuration directory when necessary.

## Common selectors

| Flag | Meaning |

| --- | --- |

| `--target <codex\|claude\|all>` | Select harnesses independently of scope. |

| no scope flag | Operate globally. |

| `--project` | Use the project containing the current directory. |

| `--project <path>` | Use the project containing the supplied path. |

| `--all-scopes` | Use global scope and every managed project. |

| `--json` | Render the same result as a stable JSON envelope. |

| `--yes` | Acknowledge every eligible partial or lossy consequence in this operation; blocked work remains blocked. |

| `--include <selector>` | Include matching resources or components; repeatable. |

| `--exclude <selector>` | Exclude matches; repeatable and wins over inclusion. |

Only commands for which a flag is meaningful accept it. `--project` and

`--all-scopes` are mutually exclusive; the executable rejects misplaced flags.

Every leaf help page also states the process exit classes: `0` completed, `1`

invalid or pre-mutation failure, `2` attention or user decision required, and

`3` partial mutation requiring recovery.

Resource and component selectors begin as logical input. skilltap resolves

them only within the command's selected scopes. Every planned operation then

uses the exact resource key—the logical ID plus concrete global or project

scope—and rejects any selector whose scope disagrees with the operation.

When `config.toml` is missing, no harness is enabled. Read-only `status` remains

available and creates nothing; a mutating command creates owned configuration

only when that command requires it.

## Results and exit codes

Plain output uses the same stable result labels across commands rather than

exposing raw implementation details. Human-readable output ends with one of:

```text

Result: completed

Result: attention required

Result: invalid

Result: partial apply; recovery required

```

The process exit code is authoritative for automation; `--json` carries the

same result class and typed next actions for agents.

`--json` emits exactly one schema-1 JSON document. `schema`, `command`,

`result`, `summary`, `resources`, `operations`, `warnings`, `errors`, and

`next_actions` are always present. `scope` is present for scoped command

results. Harness selections and exit codes are not separate top-level fields;

target details belong in the applicable summary, resource, or operation data,

and the process reports its exit code to the caller.

```json

{

"schema": 1,

"command": "status",

"result": "attention_required",

"scope": {

"kind": "all"

},

"summary": {},

"resources": [],

"operations": [],

"warnings": [],

"errors": [],

"next_actions": []

}

```

| Code | Meaning |

| --- | --- |

| `0` | Operation completed and desired state is satisfied. |

| `1` | Invalid input, invalid configuration, or operational failure before mutation. |

| `2` | Drift, planned changes, or a user decision requires attention. |

| `3` | Mutation partially completed and recovery is required. |

For `plan`, a non-empty plan exits `2`. For `status`, unhealthy state or

required changes exits `2`. For `sync`, blocked operations exit `2` when no

mutation failed; a failed or partial mutation exits `3`. Consult the leaf help

and structured `next_actions` for the recovery command an agent should run.

---

<!-- Source: https://skilltap.dev/reference/state -->

# State and Configuration

All skilltap-owned machine configuration lives under:

```text

${XDG_CONFIG_HOME:-$HOME/.config}/skilltap/

├── config.toml

├── inventory.toml

├── state.json

└── managed/

```

No skilltap metadata is written into managed projects.

## `config.toml`

Policy includes enabled harnesses, binary overrides, instruction bridge mode,

and update behavior. It does not list installed resources.

If this file is missing, neither harness is enabled. Read-only inspection does

not create it and does not infer enabled harnesses from binaries found on the

machine.

```toml

schema = 1

[harnesses.codex]

enabled = true

binary = "codex"

[harnesses.claude]

enabled = true

binary = "claude"

[instructions]

claude_mode = "symlink"

[updates]

mode = "apply-safe"

interval = "6h"

```

## `inventory.toml`

Inventory is the human-readable desired state for registered marketplaces,

plugins, standalone skills, instruction locations, target harnesses, project

paths, component selections, update policy, and pins. Entries use stable

skilltap identifiers and canonical absolute paths. A logical resource ID and

its concrete scope form the exact resource key; equal IDs in global and

different project scopes remain distinct.

## `state.json`

State is machine-written provenance and apply history: native identifiers,

fingerprints, versions, Git revisions, last checks, native harness versions,

timestamps, and apply results. It is inspectable output, not desired

configuration.

Fresh declared/effective observations, capability-profile evidence, and health

findings are ephemeral. `status` and `adopt` do not persist their snapshots to

`state.json`. A successful mutation may update provenance, fingerprints,

revisions, versions, timestamps, and apply results after re-observation.

## `managed/`

Managed artifacts and recoverable backups live here when no faithful native

lifecycle exists. Authentication material and secrets never enter any skilltap

state file or managed artifact.