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.
Prepare skills in Desktop
In Skills Library, choose Review suggestions for recommendations from local usage history, or Choose skills to select occasional-use skills yourself. Review the per-harness context projection and choose Keep selected on demand. SelfTune saves a verified Library copy before removing each active installation. These copies remain available toskills search, load, and activate.
Undo restores the original installations. After reopening the app, use the
skill’s Restore action. The Library copy is retained. Identical installations
are consolidated automatically into one searchable Library revision when moving
on demand, with a restore receipt for each original location. Different revisions
require review; system and admin skills are protected. Every selected revision is
checked before removing any installation of that skill.
Ordinary quarantine does not create a searchable copy.
Context savings by harness
The UI estimates discovery overhead from actual local metadata, not full skill instructions. Claude Code uses name and description (includingwhen_to_use,
capped at 1,536 characters); Codex also includes the file path; OpenCode uses an
XML name/description entry; Pi includes an XML location too. Claude and Pi
disable-model-invocation: true entries contribute zero discovery tokens.
Tokens remain estimates at four bytes per token. These are not measured model
usage: host budgets, visibility settings, additional shared search paths and
model tokenizers affect the actual prompt. Unknown metadata or unsupported
harnesses show Unknown, not zero. Different project scopes are not added
together. Only archived installations with a retained cached revision count as
avoided overhead; arbitrary cached skills do not create fictional savings.
Removing a skill cannot remove instructions already read into a conversation.
Loading behavior sources: Claude Code,
Codex,
OpenCode, and
Pi’s prompt formatter.
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.