Skip to content

Latest commit

 

History

History
324 lines (274 loc) · 18.8 KB

usage.md

File metadata and controls

324 lines (274 loc) · 18.8 KB

Local skill workflows

Detailed command behavior, adapter differences, and lock compatibility. For an introduction and installation, see README.

Set up a repository

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.

Work with skills

# 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-skill

owner/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.json

A 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.

Merge upstream skills

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 combined

The 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 combined

Only 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.

What it will and will not do

  • 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, and remove preserve 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 with cd before 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.