# SPEC.md A behavioural specification for skills-hub: what it guarantees about the files it scans, moves, links and deletes, and about the metadata it keeps alongside them. Not how the code is built — `ARCHITECTURE.md` owns that, and `README.md` owns why the application exists. Every guarantee below is backed by a test or, where marked, a code comment making the same promise in prose; the two diagrams render guarantees already stated and cited around them and assert nothing of their own. Paths are relative to the repository root; field and file-format details are not restated here except where a guarantee depends on them — read the cited source for those. ## Identity - **An item's identity survives enabling and disabling.** The entry id hashes tool, item type, project, plugin, name and path, but strips the `.skillmanager-disabled` segment first, so moving an item into or out of that folder does not change who it is. (`crates/core/src/ids.rs`, `disabling_an_item_does_not_change_its_identity`) - **Two items of the same name in different directories never collide.** The full path is hashed, not a truncated prefix — the Obsidian plugin this is derived from truncated its slug to 80 characters, which for a deep path could let two unrelated items share one metadata note. (`crates/core/src/ids.rs`, `long_paths_sharing_an_eighty_character_prefix_do_not_collide`) - **Tool, type, project, plugin and name are all part of the identity**; changing any one changes the id. (`crates/core/src/ids.rs`, `every_component_of_the_tuple_is_part_of_the_identity`) - **The same real file reached through two different links is two separate items, independently toggleable** — collapsing them would make disabling one look like disabling both. (`crates/core/tests/scan.rs`, `two_paths_to_one_real_file_remain_two_items`) ## Item lifecycle How one item's state on disk changes, and how its metadata note tracks that. Every edge below is detailed and cited in the sections that follow. ```mermaid stateDiagram-v2 [*] --> Present: scan finds it in its tool's folder state Present { [*] --> Enabled Enabled --> Disabled: set_item_enabled(item, false) Disabled --> Enabled: set_item_enabled(item, true) } note right of Present add_to_project() may also link it into a project: a separate entry with its own id, symlinked back to this one, governed by the same rules shown here. end note Present --> Deleted: delete_item(item) Present --> Orphaned: missed by a full, warning-free scan Orphaned --> Present: found again — orphanedAt cleared Orphaned --> Trashed: 14 days past orphanedAt, no user data Orphaned --> Retained: 14 days past orphanedAt, has user data Retained --> Trashed: user explicitly forgets it Orphaned --> Trashed: user explicitly forgets it Deleted --> [*] Trashed --> [*] ``` ## Scanning ### What is an item - **A folder containing `SKILL.md` is the item; a flat `.md` file is the item.** No other shape is recognised; a folder without a manifest is descended into as a category, which is what makes `skills/engineering/tdd/SKILL.md` work. (`crates/core/src/scan/mod.rs`, `crates/core/tests/scan.rs::descends_into_a_folder_that_is_not_itself_a_skill`) - **`SKILL.md` is case-sensitive**; a `skill.md` is an ordinary flat file, not a manifest, matching the tools themselves. (`crates/core/src/fsunit.rs::the_manifest_name_is_case_sensitive`) - **A `.md` extension is matched case-insensitively** — macOS's filesystem is, and so are the tools. (`crates/core/src/scan/mod.rs`) - **A name comes from frontmatter, falling back to the file or folder name when frontmatter declares none.** (`crates/core/tests/scan.rs::falls_back_to_the_folder_name_when_frontmatter_declares_none`) - **A compound suffix — `.instructions.md`, `.prompt.md` — is stripped whole**, not just the extension, so Copilot's `foo.instructions.md` is named `foo`. (`crates/core/tests/scan.rs::strips_a_compound_suffix_whole_rather_than_only_the_extension`) - **A non-markdown file beside items in a flat folder is ignored.** (`crates/core/tests/scan.rs::finds_flat_markdown_files`) ### Traversal limits - **The item scan descends at most four levels below a configured root** — generous for any category layout seen in practice, and a ceiling against a mis-configured path (someone's whole home directory, a monorepo) turning into a full-disk crawl. (`crates/core/src/scan/mod.rs::MAX_SCAN_DEPTH`, `crates/core/tests/scan.rs::stops_descending_past_the_depth_limit`) - **The broken-symlink scan descends one level deeper (five)**, since a manifest inside a skill folder can itself be the dangling link. (`crates/core/src/scan/broken.rs::MAX_DEPTH`) - **`node_modules` and `.git` are never descended into**, by either scan. (`crates/core/tests/scan.rs::never_descends_into_node_modules_or_git`) - **A symlink loop does not repeat items or hang** — real paths of directories already entered are tracked. (`crates/core/tests/scan.rs::a_symlink_loop_does_not_repeat_items`) - **A configured "directory" that is actually a file is not an error** — Cline once used a single `.clinerules` file where every other tool uses a folder. (`crates/core/tests/scan.rs::a_configured_path_that_is_a_file_is_not_an_error`) - **A configured root that does not exist yields neither items nor warnings.** (`crates/core/tests/scan.rs::a_missing_root_produces_neither_items_nor_warnings`) ### Enabled and disabled - **The scanner pairs enabled and disabled folders at every level it visits, not only at the configured root** — a `.skillmanager-disabled` folder inside a category is found there, since an enabled-only walk skips it by name and a root-only disabled pass would miss it entirely. (`crates/core/tests/scan.rs::finds_an_item_disabled_inside_a_category_folder`) - **Nothing is treated as disabled inside a disabled folder** — a nested `.skillmanager-disabled` folder is not descended into a second time. (`crates/core/tests/scan.rs::nothing_is_disabled_within_a_disabled_folder`) ### Single-file rules - **A tool whose rule path names one file (`CLAUDE.md`, `AGENTS.md`) treats that file as the whole item**, not a directory of items; its disabled twin sits wherever the generic move puts any lone file. (`crates/core/tests/scan.rs::reads_a_single_instructions_file_as_one_item`, `finds_a_disabled_instructions_file_beside_its_enabled_position`) - **A missing instructions file yields nothing, not an error.** (`crates/core/tests/scan.rs::a_missing_instructions_file_yields_nothing_rather_than_an_error`) - **A single-file rule is never offered as an install target** — it is the user's own memory, not a thing to install into. (`crates/core/src/paths.rs::a_single_file_rule_is_not_an_install_target`) ### Symlinks during scanning - **The item scan follows symlinks — a linked-in skill is a skill** — and records both `source_path` (where found) and `real_path` (where it really lives). (`crates/core/tests/scan.rs::follows_a_symlinked_skill_and_records_where_it_really_lives`) - **A dangling symlink is skipped by the item scan rather than failing it.** (`crates/core/tests/scan.rs::a_dangling_symlink_is_skipped_rather_than_failing_the_scan`) - **Broken symlinks are found by a separate walk**: the item scan calls `metadata` (follows a link, so cannot see a dangling one) while the broken-link walk calls `symlink_metadata` (does not follow) and then checks whether the target exists. (`crates/core/src/scan/broken.rs`) - **A link that resolves is never reported as broken**, and is deliberately not descended into by the broken-link walk — following it here risks a loop, and a working link is the item scan's business. (`crates/core/tests/plugins_and_broken.rs::a_link_that_resolves_is_not_reported`) - **A dangling link inside the disabled folder is still reported** — the user parked that item on purpose; a link pointing nowhere is the same problem wherever it sits. (`crates/core/tests/plugins_and_broken.rs::a_dangling_link_inside_the_disabled_folder_is_still_reported`) - **A broken link found inside a project names that project.** (`crates/core/tests/plugins_and_broken.rs::reports_a_dangling_link_in_a_project_and_names_the_project`) ### Unreadable folders - **A folder the scan cannot read is recorded as a warning (permission denied, or otherwise unreadable), never silently dropped** — a scan that quietly returned less than it should must not look identical to one that found nothing, which is the distinction pruning relies on (see Pruning notes, below). (`crates/core/src/model.rs::ScanWarning`, `crates/core/src/scan/mod.rs::warn`) ### Project scope - **An item found inside a project carries that project's id**, and the same skill scanned globally and inside a project gets two different entry ids. (`crates/core/tests/scan.rs::a_project_scan_tags_items_with_the_project_id`, `the_same_skill_globally_and_in_a_project_gets_different_ids`) - **A user can add extra rule paths beyond a tool's one configured location**, scanned like any other root. (`crates/core/tests/scan.rs::scans_an_extra_rule_path_the_user_added`) ### Plugin bundles - **A tool marked disabled in settings is still scanned** — skipping it would make every one of its items look deleted, and the metadata store would then be entitled to discard the user's tags for all of them. (`crates/core/src/scan/mod.rs::scan_tool`) - **Absence from a tool's `enabledPlugins` map means enabled** — the file only records decisions the user actually made. (`crates/core/tests/plugins_and_broken.rs::finds_a_registry_plugin_and_the_skills_inside_it`) - **Disabling a plugin bundle makes every item inside it report disabled**, regardless of which folder the item's own file sits in. (`crates/core/tests/plugins_and_broken.rs::a_plugin_switched_off_in_settings_reports_as_disabled`) - **A Codex cached bundle counts only where its `.codex-plugin` marker file is present** — a marketplace source tree is not mistaken for an installed one — and where several versions sit mid-update, the first found wins. (`crates/core/tests/plugins_and_broken.rs::finds_a_cached_bundle_only_where_the_marker_file_is`) - **A missing or malformed plugin registry yields no plugins, not an error.** (`crates/core/tests/plugins_and_broken.rs::a_missing_or_malformed_registry_yields_no_plugins_rather_than_an_error`) - **A plugin's repository is accepted from its manifest only when it is a GitHub URL** — a half-usable value would be worse than none. (`crates/core/tests/plugins_and_broken.rs::reads_a_github_repository_from_the_manifest_and_rejects_anything_else`) - **A bundle can lay a type out in a different subfolder than the tool's own global layout** — Codex's global commands live in `prompts/`, a bundle's in `commands/`. (`crates/core/tests/plugins_and_broken.rs::a_bundle_lays_commands_out_where_the_tool_says_it_does`) - **A plugin's items are toggled and deleted only as a whole bundle**, never individually — see Toggling and deleting. ## Toggling and deleting Enable, disable and delete are the only operations that destroy anything on disk, and three rules govern all of them (`crates/core/src/toggle.rs`): 1. **Create before destroying** — the new entry is made and verified before the old one is removed; there is no instant at which neither exists. 2. **A symlink is re-pointed, never followed**, and removed with a link-specific call, never a recursive directory removal. 3. **Nothing is overwritten** — a name already taken at the destination is refused, not silently resolved. - **Disabling moves an item's whole unit — a skill's entire folder including companions, or a lone file — into a `.skillmanager-disabled` folder beside where it was; enabling moves it back to exactly where it was.** (`crates/core/tests/toggle.rs`, `disabling_a_flat_file_moves_it_into_the_disabled_folder`, `a_skill_folder_travels_whole`, `enabling_it_again_puts_it_back_exactly_where_it_was`) - **An item inside a category folder is disabled beside its own neighbours in that category, not at the tool's configured root** (the write side of the pairing rule scanning relies on, above). (`crates/core/tests/toggle.rs::an_item_in_a_category_folder_is_disabled_beside_its_own_neighbours`) - **Toggling is idempotent**: asking for the state an item is already in does nothing and succeeds, and disabling twice moves nothing the second time — a double click or a retry cannot leave an item flipped the wrong way. (`crates/core/tests/toggle.rs`, `asking_for_the_state_it_is_already_in_does_nothing`, `disabling_twice_is_not_an_error_and_moves_nothing_the_second_time`) - **A name already taken at the destination is an error, and neither file is touched.** (`crates/core/tests/toggle.rs::a_name_already_taken_is_an_error_and_nothing_is_overwritten`) - **An item that belongs to a plugin can be neither toggled nor deleted through this path** — the whole plugin must be switched off instead. (`crates/core/tests/toggle.rs::an_item_from_a_plugin_can_neither_be_toggled_nor_deleted`) - **A relative symlink is recomputed for its new depth on every move and stays relative; an absolute link stays absolute.** Carrying a relative target across unchanged would point one level off; making it absolute instead would break the moment the home directory has a different name — exactly what a relative link exists to survive. (`crates/core/tests/toggle.rs`, `a_relative_link_is_recomputed_for_its_new_depth_and_stays_relative`, `an_absolute_link_stays_absolute`) - **A relative link to a whole skill folder still resolves after the move**, and the skill it points at is never itself touched by disabling the link. (`crates/core/tests/toggle.rs`, `a_relative_link_to_a_skill_folder_still_resolves_after_the_move`, `the_skill_a_link_points_at_is_never_touched`) - **Moving one of several links to the same target leaves the others reading through correctly**, and a link survives a full disable-then-enable round trip reading exactly as it did before. (`crates/core/tests/toggle.rs`, `moving_one_of_several_links_to_the_same_target_leaves_the_others_alone`, `a_link_survives_a_full_round_trip`) - **A relocated symlink's new location is checked before the original is removed**; if it does not resolve to the same target, the move aborts rather than deleting the original. Not test-covered — see the closing section. (`crates/core/src/toggle.rs::relocate_symlink`) - **Deleting a flat file or a skill folder removes it entirely.** (`crates/core/tests/toggle.rs`, `deleting_a_flat_file_removes_it`, `deleting_a_skill_removes_the_whole_folder`) - **Deleting a project link removes only the link, never the skill it points at** — see Cross-cutting for how a directory symlink is always removed without touching its target. (`crates/core/tests/toggle.rs::deleting_a_project_link_removes_the_link_and_not_the_skill`) - **Switching a whole plugin on or off writes into the owning tool's own settings file, preserving every other key in it** — a plugin with no recorded decision yet can still be switched off; a tool with no usable settings file says so rather than inventing one. (`crates/core/tests/toggle.rs`, `switching_a_plugin_off_records_it_without_disturbing_other_settings`, `a_plugin_with_no_recorded_decision_can_still_be_switched_off`, `a_tool_with_no_settings_file_says_so_rather_than_inventing_one`) - **A move across a filesystem boundary copies then removes the original, only after the copy succeeds** — an interruption leaves two copies, never none. (`crates/core/src/toggle.rs::copy_then_remove`) - **Deleting an item is a real filesystem removal, not a move to the trash.** Only the metadata store's own pruning (see Pruning notes) sends anything to the OS trash; `toggle::delete_item` calls `remove_file` / `remove_dir_all` / a link-specific removal directly. (`crates/core/src/toggle.rs::delete_item`) ## Linking into a project `crates/core/src/projectlink.rs`. - **Linking is always by symlink, never by copy** — a copy is a second thing to keep in step with the first, and removing a link takes nothing from the original. (`crates/core/src/projectlink.rs`) - **A link is created using the same path resolution the scanner uses**, so it lands where the tool will actually look — the Obsidian plugin this is derived from stripped `~/` off the global path instead, which for Copilot put a rule at `.copilot/instructions` when the project convention is `.github/instructions`, a folder nothing reads. (`crates/core/tests/projectlink.rs::honours_a_tools_project_path_rather_than_deriving_it`) - **A link points at where the item really lives, never at another link** — chaining through an intermediate link would break as soon as any hop moved. (`crates/core/tests/projectlink.rs::links_through_to_where_the_item_really_lives`) - **Linking is idempotent**: linking something already linked changes nothing. (`crates/core/tests/projectlink.rs::linking_twice_changes_nothing`) - **Unlinking removes only the link and leaves the skill untouched**; unlinking anything that is not itself a symlink is refused, so this path can never become a way to delete a real item by accident. (`crates/core/tests/projectlink.rs`, `unlinking_removes_the_link_and_leaves_the_skill`, `unlinking_something_that_is_not_a_link_is_refused`) - **A tool with nowhere in a project to put a given item type says so**, rather than guessing a location. (`crates/core/tests/projectlink.rs::a_tool_with_nowhere_to_put_it_says_so`) - **A linked item is found by a subsequent project scan**, tagged with that project's id. (`crates/core/tests/projectlink.rs::the_project_scan_then_finds_the_linked_item`) ## Metadata notes `crates/core/src/store/` — one markdown note per item. - **One note file exists per item, named after its entry id.** (`crates/core/tests/store.rs::creates_one_note_per_item_named_after_its_id`) - **A note is written only when something in it would actually change** — not even a matching rescan touches the file's mtime. `lastScanned` alone does not count as a change, so a synced or version-controlled notes folder is never shown as fully modified after a routine scan. (`crates/core/tests/store.rs::a_second_scan_that_found_the_same_thing_writes_nothing`) - **A changed derived field — description, enabled state, and so on — is written through on the next scan**, while tags, favourites and collections are never touched by a scan. (`crates/core/tests/store.rs`, `a_changed_description_is_written_through`, `a_rescan_does_not_disturb_tags_favourites_or_collections`) - **An edit made outside the application survives the next scan** — a hand-added tag, hand-written prose, or a frontmatter key the application does not itself recognise. (`crates/core/tests/store.rs`, `an_edit_made_outside_the_application_survives_the_next_scan`, `an_unknown_frontmatter_key_survives_a_rescan`) - **Notes are written atomically**, through a temporary file in the same directory and a rename, so a reader — Obsidian, a sync client — never sees a half-written note. (`crates/core/src/store/mod.rs::write`) - **A tag update trims, de-duplicates case-insensitively, keeps the first casing seen, and preserves order.** (`crates/core/tests/store.rs::tags_are_trimmed_and_de_duplicated_without_being_reordered`) - **Updating an item that was never scanned is an error, not a new note.** (`crates/core/tests/store.rs::updating_something_that_was_never_scanned_is_an_error_not_a_new_note`) - **A markdown file in the notes folder this application did not write is left alone entirely**, reported separately as "foreign" rather than parsed or adopted. (`crates/core/tests/store.rs::a_markdown_file_that_is_not_ours_is_left_alone`) - **A note whose `enabled` key is missing reads as enabled** — a note nobody can classify describes an item that is present; hiding it would be the more surprising error. (`crates/core/src/store/note.rs::a_missing_enabled_key_reads_as_enabled`) - **Provenance fields are left out of the file entirely until there is a value to write**, rather than appearing empty. (`crates/core/src/store/note.rs::provenance_is_left_out_of_the_file_until_there_is_any`) ### Pruning notes `crates/core/src/store/prune.rs`. The question is never "was it found?" but "is this scan entitled to conclude it is gone?" — a scan can miss an item for reasons that have nothing to do with the item: an unmounted volume, a folder macOS withheld consent for, a tool mid-reinstall. ```mermaid flowchart TD A[A scan runs] --> B{Every tool and
project covered?} B -- no --> X[Prunes nothing — PartialScan] B -- yes --> C{Any folder
unreadable?} C -- yes --> Y[Prunes nothing — ScanHadWarnings] C -- no --> D{Found anything
at all?} D -- no --> Z[Prunes nothing — ScanFoundNothing] D -- yes --> E{This note's item found,
or its symlink merely broken?} E -- yes --> F[Kept — ensure() already
cleared orphanedAt if set] E -- no --> G{Already marked
orphanedAt?} G -- no --> H[Mark orphanedAt now —
nothing deleted] G -- yes --> I{14 days past
orphanedAt?} I -- no --> J[Left alone] I -- yes --> K{Note has user data?
tags, favourite, collections, …} K -- yes --> L[Retained — listed for
the user to decide] K -- no --> M[Moved to the OS trash] ``` - **Prunes nothing unless the scan was full, warning-free, and found at least one item** — partial, warning-carrying or wholly-empty scans are never evidence of absence. (`crates/core/tests/store.rs`, `a_partial_scan_prunes_nothing`, `a_scan_that_could_not_read_something_prunes_nothing`, `a_scan_that_found_nothing_at_all_prunes_nothing`) - **A missing item is marked orphaned before it is ever removed** — the first miss only sets `orphanedAt`. (`crates/core/tests/store.rs::a_missing_item_is_marked_before_it_is_ever_removed`) - **An orphaned note waits fourteen days (`ORPHAN_GRACE`) before it can be trashed**, and is untouched if found again in the meantime, which clears the marker. (`crates/core/src/store/prune.rs::ORPHAN_GRACE`, `crates/core/tests/store.rs`, `a_note_is_not_removed_before_the_grace_period_is_up`, `an_item_that_comes_back_stops_being_an_orphan`) - **Past the grace period, a note carrying anything the user put there — a tag, a favourite, a collection, provenance, or an unrecognised key — is never auto-deleted**; it is listed for the user to decide instead. (`crates/core/tests/store.rs::a_note_carrying_user_data_is_never_removed_automatically`) - **An item behind a currently broken symlink keeps its note without even being marked orphaned** — the file is visibly there, just broken. (`crates/core/tests/store.rs::an_item_whose_symlink_is_broken_keeps_its_note`) - **The user can explicitly forget an orphan**, trashing its note regardless of grace period or user data. (`crates/core/tests/store.rs::the_user_can_let_an_orphan_go`) - **Anything the store removes goes to the OS trash, never straight deletion**; a trash failure leaves the note in place. (`crates/core/src/store/prune.rs`) - **A timestamp that cannot be parsed counts as not past the grace period** — a note nobody can date is not a note to delete. (`crates/core/src/store/prune.rs::past_grace`) ## Installing, updating and restoring `crates/core/src/install.rs`. - **Install refuses to overwrite anything already at the destination name**, and installs nothing if it would. (`crates/core/tests/install.rs::refuses_to_overwrite_something_already_there`) - **What lands on disk is plain files: the clone's `.git` directory is stripped before anything is copied out**, so an installed item never becomes a nested checkout. (`crates/core/tests/install.rs::what_lands_on_disk_has_no_repository_in_it`) - **Installing a folder skill copies the whole folder, companions included; installing a flat file copies the file**, into either the home directory or a specific project. (`crates/core/tests/install.rs`, `installs_a_folder_skill_where_the_tool_reads_it`, `installs_a_flat_file`, `installs_into_a_project_when_asked`) - **Installing an empty subpath (the whole repository) names the item after the repository.** (`crates/core/tests/install.rs::names_a_whole_repository_after_the_repository`) - **A subpath that does not exist in the repository fails outright and installs nothing.** (`crates/core/tests/install.rs::a_subpath_that_is_not_there_says_so_and_installs_nothing`) - **What was installed records the repository, ref, subpath and exact commit** — the entire basis for checking updates, diffing, and restoring. (`crates/core/tests/install.rs::records_where_it_came_from_so_it_can_be_updated_later`) - **An item is reported `Current` until the remote branch moves on, `Stale` once it has, and `Untracked` for anything not installed through this application** — an untracked item is never checked against a remote. (`crates/core/tests/install.rs`, `says_an_item_is_current_until_the_remote_moves_on`, `an_item_nobody_installed_is_not_checked_at_all`) - **A review shows what an update or restore would change before anything on disk is touched** — a real line-level diff for the manifest, an added/removed/modified verdict for every other file, computed but not applied. (`crates/core/tests/install.rs::a_review_shows_what_would_change_before_anything_does`) - **If the tracked commit moved on but this item's content did not, the review says so rather than showing an empty diff** — a repository holding many skills moves on for reasons that can have nothing to do with any one of them. (`crates/core/tests/install.rs::says_when_the_commit_moved_but_this_item_did_not`) - **Applying a review replaces the local copy wholesale**; a file the update removed upstream is gone locally too, not left behind. (`crates/core/tests/install.rs::applying_a_review_replaces_the_local_copy`) - **Restoring an item brings back the exact commit it was installed at** — see Talking to git for how an exact commit is fetched even though every other clone here is shallow. (`crates/core/tests/install.rs::restoring_brings_back_the_commit_it_was_installed_at`) - **Reviewing an item with no recorded install provenance is refused outright.** (`crates/core/tests/install.rs::reviewing_something_that_was_never_installed_from_anywhere_is_refused`) ## Discovering installable items in a repository `crates/core/src/discover.rs` — no GitHub API, no permanent clone. - **What something is comes from where it sits, never from what is in it.** A folder holding `SKILL.md` is a skill; a markdown file inside a folder named `agent(s)`, `command(s)`, `prompt(s)` or `rules` is one of those, and the type carries down into subfolders. (`crates/core/tests/discover.rs`, `reads_the_type_from_the_folder_it_is_in`, `the_type_carries_down_into_subfolders`) - **A loose markdown file with nothing declaring what it is — no typed folder, no `SKILL.md` beside it — is not counted as an item.** (`crates/core/tests/discover.rs::a_loose_markdown_file_with_nothing_saying_what_it_is_is_not_an_item`) - **A skill's own companion files are never separate items** — its `references/`, its own nested `commands/`, are not walked as items. (`crates/core/tests/discover.rs::a_skills_own_files_are_not_separate_items`) - **Dot-folders are searched, unlike `node_modules` and `.git`** — Copilot keeps prompts under `.github/`, a Claude plugin's manifest under `.claude-plugin/`. (`crates/core/tests/discover.rs`, `looks_inside_dot_folders`, `never_looks_inside_node_modules_or_git`) - **A subpath can point straight at one skill's folder or one markdown file, and finds exactly that item** — the natural result of pasting a link to a single skill. A subpath absent from the repository is refused. (`crates/core/tests/discover.rs`, `a_subpath_pointing_straight_at_a_skill_finds_it`, `a_subpath_pointing_straight_at_a_markdown_file_finds_it`, `a_subpath_that_is_not_there_says_so`) - **A repository with nothing installable yields an empty result, never a failure.** (`crates/core/tests/discover.rs::a_repository_with_nothing_installable_yields_nothing_rather_than_failing`) - **The same repository, branch and subpath is always the same source identity.** (`crates/core/tests/discover.rs::the_same_repository_branch_and_subpath_is_the_same_source`) - **Re-fetching a watched source replaces everything previously known about it** — an item since gone from the repository disappears from the catalogue too. (`crates/core/tests/discover.rs::refetching_a_source_replaces_what_was_known_about_it`) - **Removing a watched source takes every entry it produced with it, and two watched sources keep fully independent entries.** (`crates/core/tests/discover.rs`, `removing_a_source_takes_its_entries_with_it`, `two_sources_keep_their_own_entries`) - **An unreadable discover catalogue file starts empty rather than refusing to open** — nothing in it cannot be found again simply by re-adding the repository. (`crates/core/src/discover.rs::CatalogFile::load`) ## Talking to git `crates/core/src/git.rs` — every operation clones into a throwaway temporary directory and discards it; nothing here keeps a permanent working copy. - **Any single git command is killed after 45 seconds, and credential prompting is disabled outright** (`GIT_TERMINAL_PROMPT=0` and equivalents), so a repository that wants credentials fails fast instead of hanging with nothing able to answer the prompt. (`crates/core/src/git.rs::TIMEOUT`, `crates/core/tests/git.rs::a_repository_needing_credentials_fails_rather_than_hanging`) - **A clone deletes itself as soon as it goes out of scope, including on an early return** — the temporary directory is owned by the clone value itself. (`crates/core/tests/git.rs::the_clone_is_deleted_when_it_goes_out_of_scope`) - **An empty ref name means the repository's default branch.** (`crates/core/tests/git.rs::an_empty_ref_means_the_default_branch`) - **A subpath that would climb out of a clone (`../`) is refused.** (`crates/core/tests/git.rs::refuses_a_subpath_that_climbs_out_of_the_clone`) - **A branch or repository that does not exist fails with an error carrying git's own message**, not a generic one. (`crates/core/tests/git.rs`, `a_branch_that_is_not_there_is_an_error_rather_than_an_empty_answer`, `a_repository_that_is_not_there_fails_with_what_git_said`) - **Restoring an exact historical commit works even though every other clone is shallow and can otherwise only see a branch's tip**, by fetching that one commit directly. A host that will not hand over an arbitrary commit fails with a message pointing at checking for updates instead; a commit id that is not a real hex identifier is refused before any git command runs. (`crates/core/tests/git.rs`, `fetches_one_exact_commit_for_a_restore`, `a_commit_the_host_will_not_hand_over_says_so`, `something_that_is_not_a_commit_id_is_refused_before_anything_runs`) ## Settings `crates/core/src/settings.rs` — the settings file is an overlay on the compiled-in tool registry, holding only what a user may override. - **A settings file written by an older version can never shadow a field the current registry knows about.** This is structural, not a maintained whitelist — the Obsidian plugin this is derived from stored whole tool objects and once shipped an incomplete field list that silently broke project paths for everyone. (`crates/core/tests/settings.rs::a_settings_file_written_by_an_older_version_cannot_shadow_the_registry`) - **Overriding one type's path for a tool leaves every other type's path, and every field the override does not name, untouched.** (`crates/core/tests/settings.rs::an_override_of_one_path_does_not_disturb_the_others`) - **An empty-string path override explicitly turns that item type off**, distinct from no override at all (which uses the shipped default). (`crates/core/tests/settings.rs::an_empty_path_turns_that_type_off_entirely`) - **A tool the user has disabled stays in the effective tool list**, so it can still be scanned — removing it outright would make every item of that tool look deleted to the metadata store. (`crates/core/tests/settings.rs::a_disabled_tool_is_still_in_the_list_so_it_can_still_be_scanned`) - **A custom tool the shipped registry later adopts under the same id defers to the registry's version.** (`crates/core/tests/settings.rs::a_custom_tool_the_registry_has_since_adopted_does_not_appear_twice`) - **A reordered sidebar stays exactly as the user left it.** A section added by a later release appears at its default relative position rather than vanishing or landing arbitrarily at the end; a section that no longer exists is dropped. (`crates/core/tests/settings.rs`, `a_reordered_sidebar_is_kept_as_the_user_left_it`, `a_section_added_by_an_update_appears_at_its_default_position`, `a_section_that_no_longer_exists_is_dropped`) - **A theme value written before the palette list grew still loads correctly**, even though the naming scheme changed from `lowercase` to `kebab-case` — the values that existed before spell the same either way. (`crates/core/tests/settings.rs::a_theme_written_before_the_palettes_grew_still_loads`) - **A missing settings file means defaults, not an error**, and a corrupt one is quarantined — moved aside with a timestamped name — rather than blocking startup. (`crates/core/tests/settings.rs`, `a_missing_file_means_defaults_rather_than_an_error`, `a_corrupt_file_is_set_aside_and_the_application_still_starts`) - **Every save keeps one copy of the previous good file**, as `settings.backup.json`. (`crates/core/tests/settings.rs::saving_keeps_a_copy_of_the_last_good_file`) - **The written settings file is pretty-printed, hand-editable, and contains none of the registry's own fields.** (`crates/core/tests/settings.rs::the_written_file_is_readable_and_hand_editable`) - **Settings, the discover catalogue and dismissals are all written atomically**, the same temp-file-then-rename pattern as metadata notes. (`crates/core/src/settings.rs::SettingsFile::save`, `crates/core/src/discover.rs::CatalogFile::save`, `crates/core/src/dashboard.rs::DismissalsFile::save`) ## MCP configuration `crates/core/src/mcp.rs` — read-only; editing another tool's own configuration is not attempted. - **A server defined both globally and inside a project appears as two separate entries, never collapsed** — seeing that a project overrides the global setup is exactly why this page exists. (`crates/core/tests/phase3.rs::the_same_name_in_two_places_is_two_entries`) - **An unreadable or malformed configuration file produces an explicit warning naming the file**, never a silently empty list; a file with simply no server map is not treated as malformed. (`crates/core/tests/phase3.rs`, `a_config_that_cannot_be_read_is_reported_rather_than_silently_empty`, `a_config_with_no_servers_in_it_is_not_a_problem`) - **A tool with no MCP configuration declared is skipped without a warning.** (`crates/core/tests/phase3.rs::a_tool_with_no_mcp_configuration_is_simply_skipped`) - **A tool can name its own key for the server map** — VS Code uses `"servers"`, not `"mcpServers"`. (`crates/core/tests/phase3.rs::honours_a_tools_own_key_for_the_server_map`) - **TOML configuration is parsed with a real parser, not a line scanner**, which means one syntax error invalidates the whole file — hence the explicit warning rather than silent partial results. (`crates/core/src/mcp.rs`) ## Usage and cost `crates/core/src/usage/`, `crates/core/src/dashboard.rs` — read from the tools' own session transcripts on disk; nothing is sent or recorded anew. - **Only skills and agents can show recorded usage.** A slash command expands into message text with no distinct event, and a rule is never "invoked" — it is simply part of the context; these are absent by construction, not filtered zeroes. (`crates/core/src/usage/mod.rs`, `crates/core/tests/phase3.rs::joins_usage_onto_the_items_it_belongs_to`) - **A tool-use block that only appears inside a user-role message (an echo) is never counted as an invocation** — only an assistant-authored one is. (`crates/core/tests/phase3.rs::ignores_everything_that_is_not_an_assistant_turn`) - **Usage accumulates across every project and session, all-time, never windowed** — a use from a year ago still counts, and a known but never invoked item shows an explicit zero, not an absence of data. (`crates/core/tests/phase3.rs`, `adds_up_across_every_project_and_session`, `joins_usage_onto_the_items_it_belongs_to`) - **A plugin-bundled item's invocation is matched by its plugin's short name** (before the `@marketplace` suffix), not the bundle id verbatim. (`crates/core/tests/phase3.rs::a_plugin_item_is_invoked_by_its_plugin_name`) - **Codex usage is inferred from paths inside a recorded tool call's input, never from an item merely being listed as available**, and a name that only appears as a substring of an unrelated path is not counted. (`crates/core/tests/phase3.rs`, `infers_codex_usage_from_the_paths_in_commands_it_ran`, `does_not_count_a_name_that_merely_appears_inside_another`) - **What a tool carries every turn — name and description — is measured separately from what it loads once invoked.** Commands and rules get no per-turn figure at all: how each tool loads them is not modelled, and a file's raw size would mislead more than saying nothing. (`crates/core/tests/phase3.rs`, `separates_what_is_always_loaded_from_what_is_loaded_on_use`, `does_not_guess_at_what_a_command_or_rule_costs_per_turn`) - **A disabled item costs nothing and is not measured at all.** (`crates/core/tests/phase3.rs::a_disabled_item_costs_nothing_and_is_not_measured`) - **A recorded invocation settles a pruning suggestion outright**, whatever the file looks like; with no usage history it falls back to size and age, needing both — large *for this library* (a moving percentile) and long untouched. (`crates/core/tests/phase3.rs`, `a_recorded_invocation_settles_it_whatever_the_file_looks_like`, `with_no_usage_it_takes_both_large_and_old_to_be_flagged`) - **Two items of the same type with the same name (case-insensitively) are always flagged as an outright overlap**; otherwise only when names and descriptions are similar enough to plausibly compete for the same request, and never for the same real file reached by two paths. (`crates/core/tests/phase3.rs`, `flags_two_items_with_the_same_name_and_type`, `flags_two_items_whose_descriptions_are_much_alike`, `does_not_flag_one_file_reached_by_two_paths`) - **An overlap pair's identifier is the same whichever order the two items are compared in.** (`crates/core/tests/phase3.rs::the_pair_reads_the_same_whichever_way_round_it_comes`) - **Rule-type items are excluded from overlap detection entirely** — a single instructions file has no declared name of its own, and every copy would collide with every other on filename alone. (`crates/core/src/dashboard.rs::overlaps`) ## Registry search `crates/core/src/registry.rs` — reading skills.sh search answers. Mostly about what gets rejected, since a result's `source` is handed straight to git. - **A `source` value that is not a plausible `owner/repo` GitHub reference is rejected outright**, because that string is passed directly to git. (`crates/core/tests/registry.rs::refuses_a_source_that_is_not_an_owner_and_a_repository`) - **One malformed row in a search response is dropped; the rest of the response is still returned**, and unknown fields are ignored, not rejected. (`crates/core/tests/registry.rs`, `drops_one_bad_row_rather_than_the_whole_answer`, `a_bad_source_takes_only_its_own_row_with_it`, `ignores_fields_it_does_not_know`) - **A response that is not JSON at all is a clear, distinct error.** (`crates/core/tests/registry.rs::an_answer_that_is_not_json_says_so`) ## Cross-cutting - **`$HOME` is always an explicit parameter inside the domain crate, never read from the environment** — the one decision that makes every guarantee above testable against a disposable temporary directory. (`crates/core/src/paths.rs`, `crates/core/src/lib.rs`) - **A directory symlink is always removed with a link-specific call (`remove_file` on Unix, `remove_dir` on Windows), never `remove_dir_all`**, which on a directory symlink would delete the tree it points at rather than the link. (`crates/core/src/platform.rs::remove_symlink`, `removing_a_directory_symlink_leaves_the_target_tree_intact`) - **On macOS, moving a file to the trash goes through `NSFileManager`, not Finder via AppleScript** — Finder needs an automation permission that may not be granted, and can block for a minute before failing outright. The file still lands in the Trash; only Finder's "Put Back" is unavailable. (`crates/core/src/platform.rs::move_to_trash`) - **Symlink creation on Windows can be probed ahead of time**, since it requires Developer Mode or a privilege the user may not hold, and failing only when the user tries to link something would be a worse time to find out. (`crates/core/src/platform.rs::probe_symlink_support`) ## What was read to write this, and what could not be verified Read in full: every file under `crates/core/tests/`, and every non-generated file under `crates/core/src/` except `tools.rs` and `usage/claude.rs` / `usage/codex.rs`, which were read only in part — their guarantees above come from `crates/core/tests/phase3.rs`, which exercises them directly. `README.md` and `CLAUDE.md` were read for register and scope, not for guarantees. Not verified: - `toggle::relocate_symlink`'s safeguard that aborts a move rather than deleting the original link when the new one doesn't resolve to the same target — stated directly in the code, but no test forces this failure path. - Windows-specific behaviour (`symlink_dir` vs `symlink_file`, `remove_dir` for a directory symlink, the Developer Mode check) is implemented and unit-tested in `crates/core/src/platform.rs`, but this pass ran no Windows CI job — cross-platform parity is taken on the code's word. - Nothing under `src-tauri/` or `src/` was read; every guarantee above is scoped to `skills-core`.