Options
Each result contains a name, short description, revision-qualified ID, local
package and instruction paths, collection membership, and a BM25 score.
Scores are relative relevance, not confidence. Matching uses words in names,
collection names, and
SKILL.md, including available author metadata. It does
not provide semantic synonym matching. Results may match only some query words;
verify the author and collection rather than treating a match as exact identity.
Boundaries
Search runs locally without an embedding API, database, or remote catalog request. It builds an in-memory index on each invocation, excludes archived packages, and skips instruction files larger than 256 KiB. Supporting scripts, assets, and reference files are not indexed. No packages are installed, downloaded, linked, executed, or modified.Use skills for a task
Tell your agent, “Use this marketing collection for this task.” The SelfTune skill guides it through search, selection, activation, and cleanup. The agent uses its task/session ID to keep temporary installations separate from permanent project skills.SKILL_ID with an exact ID from search. Repeat --id to select several
skills. Use --set SET_ID instead to activate every member of a saved Skill Set.
IDs must still match their local package revisions; stale or missing packages
are rejected, not silently replaced or downloaded.
Activation caches local packages once, then uses the existing installer to link
them into the selected project. Platforms that disallow symlinks use verified
copies. It does not create another saved Skill Set. Repeating the same selection
for the same task reuses its receipt. To change a task’s selection, clean up that
activation first.
Lifecycle commands
--project defaults to the current directory, which must exist. Supported
harnesses are codex, claude_code, opencode, openclaw, and pi.
Activation accepts repeated --search-dir roots for ID lookup. Activation and
deactivation preview by default; --yes applies an approved change and
--dry-run always keeps it read-only. Lifecycle results are structured JSON.
Cleanup and interruptions
Before finishing, your agent removes only the paths its activation created. Pre-existing project skills and Library packages remain. Changed or replaced targets block cleanup so your edits are preserved. A different task cannot borrow a temporary target that another unfinished task owns. If an agent crashes or is killed, there is no timer that removes skills while work might still be running. On resume, inspectskills active --task TASK_ID
and run task cleanup. An interrupted activation with an unverified target needs
manual review; cleanup will not guess that SelfTune owns it.
Use skills load or the returned instruction path in an already-running agent;
native skill-directory refresh behavior differs between clients. These commands
do not control a client’s system prompt or permission settings. Removing links
cannot erase instructions already read into a conversation.