Skip to content
Skills Manager/DOCS
English

Library and sources

1. Inspect a source

Section titled “1. Inspect a source”
Terminal window
skills install owner/repo --list

--list shows the remote skills without installing them. If it finds more than one, you must choose which ones to install.

Reference Notes
owner/repo[/subpath] GitHub shorthand.
GitHub tree URL Retains the selected branch and path.
Git URL Use --branch for a branch or tag.
Archive URL Requires a source name on first install; internal paths are preserved.
Local path Copies content directly; remote discovery options do not apply.

2. Select and install

Section titled “2. Select and install”
Terminal window
skills install owner/repo --select skills/review --repo-alias toolbox
skills repos
skills list repo:toolbox

Repeat --select PATH to choose specific paths. --select . chooses the source root. --all installs the valid outermost skills from separate branches of the directory tree; it does not install nested skills beneath them.

Before a remote skill is copied into the Library, Skills Manager checks the selected skill directory. It refuses special files such as FIFOs or devices, symlinks that are absolute or lead outside the skill directory, and more than 20,000 entries or 512 MiB of file content. Symlinks that stay inside the skill are kept. For a Git source only the selected skills are checked, so an unsafe skill elsewhere in the repository does not block them. An archive is refused as a whole if it contains any symlink or special file. Local paths are copied as they are.

The Repos view shows each source and the skills installed from it.

Arrange the Library view

Section titled “Arrange the Library view”

The Library View controls can group skills automatically or by repository, tag, or preset. Choose None for one flat list. Groups can be ordered by name or by the number of skills they contain, and skills can be sorted by name, Library path, or search relevance. Name and path sorting support both ascending and descending order. The same grouping and sorting choices work in card, list, and compact layouts.

Auto adapts to what you are doing. While browsing, it groups skills by source and sorts them by name. Filters such as tag: still count as browsing. A query with free text becomes a flat relevance-ranked list so the strongest matches stay together. If you explicitly choose a grouping mode, the Library keeps those groups during a free-text search; with Auto sorting, it ranks the matches within each group.

Repository, tag, and preset headers can be collapsed. Grouping by tag or preset may show the same skill in more than one group when it belongs to several of them. Counts, multi-selection, and actions still identify a skill by its Library key, so a repeated skill is counted or acted on only once. Select all includes every matching skill, including matches inside collapsed groups.

Grouping, sorting, collapsed groups, and layout choices last for the current TUI session. They do not change Library files, metadata, or the saved configuration, and arranging the display does not rescan or hash skill content.

The results frame keeps its View controls in the top border. Click View or press F2 from anywhere in Library to open the menu. ←/→ switches among Layout, Group by, Sort, and Group order; Tab advances to the next category and Shift+Tab returns to the previous one. ↑/↓, j/k, and the scroll wheel apply settings immediately while keeping the menu open. Enter, Esc, or F2 closes the menu without reverting changes. Clicking an option also applies it without closing the menu; clicking outside closes it. The category tabs and options work with the mouse, while wheel events outside the popup are ignored. Group order is dimmed and skipped while the results are flat, but its previous value returns when grouping is enabled again. Relevance is unavailable without a free-text search. With a skill focused, v or V still cycles the card, list, and compact layouts.

The filled category tab identifies the open page. An arrow and a highlighted row mark the keyboard choice; ● marks the applied value and ○ marks the other values. The popup contains settings only. Shortcut hints appear only at the bottom of the screen.

Group headers show the matching and total skill counts. Select a header and press Enter or Space to toggle it, ←/h to collapse it, or →/l to expand it. Clicking a header also toggles it. To change every current matching group at once, use the collapse-all and expand-all controls in the frame border. Their labels shorten to compact text and then triangle markers as the terminal narrows. With the results focused, Ctrl+← collapses them all and Ctrl+→ expands them all; the same keys keep their normal text-editing behavior while the search input is focused.

Browse a skill’s files

Section titled “Browse a skill’s files”

Open a skill preview from any TUI view to see compact metadata, the skill’s file tree, and the selected file together on wider terminals. The preview starts on SKILL.md with the file content focused. Press ← in the content to focus the tree, or → in the tree to focus the content; Tab also switches between them. ↑/↓ or j/k move through the tree or scroll the focused content. Use Enter/l to open a file or toggle a directory, ←/h in the tree to collapse or move to its parent, gg/G to jump, and Ctrl-d/Ctrl-u to page. Directories load when first expanded; hidden entries are omitted until you press .. Press e to expand the metadata header; scroll it with j/k, arrows, PgUp/PgDn, Home, or End, then press Tab to return to the file content. The preview uses about 80% of the terminal width up to 160 columns. On terminals narrower than 64 columns, it starts with content only; press ← or Tab to show the tree, and → or Tab to return to the content. Esc or q closes the preview without changing the page beneath it.

Markdown files use the regular rendered preview. Other text has line numbers. Binary and unreadable files show an explanation; text previews are limited to 256 KiB and say when they are truncated. Symlinked directories never expand, and symlinked files are read only when their resolved target stays inside the skill directory. The browser is read-only and uses the existing ui.icons setting for Nerd Font icons or text markers.

How installed skills are named

Section titled “How installed skills are named”

The install command above uses --repo-alias toolbox, so Skills Manager stores the selected skill under repos/toolbox/. Installation prints the full Library key for use in later commands.

Name How it is used
Source display name Labels the source in the UI. Set it with --source-name NAME; Git sources default to owner/repo. A new archive URL requires a name.
Library key Identifies the stored skill. It contains the storage alias from --repo-alias and the skill’s local storage name.
Declared skill name Comes from the name field in SKILL.md and becomes the Agent link name. It does not have to match the local storage name.

For one selected skill, --name local-name sets the local storage name. For multiple selections, repeat --local-name upstream/path=local-name. These options do not change the name declared in SKILL.md, so duplicate declarations can still cause a deployment conflict.

Rename a source or stored skill

Section titled “Rename a source or stored skill”
Terminal window
skills repos rename toolbox "Team toolkit"
skills rename repos/toolbox/review repos/toolbox/review-local
Command Result
repos rename Changes the source display name only.
rename Moves the Library skill and updates metadata and managed links; frontmatter name is unchanged.

Check preset membership after changing a Library key.

Local content and metadata

Section titled “Local content and metadata”
Terminal window
skills install ./path/to/skill --name my-skill
skills adopt ./path/to/skill

install copies local content. adopt moves an external directory into the Library. If the source is directly inside a configured Agent directory, the original location becomes a link. Back up independent content before adoption.

Remote metadata lives in .skills-meta/repos/<alias>.toml; standalone records may use .skills-meta/repos/.root.toml. Records include source, installed name, revision, baseline, and optional note. Local skills do not keep these per-skill records.

Terminal window
skills set-source KEY REFERENCE
skills remove KEY --yes

skills set-source changes the recorded source without replacing content or accepting a baseline. skills remove deletes managed deployments, content, and metadata. --keep-meta preserves metadata but deletes the content. Use undeploy to remove an Agent link while retaining the skill.