# skilltap — Complete Documentation > Source: https://skilltap.dev/llms-full.txt > Generated from the current website documentation. --- # 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, MCP declarations, and shared instruction files across a typed registry of local agent harnesses. 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, and vice versa. When a plugin is published natively for both harnesses, skilltap tracks both native installations instead. Otherwise it materializes through documented target paths and calls out anything that needs approval instead of silently dropping behavior. ## 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 registered harness adapters you want skilltap to manage. 2. Adopt existing native configuration into skilltap's inventory. 3. Review a clear plan. 4. Synchronize safe, faithful changes. 5. Use status to inspect verified health, declared-but-unverified state, drift, updates, and required decisions. Support is component- and scope-specific. Verified capabilities reconcile normally. Declaration-managed file surfaces require explicit foreground acknowledgment and remain effective-unverified. Observe-only targets never gain mutation authority. See the [Harness Support Matrix](../reference/harnesses) and start with [Getting Started](./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 enabled harness environments > are healthy, and distinguish verified from effective-unverified state. > 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 every > selected target that can represent it safely. 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, no harness is considered enabled. `status` may report installed or file-only observe-only targets, 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 list skilltap harness enable codex skilltap harness enable claude # Other registered ids appear in `harness list` with their exact support tier. ``` 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 ` or `--target all` independently selects the harnesses involved. Registration and enablement do not imply mutation support; plans report component- and scope-specific authority for the installed version. 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). --- # 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 skilltap plugin install @ skilltap skill install ``` 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//` 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, declaration-managed, 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, lossy, or declaration-managed foreground operation requires explicit `--yes`. For declaration-managed work, the acknowledgment accepts that skilltap can verify owned file bytes but not harness loading or activation. It never overrides invalid configuration, unsupported components or scopes, unknown versions, authentication, trust, drift, conflicts, or native harness policy. After verified mutation, skilltap observes the targets again. Declaration- managed mutation reports the declaration as owned and healthy while effective state remains unverified. 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 align this project's enabled harnesses, but show me anything > declaration-managed, 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. --- # 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 ``` --- # 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 fully safe by policy. It never acknowledges partial compatibility or declaration-managed effective- unverified work, overwrites drift, edits conflicted instructions, authenticates, approves trust, or installs newly observed resources. Items that need judgment remain pending for a foreground plan. --- # 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 --help $ skilltap --help ``` The public command families are: | Family | Purpose | Start with | | --- | --- | --- | | Harness | Enable, disable, and inspect registered target policy and support tiers | `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 ` | Select harnesses independently of scope; use `harness list` for current ids. | | no scope flag | Operate globally. | | `--project` | Use the project containing the current directory. | | `--project ` | 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, lossy, or effective-unverified declaration consequence; blocked work remains blocked. | | `--include ` | Include matching resources or components; repeatable. | | `--exclude ` | 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; file-only observe-only targets require no guessed binary. A mutating command creates owned configuration only when that command requires it. ## Target support tiers `harness list`, `status`, and `plan` derive target behavior from the typed registry and exact observed profile: - **Verified** capabilities may execute normally. - **Declaration-managed** components require foreground `--yes`; skilltap verifies its owned bytes while effective state remains unverified. - **Observe-only** targets expose safe documented reads and no mutation ports. - **Unsupported** components or scopes remain blocked without affecting safe siblings. Native commands always require verified `Supported` authority. Unknown versions never mutate, and the daemon never supplies declaration acknowledgment. ## 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. --- # Harness Support skilltap registers targets independently from the authority to mutate them. Support is evaluated for the installed version, component, and concrete global or project scope. Use `skilltap harness list`, `skilltap status`, and `skilltap plan` for the machine-specific result. ## Support tiers - **Verified** — skilltap can safely perform the operation and verify the native or managed result. - **Declaration-managed** — an exact-version documented file surface can be owned, preserved, rolled back, removed, and repeated safely, but no safe native observer proves that the harness loaded it. Foreground `--yes` is required and status remains effective-unverified. - **Observe-only** — skilltap can inspect safe documented surfaces but exposes no mutation authority. - **Unsupported** — the component or scope has no safe contract. It remains blocked without preventing unrelated supported work. Unknown versions never mutate. Native commands always require verified support. The daemon never acknowledges declaration-managed operations. ## Current target matrix | Target id | Harness | Current contract | | --- | --- | --- | | `codex` | Codex | Verified native and managed behavior for exact compiled profiles. | | `claude` | Claude Code | Verified native marketplace/plugin behavior and managed compatibility. | | `droid` | Factory Droid | Verified native/managed coexistence; project marketplace operations remain unsupported where the native lifecycle lacks them. | | `qwen` | Qwen Code | Verified native extension conversion and managed skill/MCP projection. | | `agy` | Antigravity CLI | Complete global/project skills plus declaration-managed global MCP for exact version 1.1.13; project MCP and native plugin lifecycle are unsupported. | | `opencode` | OpenCode | Verified file-managed skills and MCP for the attested profile. | | `copilot` | GitHub Copilot CLI | Mixed: managed MCP has structured observation; complete skills are declaration-managed; incomplete native plugin lifecycle is unsupported. | | `kiro` | Kiro CLI | Complete skills and MCP declarations for the attested profile; plugin/MCP projection is declaration-managed and never invokes login. | | `kimi` | Kimi Code CLI | Global MCP declaration-managed; project MCP and unsupported auth/transports remain blocked. | | `vibe` | Mistral Vibe | Global/trusted-project static MCP declaration-managed through syntax-preserving TOML edits; OAuth and interactive effective observation are unsupported. | | `kilo` | Kilo Code | Valid global/project JSON/JSONC declarations are declaration-managed; side-effectful debug/list/auth probes are never invoked. | | `junie` | Junie | Complete skills and MCP are declaration-managed; ambiguous cross-scope MCP names block and interactive `/mcp` is never invoked. | | `amp` | Amp | Complete skills and MCP are declaration-managed; doctor, OAuth, login, browser, and trust approval are never invoked. | | `pi` | Pi | Observe-only compound profile for the attested Pi, MCP companion, and hook companion tuple. | | `cursor` | Cursor | Observe-only using documented `agent` detection and safe skill/MCP read surfaces; no mutation profile. | | `zoo` | Zoo Code | File-only observe-only target; editor storage, installed identity, and effective reload remain unresolved. | | `zcode` | ZCode | File-only observe-only target for documented global skill and MCP files; project skills and effective reload remain unresolved. | Codex and Claude Code remain the only first-party bootstrap plugin targets. Other registered harnesses participate through ordinary enablement, status, planning, synchronization, and update behavior according to the matrix above. ## Declaration-managed safety An acknowledged declaration-managed operation does **not** mean the harness loaded or activated the resource. skilltap still guarantees: - exact-version authority; - explicit files and consequences in the plan; - no overwrite of unmanaged or ambiguous same-name entries; - preservation of unrelated documented fields and credential references; - root-confined no-follow writes; - lock-time executable and file revalidation; - rollback and target-local ownership; - immediate-repeat no change; - no daemon execution, browser, authentication, trust approval, TUI, editor automation, or side-effectful status probe. --- # 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, no harness is enabled. Read-only inspection does not create it and does not infer enabled harnesses from binaries or documented file-only surfaces found on the machine. ```toml schema = 1 [harnesses.codex] enabled = true binary = "codex" [harnesses.claude] enabled = true binary = "claude" # File-only observe-only targets have no binary field. [harnesses.zoo] enabled = false [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`. Declaration-managed results persist owned declaration provenance and fingerprints, not a claim that the harness loaded them. A successful mutation may update revisions, versions, timestamps, and apply results after the applicable disk or native 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.