> ## Documentation Index
> Fetch the complete documentation index at: https://docs.selftune.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# selftune skills search

> Find local skills by task, author, or collection without installing them.

Ask your agent to find a skill for a task. It can search installed skills and
inactive packages in your local SelfTune Library, then read only the selected
instructions.

```bash theme={null}
selftune skills search "Corey Haines marketing" --json
selftune skills search "landing page conversions" --limit 5 --json
```

## Options

| Option              | Meaning                                                                                                   |
| ------------------- | --------------------------------------------------------------------------------------------------------- |
| `--limit N`         | Return up to N matches; default 5, maximum 20.                                                            |
| `--search-dir PATH` | Replace default installation search roots; repeat for multiple roots. The local Library remains included. |
| `--json`            | Emit query, indexed count, results, and skipped-package warnings.                                         |

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.

```bash theme={null}
selftune skills activate --id SKILL_ID --project . --harness codex --task TASK_ID --dry-run --json
selftune skills activate --id SKILL_ID --project . --harness codex --task TASK_ID --yes --json
selftune skills load --id SKILL_ID --json
selftune skills deactivate --task TASK_ID --project . --yes --json
```

Replace `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

| Command                                            | Purpose                                                                                          |
| -------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| `skills load --id ID`                              | Read one exact local skill without installing or executing it. Supports repeated `--search-dir`. |
| `skills activate --id ID --harness NAME --task ID` | Preview task-scoped activation. Select exactly one harness.                                      |
| `skills active --project PATH`                     | List unfinished temporary activations, optionally filtered by `--task`.                          |
| `skills deactivate --task ID --project PATH`       | Preview cleanup of all this task's activations in this project.                                  |
| `skills deactivate --receipt ID --project PATH`    | Preview cleanup of one temporary receipt.                                                        |

`--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, inspect `skills 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.