Detailed command behavior, adapter differences, and lock compatibility. For an introduction and installation, see README.
skillctrl works on a Git repository. add and merge create .agents/skills
if it is missing. Save customization requirements in an intent file when needed:
.agents/skills/<name>/ imported and adapted skills
.agents/skillctrl/intents/<name>.md what your customization must keep doing
The native project lock stays at the repository root: skills-lock.json keeps
ordinary registrations in the format used by npx skills. Aliases, merged
inputs, and supplemental source provenance live in
.agents/skillctrl/lock.json; they do not add custom entries or fields to
the native lock. Native commands restore and update ordinary registrations;
use skillctrl for aliases and merges, which native skills does not implement.
The same lock records the accepted hash of each
whole skill directory with both an upstream registration and saved intent.
Intent-free imports and handwritten skills remain excluded. Acquisition never
advances accepted hashes; check reports local drift and pending cleanup offline.
Existing native locks retain their version, other providers, unknown fields,
and exact bytes when their registrations are unchanged. Supplemental metadata
is bound to its native entry: an independent native edit or removal wins over
old metadata. Legacy version 3 and older skillctrl extensions remain readable;
a successful import moves recognized alias/merge registrations into the private
tracking file. Read-only commands and dry runs never migrate anything. Only
when no root lock exists does a successful import move the legacy native lock
from .agents/.skill-lock.json to the root.
The private lock uses version 1, with upstreams for skillctrl-only registrations
and acceptedHashes for explicit acceptance. add, merge, and update change
provenance without advancing accepted hashes; record changes accepted hashes
without fetching or changing provenance. remove removes the registration and
its accepted hash.
When the private lock is absent, skillctrl reads the old upstreams.json and
intents/lock.json files under .agents/skillctrl/. The next successful private
lock write combines them and removes both old files without accepting new content.
check and dry runs never migrate files. Once present, the unified lock takes
precedence over old files, including registrations deliberately removed from it.
Older skillctrl releases do not read the unified lock; keep the new CLI after migration.
Run provenance-changing operations one at a time per repository. Concurrent
add, merge, update, remove, or native registration edits are unsupported;
an import can replace provenance prepared before those edits.
# search the public index; installs nothing
skillctrl find review --owner owner
# list installed project skills
skillctrl list
# check local accepted hashes offline without changing files
skillctrl check
# import a skill
skillctrl add owner/repo:chosen-skill
# refresh the original without AI or acceptance
skillctrl update chosen-skill
# Save requirements, then edit and verify the skill directly
mkdir -p .agents/skillctrl/intents
cp requirements.md .agents/skillctrl/intents/chosen-skill.md
# what still differs from the accepted hashes
skillctrl check
# compute and save the hash after verifying a deliberate edit
skillctrl record chosen-skill
# remove the skill, its saved intent, and registrations
skillctrl remove chosen-skillowner/repo and chosen-skill are placeholders; replace them with an inspected
source and skill. An intent describes behavior, for example: "Keep instructions
concise and require tests before completing code changes."
add, update, and merged inputs use a replaceable acquisition adapter. The
default skills adapter reuses a stable skills 1.x CLI at least 1.7.0 on PATH.
If missing, incompatible, or unable to report its version, it invokes
npx --yes --ignore-scripts skills@1.7.0 instead. A separate skills installation
is optional; the npx path needs Node.js/npm (skills requires Node.js >=22.20.0).
--adapter gh invokes gh skill install. --adapter git
retains the direct Git importer for existing integrations. Set
SKILLCTRL_ADAPTER to choose a default; an explicit flag takes precedence.
--adapter accepts only skills, gh, or git. Invalid flag values and invalid
effective SKILLCTRL_ADAPTER values are rejected before command execution, even
for local-only commands and dry runs. If neither a compatible skills CLI nor npx
is available, acquisition fails with setup guidance. The npx path reports its
use on stderr and may fetch its fixed package on first use. npm's cache is kept
outside disposable staging, honoring an explicit npm cache setting or using the
caller's ~/.npm. It does not add project dependencies or install a global CLI.
Installer failures are returned without retrying via npx or another adapter.
Manage runtime tools through the target repository's existing tool manager and
preserve its version pins and release cooldowns;
skillctrl never requests an unpinned npm package. Local commands and dry runs
never resolve or invoke skills/npx.
skillctrl --adapter skills add owner/repo:chosen-skill
skillctrl --adapter gh add owner/repo:chosen-skill
skillctrl list
skillctrl check chosen-skill| Command | Responsibility |
|---|---|
find / search |
Search skills.sh for skills or git; use gh skill search for gh. The skills 1.7.0 find command has no JSON API, so its public index is queried directly. |
add / install, update |
Delegate acquisition to the adapter, then validate, import, and register originals without AI or accepted hashes. Each update fetches an original into empty staging; an unchanged original leaves the skill untouched, and a changed one is three-way merged into the local skill. |
list / ls |
Read project skill directories, including handwritten skills. |
check |
Report local accepted-hash drift offline without importing or reviewing; optional names scope the report. No acquisition adapter executable is needed. |
remove / rm |
Remove project content, its saved intent, and registrations locally; no network or adapter executable is needed. |
merge |
skillctrl-specific routing skill containing ordered upstream originals; no intent or AI required. |
record |
Compute current skill-directory hashes and create or replace the named lock entries after verifying content yourself; unresolved conflict markers are refused. |
Acquisition runs in a disposable directory and home, so installer-owned global
locks do not replace or relocate the project's root skills-lock.json. Only
selected source registrations are imported, preserving unrelated lock metadata.
GitHub CLI's native tracking metadata remains in the downloaded SKILL.md.
GitHub CLI acquisition resolves existing token or Keychain-backed authentication
before changing home, then passes it only to the acquisition process while
removing the inference credential. Native acquisition
tools are trusted executables; downloaded skill scripts are not executed.
Discovery, release/ref selection, and downloaded file modes follow the chosen
backend; switching backends can produce a different original to inspect and customize directly.
Do not interpret the adapters as identical upstream resolvers. The direct Git
backend records source commits; command adapters record paths and content hashes
without inventing a commit identifier. Intent review, import protection, accepted
hashes are shared by all adapters.
Adapter selection is per invocation. Backend discovery, source resolution and file modes may differ; choose an adapter explicitly when that distinction matters. The source repository stores its own merged registration in private tracking, so it does not mark its distributable package as a native installed dependency. Japanese skill guides display metadata as documentation, without installable frontmatter, preventing accidental selection of the translation.
CI is optional. Local commands need neither an AI reviewer nor its toolchain. Use your editor or existing agent to customize content before recording it.
record NAME computes the current whole skill-directory hash and creates or
replaces NAME in acceptedHashes in .agents/skillctrl/lock.json. NAME selects
a skill; you do not supply a hash. Unchanged content produces the same hash. It
does not update native registrations or original-source tracking. It updates
only the accepted hashes, preserving acquisition metadata. It runs no reviewer, changes no skill content, and leaves the
Git index alone. It refuses a skill directory that still contains unresolved
conflict markers, so a conflict-marker block can never become accepted content.
Use it after deliberately editing and checking a managed skill;
it records your acceptance rather than verifying that the saved intent is met.
record --dry-run previews the operation without computing or comparing hashes;
use check [NAME...] to inspect local drift.
Only named upstream-registered skills with saved intent advance; other eligible hashes remain unchanged. Ineligible entries are pruned. With no names, record only prunes ineligible entries and accepts no content, including after every intent file has been deleted.
check reports local drift in local without contacting upstreams. It compares
skill-directory hashes with the accepted lock and does not run a model to assess
whether the current instructions satisfy the intent. Differences are reported
in JSON, not treated as command failures. With no names, it checks all skills
with both upstream registration and saved intent; explicit names select a subset.
Upstream changes are acquired only by an explicit update; a new upstream
version alone does not change local acceptance. Local and automated updates use
the same commands. A CI job can fail on .local.lock_changed in the check JSON;
a scheduler calls update before review, editing, and explicit recording.
See agent workflow guide for the common flow.
To update originals deliberately, first inspect local customization, then run:
skillctrl update chosen-skill > update.json
jq '.updates' update.json
git diff -- .agents/skills/chosen-skill
# Resolve conflicts and check the upstream change against the saved intent
skillctrl record chosen-skill
git diff -- .agents/skills/chosen-skill .agents/skillctrl/lock.jsonA single-input update merges the changed original into the current skill, file
by file. The base is recovered by its registered skillFolderHash from Git
objects or upstream history. Files unchanged upstream and local-only files keep
their local bytes and modes. Overlapping text edits produce diff3 markers.
git diff -- .agents/skills/chosen-skill shows the applied upstream change and
any conflicts; updates[].changes lists the upstream file changes.
update reports each changed skill in updates:
{"repo": "/path/to/repo", "skills": ["chosen-skill"], "updates": [{
"name": "chosen-skill", "path": ".agents/skills/chosen-skill", "layout": "single",
"status": "conflicted", "base": "upstream-history",
"changes": [{"path": "SKILL.md", "upstream": "modified", "result": "conflict"},
{"path": "references/new.md", "upstream": "added", "result": "applied"}],
"conflicts": [{"path": "SKILL.md", "kind": "content", "lines": [[12, 20]]}]
}]}status |
Meaning |
|---|---|
merged |
Every upstream change applied; local edits are preserved. |
conflicted |
Clean changes applied; listed files need resolution. Text conflicts carry diff3 markers labelled local, previous original, and new original at the reported 1-based, inclusive line ranges. Binary and modify/delete conflicts keep the local side; inspect the new original at the registered upstream source and skill path. |
replaced |
No verified previous original was available; the new original replaced the skill as in earlier releases. reason says why. |
refreshed |
A merged skill's registered references were replaced; inputs lists which changed. Its routing body is preserved. |
base names the first verified source: the repository's Git objects
(repository), upstream branch and tag history fetched with blob:none
(upstream-history, for every adapter), or the recorded source commit fetched
again by the direct Git adapter (upstream). Each recovered tree must match the
registered tree hash. Source commits are optional for history recovery. History
fetches have no shallow boundary; blobs are downloaded only when reading the
required tree, if the server supports filtering. History is shared per source
within an update and discarded afterward. Updates require upstream access;
check stays offline. If recovery fails, for example after rewritten history
removes the tree, replaced reports the reasons and replaces the whole skill,
including local-only files. History fetch/read/verification failures abort the
update unless recorded-commit recovery succeeds. A conflicting update exits 0.
Legacy .agents/skillctrl/originals/ directories are ignored and left untouched.
After upgrading all callers, inspect and remove that directory manually (for
tracked copies, git rm -r -- .agents/skillctrl/originals) and commit the removal.
No command creates or refreshes it. Merged skills retain registered references/.
Edit the skill directly to resolve conflicts and keep its saved intent, verify
the result, then run record chosen-skill to accept it. record refuses a
skill directory that still contains unresolved conflict markers, so resolve
them first. Intent-free skills remain outside the accepted lock. Inspect the
resulting changes before committing them.
Results are JSON on stdout; logs and errors go to stderr. Exit 0 means success
and exit 1 means failure. Commands operate in the current repository and never
start AI, commit, push, or open a pull request. External automation uses the same
commands and manages its own agent, timer, and draft PR.
add and merge use the same positional owner/repo:skill inputs.
add imports separate skills; merge imports ordered originals into one
routing skill, with each input registered in its sources array. Neither
requires intent or a reviewer:
# Import separate skills
skillctrl add owner/first:first-skill owner/second:second-skill
# Combine the same inputs under one routing skill
skillctrl merge --name combined \
owner/first:first-skill \
owner/second:second-skill
skillctrl update combinedThe repositories above are placeholders. The generated root SKILL.md routes
tasks to references/first-skill/SKILL.md, references/second-skill/SKILL.md, and so
on. Each original retains its bundled resources and relative resource paths.
Snapshots are excluded from skillctrl's independent skill discovery. Check the
target agent's discovery behavior when enabling the package; agents that scan
nested manifests may expose the preserved originals separately. Distinct source skill
names are required (case-insensitively); collisions are rejected before fetching.
Handwritten reference files remain untouched. Legacy numeric snapshots keep
their locations on update; explicitly re-running merge moves registered originals
to named references and regenerates routing. Explicitly running
merge again replaces the ordered source list and regenerates routing; update
refreshes originals while preserving the current root entrypoint.
To customize integration, write the target intent and edit the routing skill directly:
mkdir -p .agents/skillctrl/intents
cp integration-requirements.md .agents/skillctrl/intents/combined.md
# Edit and verify .agents/skills/combined/SKILL.md
skillctrl record combinedOnly combined.md guides that review. Existing input skills and their local
intents are neither combined nor deleted. Keep the original snapshots intact during customization. Do not record
unresolved integration. Operations use the selected repository in place. Older skillctrl binaries do not read the private tracking file.
For a single input, add owner/repo:upstream-name --name local-name changes the
local directory and registration name, preserving original file bytes and
frontmatter. Subsequent update local-name resolves the recorded upstream name;
check local-name checks only the local accepted hash. --name requires exactly one selected skill; omit it
when importing several separate skills. The acquisition-compatible
add owner/repo --skill upstream-name syntax also remains available. Do not
combine its --skill with qualified owner/repo:skill inputs. Positional inputs must have distinct skill names, including across repositories.
- Originals are prepared in isolation. The selected adapter runs outside the caller's repository. Imported files are checked for symlinks, Git control files, and destination ignore rules before any result is promoted. The direct Git adapter reads tracked blobs without running upstream installers or hooks and preserves their executable modes. Command adapters use their native discovery and installation behavior; installed skill scripts are not executed by skillctrl.
- An unchanged original is never re-imported. That is what keeps an adaptation alive across an update that did not touch it.
- A changed original is merged, not substituted. Update applies only the difference between the previous and new originals to the local skill and reports conflicts; it replaces the skill only when no verified previous original exists, and says so.
- The accepted hash covers the whole skill directory - body, references, scripts, and executable mode - and never the intent document. Changing or deleting an intent is a decision in itself and never triggers adaptation on its own. An ambiguous upstream selection is refused. A deleted skill with a surviving intent is reported, not restored.
- Pending edits are allowed.
add,merge,update, andremovepreserve unrelated working files and the caller's staging area. An import that would replace a skill directory containing pending edits is refused before any skill is imported; unchanged originals do not overwrite those edits. Main checkouts and linked worktrees are both modified in place. skillctrl never creates a worktree or changes the working directory. Run commands from the target repository; change repositories withcdbefore invoking skillctrl. - Review and publication belong to the caller. skillctrl does not launch AI or validate an agent's judgment. Verify the skill against its saved intent before recording it. Automation should use the same checks and keep scope, tests, credentials, and PR publication in its repository-owned workflow; see agent workflow guide.