Skill Manager Agent Brief

Project Intent

skill-manager is a local tool for managing globally installed agent skills for Claude Code, Codex, Muse, and Grok. Its established terminal interfaces remain the primary source-management surface, with a macOS desktop interface for visibility and reversible toggles.

The first version is a local, simple, reversible TUI plus a minimal CLI. It must make it easy to see which skills are enabled for each tool and toggle them off and on without losing their original installation method.

This repository is intentionally greenfield. The planning discussion happened before implementation. Preserve these decisions unless the user explicitly changes them.

Public Text

This repository is public. Pull request bodies, commit messages, issues, docs, wiki, plans, and fixtures describe behavior for every user with synthetic examples. Review that public text with docs/contributing/public-text.md before git push and before creating or editing a pull request, issue, or release.

Mandatory Wiki Routing

This project has an LLM-maintained wiki under docs/wiki/.

Before starting non-trivial work in this repository:

1. Read docs/wiki/README.md for the wiki contract, source precedence, and workflows.
2. Read docs/wiki/index.md, then open the topic pages relevant to the task.
3. Verify important or mutable claims against the authoritative project files; the wiki is a synthesis layer, not a replacement for this file, the planning documents, code, or tests.

After work that produces a reusable conclusion, correction, decision, implementation insight, or open item, update the relevant docs/wiki/topics/ or docs/wiki/sources/ pages, update docs/wiki/index.md when pages change structurally, and append an entry to docs/wiki/log.md using ## [YYYY-MM-DD] type | Short title.

If the user accepts a change to product scope, semantics, paths, or UX, update the authoritative files required by the Documentation Rules below before bringing the wiki synthesis up to date.

Current Target Environment

The supported source release targets Apple Silicon macOS and the standard global skill layout:

• Claude Code user skills: ~/.claude/skills
• Codex user skills: ~/.agents/skills
• Muse user skills: ~/.config/muse/skills ($XDG_CONFIG_HOME/muse/skills when set)
• Grok user skills: ~/.grok/skills
• Codex system skills: ~/.codex/skills/.system
• Claude plugin cache: ~/.claude/plugins/cache
• Skill Manager state: ~/.skill-manager
• Skill Manager managed repo checkouts: ~/.skill-manager/repos

For MVP, use these paths from $HOME directly. Do not add config file support in the first iteration.

Discovery Model

The application must not depend on a captured machine inventory. It scans the filesystem each run and supports any valid skills found under the fixed paths. Tests, demo data, screenshots, and documentation examples use synthetic homes, repositories, skill names, and counts (see Public Text).

Core Product Decisions

Toggle Semantics

Disable means the skill disappears from the directory scanned by Claude Code, Codex, Muse, or Grok.

Enable means the exact previous entry is restored.

The tool must preserve:

• Whether the original entry was a symlink or directory
• The symlink target, if any
• The original tool-specific path
• The source classification, when detectable

Enable/disable operations must not:

• Delete source repositories
• Edit SKILL.md
• Modify git checkout contents
• Rewrite Skills CLI lockfiles
• Rewrite Claude plugin cache contents

Managed vs Read-Only Sources

Managed and toggleable in MVP:

• Claude Code user skills in ~/.claude/skills
• Codex user skills in ~/.agents/skills
• Muse user skills in ~/.config/muse/skills ($XDG_CONFIG_HOME/muse/skills when set)
• Grok user skills in ~/.grok/skills

Read-only in MVP:

• Codex system skills in ~/.codex/skills/.system
• Claude plugin skills in ~/.claude/plugins/cache
• Any plugin marketplace checkout skills

Plugin enable/disable is out of scope for MVP. A future Plugins screen may toggle whole Claude plugins through ~/.claude/settings.json.enabledPlugins, but the first Skills screen must not do that.

Skills CLI Installs

Skills installed through npx skills are in scope if they are present under ~/.agents/skills.

Use ~/.agents/.skill-lock.json only for source labeling, not as the control surface. Do not edit the lockfile during enable/disable.

Tests and documentation should use synthetic Skills CLI entries such as catalog-search from example-labs/skills.

Invalid Skill Directories

Entries without SKILL.md are hidden in MVP.

Do not show or manage ~/.claude/skills/invalid-entry unless a future plan explicitly adds invalid-entry cleanup.

Source Labels

The UI should classify skills using source details and a source filter.

Expected source labels:

• symlink repo
• Skills CLI
• local
• Codex system
• Claude plugin

If a source cannot be determined, use a conservative unknown label and do not block listing.

Groups

Group is a first-class display and bulk-toggle concept.

A group is an automatically detected source package, repository, or collection. It is not manually configured in MVP2.

Expected group labels:

• GitHub repo symlinks: owner/repo
  • https://github.com/example-labs/engineering-skills.git -> example-labs/engineering-skills
  • https://github.com/sample-org/product-skills.git -> sample-org/product-skills
• Non-GitHub git remotes: best stable remote-derived label, falling back to repo root directory name
• Git repo with no remote: repo root directory name
• Skills CLI installs: Skills CLI
• Link-in-place local path installs: canonical source root basename
• Local managed directories: local
• Codex system read-only skills: Codex system
• Claude plugin read-only skills: Claude plugin
• Unknown: unknown

Group and Source are different:

• Source describes the installation mechanism, e.g. symlink repo, Skills CLI, local path, local.
• Group describes the collection the skill belongs to, e.g. example-labs/engineering-skills, sample-org/product-skills.

The main TUI table uses Group instead of Source. Details still show both Group and Source.

Repository Install (Iteration 3)

Iteration 3 adds CLI-first installation from Git repositories. Do not add a TUI install screen in this iteration.

Install source and layout:

• skill-manager install <git-url> clones Git repositories into ~/.skill-manager/repos/<host>/<repo-path>.
• Example: https://github.com/addyosmani/agent-skills clones into ~/.skill-manager/repos/github.com/addyosmani/agent-skills.
• Installed skills are represented in Claude/Codex/Muse/Grok user skill directories as symlinks to skill directories inside the managed checkout.
• Moving or toggling those symlinks must not modify the managed checkout.

Supported repository inputs for Iteration 3:

• HTTPS Git URLs, with or without .git.
• SSH Git URLs such as git@github.com:addyosmani/agent-skills.git.

Out of scope for Iteration 3:

• Branch, tag, or commit selection.
• Local path installs.
• GitHub shorthand such as addyosmani/agent-skills.
• Submodules, sparse checkout, and update operations.
• Uninstall operations.
• --force or overwrite behavior.
• Mutating group/all CLI commands.

Future repository-management work is planned but intentionally deferred:

• skill-manager install --branch
• skill-manager install --force

Tool targeting:

• Default target is every supported tool. Empty, both, and all are equivalent.
• --tool claude, --tool codex, --tool muse, --tool grok, --tool both, and --tool all are accepted. Empty, both, and all all target every supported tool.
• --skill <name>[=<path>] may be repeated to install selected skills only. The optional =<path> qualifies one source-relative copy when a name was discovered at several paths with differing content.
• If no --skill is provided, install all valid skills discovered in the repository.

Repository reuse:

• If the checkout does not exist, clone it.
• If the checkout exists and its remote matches the requested URL, reuse it without git pull.
• If the checkout exists but its remote does not match, fail as a conflict.
• install must not update an existing checkout. Repository changes use the separate explicit update command from Iteration 4.

Skill discovery:

• A valid installable skill is any directory containing SKILL.md.
• Discovery is recursive inside the checkout.
• Ignore heavy or generated directories such as .git, node_modules, .venv, vendor, build, and dist.
• Skill name is the basename of the directory containing SKILL.md. The install name (the link basename in each tool directory) equals the skill name unless the skill is installed under another name with --as (Iteration 26).
• Skills sharing one basename are grouped instead of failing discovery (Iteration 25). Identical copies resolve to one canonical copy; differing copies need an explicit --skill <name>=<path> choice.
• Invalid directories without SKILL.md are skipped.

Conflict and idempotency rules:

• Preflight all selected skill/tool symlink targets before creating any symlink.
• If the target path is free, it may be linked.
• If the active target path already is a symlink to the same repo skill directory, treat it as already installed and OK.
• If a disabled state entry exists for the same tool and skill and points to the same repo skill directory, treat it as already installed but currently OFF. Do not implicitly enable it.
• If the tool/install-name cell is recorded as owned by another Git or local source, fail preflight even when the active path is free or happens to match. When the blocked name is the plain skill name and this source has no record for it, the failure suggests a free install name (Iteration 26).
• If the target path exists and is anything else, fail before creating new symlinks.
• Do not overwrite, merge, delete, or rename blockers.

Install apply behavior:

• After a clean preflight, create symlinks for selected skills and tools. With Install as OFF (Iteration 23), new links are created directly at the disabled path instead.
• If symlink creation fails after some links were created, remove only the links created by that failed install operation.
• If saving the install state fails, remove the links created by that operation as well, for Git and local sources alike.
• Do not remove a checkout created earlier in the operation. Keeping the clone makes retry cheaper and safer.
• Do not write a partial install manifest when symlink creation fails.

Dry-run behavior:

• install --dry-run is strict and must not clone repositories.
• If the repo is not already checked out locally, print that the repo would be cloned and that skill discovery is unavailable until real install.
• If the repo is already checked out locally, discovery and preflight may run against the local checkout and print planned symlinks/conflicts.
• Dry-run must not create symlinks or mutate state.json.

State and lockfiles:

• Store repository installation metadata in ~/.skill-manager/state.json.
• Do not edit .agents/.skill-lock.json, Claude plugin metadata, Skills CLI lockfiles, or any external manager lockfiles.
• Use the Skill Manager manifest as the source of truth for repositories installed by skill-manager.

Runtime visibility:

• install changes filesystem state for future Claude/Codex/Muse/Grok runs.
• Already running Claude/Codex/Muse/Grok sessions may not see newly installed skills. Documentation should tell users to start a new session for guaranteed detection.

Repository Update and Uninstall (Iteration 4)

Iteration 4 adds CLI-first update and whole-repository uninstall. Do not add TUI repository actions in this iteration.

Update commands:

• skill-manager update [<git-url>] [--dry-run]
• Without a URL, update every repository recorded in Skill Manager state in deterministic host/repo-path order.
• With a URL, normalize HTTPS/SSH forms and update the matching recorded repository only.
• Stop on the first failure and keep earlier successful repository updates reflected in state.

Update safety:

• Require the managed checkout, matching origin, a normal current branch tracking origin/*, no local-only commits or divergence, and no tracked, untracked, or ignored worktree changes.
• Checkout blockers are classified (Iteration 21). A dirty worktree is repairable through repair; every other blocker is explained and left for the user.
• Audit every recorded active/disabled skill symlink and reject missing, changed, duplicate, or extra managed-directory references into the checkout.
• Fetch origin, require a fast-forward, and verify each installed relative skill path still contains a regular SKILL.md in the target commit before merging.
• Do not auto-install newly discovered skills. Do not move or rewrite existing active/disabled symlinks during update. Iteration 22 reports them instead: after a successful update, and in dry-run from the local checkout, list skills whose names are not recorded and print the exact install --skill command.
• Persist the successful target commit as lastSeenCommit.
• Update dry-run must not fetch or change remote-tracking refs, checkout files, symlinks, or state. It must state that exact remote preflight is unavailable until real update.

Uninstall commands and safety:

• skill-manager uninstall <git-url> [--dry-run] removes the entire recorded repository installation. An explicit URL is always required. Iteration 27 adds --skill <name>... to remove only some recorded skills; see that section.
• Remove only exact validated active/disabled skill symlinks owned by the repository, the matching disabled records, the repository manifest entry, and the managed checkout.
• Require a clean checkout with a recoverable origin/* upstream and no local-only commits. Block on missing/changed expected symlinks or extra managed-directory symlinks into the checkout.
• An unrelated blocker at the original path of an OFF skill is not owned by Skill Manager and must be left untouched.
• Stage symlinks and checkout under ~/.skill-manager/trash/, save state, then delete staging. Roll back paths when a failure happens before state save; report any post-save cleanup residue explicitly.
• Do not add --force, uninstall-all, checkout archival, or a separate repo remove command. Whole-repository uninstall supersedes repo remove.
• Update and uninstall dry-runs must not mutate checkout, symlinks, Git refs, or state.json.
• Already running Claude/Codex/Muse/Grok sessions may retain old skill visibility; recommend a new session after update or uninstall.

Local Path Install and Uninstall (Iteration 5)

Iteration 5 adds CLI-first link-in-place installation from local folders. Do not add TUI source-management actions in this iteration.

Local install commands and discovery:

• skill-manager install <local-path> [--tool claude|codex|muse|grok|both|all] [--skill name[=path]...] [--as name=install-name...] [--dry-run]
• Accept absolute paths, explicit relative paths (./ and ../), ~/ paths resolved from $HOME, and bare relative paths only when they currently exist.
• Resolve the source to a canonical absolute directory path. A root containing a regular, non-symlinked SKILL.md is exactly one skill; otherwise recursively discover skills with the existing ignored-directory rules and the shared duplicate-group resolution (Iteration 25).
• Use link-in-place symlinks directly to skill directories. Never copy, move, edit, update, or delete the local source.
• Reuse Git install tool targeting, skill selection, all-or-nothing preflight, idempotency, blocker handling, apply rollback, and strict dry-run semantics.
• Reject local roots that overlap in either direction with Skill Manager state, Claude/Codex/Muse/Grok user skill paths, disabled paths, Codex system skills, or Claude plugin cache paths.
• Use source label local path and the canonical source root basename as Group.
• Treat canonical source path as identity. Reinstalling the same source may add newly discovered skills, but existing recorded ownership drift blocks the operation.
• A tool/install-name cell may be owned by only one Skill Manager Git or local source. An exact matching unmanaged symlink may be adopted.

Local uninstall and update behavior:

• skill-manager uninstall <local-path> [--dry-run] removes the whole recorded local installation: exact validated active/disabled links, matching disabled records, and the local-source state entry.
• Never stage or remove the source directory. An unrelated blocker at an OFF skill's active path remains untouched.
• Permit uninstall after the source is missing by validating stored relative targets against exact active/disabled symlink text. Reject changed expected links and extra managed-directory symlinks into the recorded source root.
• Stage owned links under ~/.skill-manager/trash/, save state, then delete staging. Roll back before-save failures and retain/report recovery data after incomplete rollback.
• Update-all processes only Git repositories. skill-manager update <local-path> reports that link-in-place sources are live and do not require update.
• repos remains a Git repository summary. Do not add a local-source summary command in this iteration.
• Already running Claude/Codex/Muse/Grok sessions may retain old skill visibility; recommend a new session after local install or uninstall.

State Location

Use a global state directory:

~/.skill-manager/
  state.json
  skill-sets.json
  favorites.json
  advisor-settings.json
  backups/
  disabled/
    claude/
      <skill-name>
    codex/
      <skill-name>
    muse/
      <skill-name>
    grok/
      <skill-name>
  repos/
    <host>/
      <owner-or-path>/
        <repo>
  trash/
    uninstall-<operation-id>/

state.json stores enough information to restore disabled entries:

• tool: claude, codex, muse, or grok
• skill name
• original path
• disabled path
• entry type: symlink or dir
• symlink target, if any
• source label
• group label
• timestamp

state.json also stores repository installation metadata for Skill Manager managed installs:

• original URL
• normalized host and repo path
• checkout path
• group label
• installed skills with name, optional install name (installedAs, Iteration 26), relative path, and tools
• install timestamp
• last seen commit, if available

Manifest version 2 also stores local-source installation metadata:

• original normalized absolute input path
• canonical absolute source path
• group label
• installed skills with name, optional install name (installedAs), relative path, and tools
• install timestamp

Version 1 manifests migrate in memory with no local sources and are written as version 2 on the next mutation. Manifest version 3 (Iteration 26) adds the optional installedAs field to installed skills; version 1 and 2 manifests migrate in memory and are written as version 3 on the next mutation. Reject unknown newer manifest versions, so binaries older than Iteration 26 refuse a version 3 manifest (state backups cover rollback).

If state.json is missing, later versions may recover from disabled/, but MVP does not need full disaster recovery.

File Operations

Disable operation:

1. Validate original entry exists.
2. Validate destination under ~/.skill-manager/disabled/<tool>/ is free.
3. Move the entry with rename.
4. Update state.json.
5. Rescan.

Enable operation:

1. Validate disabled entry exists.
2. Validate original target path is free.
3. Move the entry back with rename.
4. Update state.json.
5. Rescan.

For symlinks, moving the symlink itself is correct. Do not dereference it.

Before the first apply in a process, write a backup copy of the current state manifest to ~/.skill-manager/backups/state-<timestamp>.json if the manifest exists.

Install operation:

1. Normalize and validate the Git URL.
2. Resolve the managed checkout path under ~/.skill-manager/repos.
3. For non-dry-run install, clone missing checkouts or reuse matching existing checkouts without pulling.
4. Discover valid skills from the checkout.
5. Apply optional --skill selection and fail if any requested skill is missing.
6. Preflight all selected skill/tool targets for conflicts and idempotent already-installed cases. Install as OFF also requires each disabled path to be free.
7. Create missing symlinks at the active path, or at the disabled path for Install as OFF.
8. If symlink creation or the state save fails, remove only symlinks created by this install operation.
9. Update the install manifest, and the disabled records of links created OFF, in one state.json save after successful symlink creation.
10. Rescan.

Local install follows the same discovery/preflight/link/state sequence without a clone step. Local uninstall stages only exact owned symlinks; it never stages or deletes its source directory.

Conflicts

If restore would overwrite an existing file, directory, or symlink, block the restore.

Do not auto-overwrite. Do not auto-merge. Do not auto-delete.

The TUI should show CONFLICT for the affected cell and details should explain:

• Original path
• Disabled path
• Existing blocker path
• Suggested manual resolution

Conflict resolution actions are out of scope for MVP.

Batch Apply

The TUI uses pending changes.

Space creates or removes a pending toggle. Changes are not applied immediately.

Apply order must be deterministic:

1. Disable operations first
2. Enable operations second
3. Within each group, sort by tool, then skill name

If a batch operation fails, stop the batch, keep already completed operations reflected in state, and show the error. Full transactional rollback is out of scope for MVP.

TUI Decisions

Build the TUI in Go using Bubble Tea.

The main view is one row per skill, with separate Claude, Codex, Muse, and Grok state columns.

Example:

Skill                                      Claude  Codex  Muse  Grok  Group
release-checklist                          ON      ON     ON    ON    example-labs/engineering-skills
catalog-search                             -       ON     -     -     Skills CLI
local-only-skill                           ON      -      -     -     local
imagegen                                   RO      RO     -     -     Codex system
codex-cli-runtime                          RO      -      -     -     Claude plugin

Default view:

• Show only toggleable skills from ~/.claude/skills, ~/.agents/skills, the Muse user skills directory, and ~/.grok/skills.
• Hide read-only skills by default.

Read-only view:

• Show or hide with a key such as o.
• Show Codex system skills and Claude plugin skills.

Expected controls:

• Tab: switch active tool column between Claude, Codex, Muse, and Grok
• Space: toggle pending state for the active cell
• b: toggle all tool cells in the row where possible
• g: smart-toggle the selected row's group for all tools
• A: smart-toggle all visible toggleable rows for all tools
• G: cycle group filter
• a or Enter: apply pending changes
• u: undo pending change for active cell
• U: clear all pending changes
• /: text filter
• s: source filter
• o: show/hide read-only entries
• d: details panel
• r: rescan from disk
• q: quit, warning if pending changes exist

The UI language is English.

Details panel is read-only in MVP and should show:

• Skill name
• Description from SKILL.md, if easy to parse
• Group label
• Claude active path and state
• Codex active path and state
• Disabled path, if off
• Entry type
• Symlink target, if any
• Source label
• Repo origin and commit, if detectable
• Conflict details, if any

Group and Bulk Toggle Semantics

Group and all-visible toggles must use the same pending-change safety model as single-cell toggles. They must never apply immediately.

Keys:

• g: smart-toggle every toggleable cell in the selected row's group, across Claude, Codex, Muse, and Grok.
• A: smart-toggle every visible toggleable cell across Claude, Codex, Muse, and Grok.
• G: cycle group filter for the current table.

Scope:

• g uses all currently loaded rows that belong to the selected row's group, not only rows currently visible after text/source/group filters. If a group filter is active, this is naturally the same visible group.
• A acts on the current visible rows after text/source/group/read-only filters.
• Read-only cells are always skipped.
• Missing cells with no disabled restore state are skipped.
• One-sided skills are valid: local-only-skill toggles only Claude, while catalog-search and decision-review toggle only Codex.
• Conflicts are skipped and reported in the status message.

Smart-toggle target:

• If every toggleable, non-conflict cell in the scope is effectively ON, add pending disables for the scope.
• Otherwise, add pending enables for cells that are OFF.
• For mixed scopes, do not create missing entries for tools where a skill never existed.

Pending merge behavior:

• If a cell already has the same pending operation, batch toggle removes that pending operation.
• If a cell has the opposite pending operation, batch toggle replaces it.
• If every applicable cell already has the same pending operation, the batch toggle acts as batch undo and removes those pending operations.

Status messages must report how many pending changes were updated and how many cells were skipped for read-only/missing/conflict reasons.

CLI Decisions

The binary name is skill-manager.

Minimal commands:

skill-manager tui
skill-manager list
skill-manager status
skill-manager groups
skill-manager disable --tool claude release-checklist
skill-manager enable --tool codex catalog-search
skill-manager disable --tool claude release-checklist --dry-run

go run . should launch the TUI by default or behave the same as skill-manager tui.

--dry-run support is required for CLI mutating commands. It prints the planned filesystem operations without moving anything.

skill-manager groups is a read-only command that summarizes group labels, row counts, sources, and Claude/Codex/Muse/Grok state counts. Do not add mutating group/all CLI commands in Iteration 2.

Iteration 3 repository install commands:

skill-manager install <git-url> [--tool claude|codex|muse|grok|both|all] [--skill name[=path]...] [--as name=install-name...] [--dry-run]
skill-manager repos

skill-manager install installs skills from a Git repository using managed checkouts and symlinks. --tool defaults to all supported tools. --skill may be repeated. --off creates new links disabled (Iteration 23). --dry-run is strict and does not clone missing repositories.

skill-manager repos is read-only and summarizes repositories recorded in Skill Manager state, including group, URL, checkout path, last seen commit, installed skill count, and tools.

Iteration 4 repository management commands:

skill-manager update [<git-url>] [--dry-run]
skill-manager uninstall <git-url> [--dry-run]

update without a URL updates all managed repositories. uninstall always requires an explicit URL and removes the full recorded repository installation and checkout, unless --skill (Iteration 27) selects only some recorded skills. Both commands use the strict safety and dry-run rules above.

Iteration 5 local path commands:

skill-manager install <local-path> [--tool claude|codex|muse|grok|both|all] [--skill name[=path]...] [--as name=install-name...] [--dry-run]
skill-manager uninstall <local-path> [--dry-run]

Local installs are live symlinks and are not included in repository update or repos output.

Extend managed sources (Iteration 19):

skill-manager extend --tool <tool> [--dry-run]

extend links every recorded Git and local source to one more tool without reinstalling each source. The tool is a parameter (claude, codex, muse, or grok); no step hardcodes a tool name. Selection reuses the install discovery and preflight rules per source with a cross-source claim map keyed by tool and install name, so sources that install one skill name under different install names extend together. Apply walks sources in manifest order (Git, then local), mirrors OFF state for skills that are OFF for every other recorded tool, and stops at the first failure with an extend --tool <tool> failed for source <group> error, keeping the completed prefix in state. --dry-run is strict and never clones, links, or writes state.json.

Repair a blocked managed checkout (Iteration 21):

skill-manager repair <git-url> [--dry-run]

repair always requires an explicit Git URL. There is no --all, no --force, and no interactive prompt; --dry-run is the preview and must not move a file or change a Git ref. Output lists the offending checkout-relative paths grouped as tracked, untracked, and ignored. update explains a classified conflict on failure and prints the exact repair command when the blocker is repairable.

Build and Distribution

MVP is local-only:

go run .
go build -o bin/skill-manager .
make dev

Use make dev after code changes to rebuild the persistent global command at ~/.local/bin/skill-manager.

Do not add Homebrew, installer, auto-update, or release packaging in the first iteration.

macOS GUI (Iteration 6)

Iteration 6 adds a local Apple Silicon desktop app while preserving the CLI and TUI contracts above.

• Use Wails 2.14 in a nested desktop Go module and call the existing Go backend in-process. Do not duplicate filesystem mutation logic in JavaScript or another backend language.
• Use React, TypeScript, Vite, npm, generated Wails bindings, and plain CSS custom properties. Keep exact dependency resolution in package-lock.json.
• The GUI contains Dashboard and Skills. Git/local install, update, and uninstall remain CLI-only in this iteration.
• The GUI uses the same pending, smart-toggle, conflict, deterministic apply, backup, and partial-failure semantics as the TUI. Pending state is process local and closing with pending changes must warn.
• Frontend calls identify skills and tools only. They must never accept or send arbitrary filesystem paths or prebuilt move operations.
• Scan on app launch, after an app-owned Apply, and on explicit Refresh. Do not add a watcher or polling loop.
• The visual source of truth is the validated root DESIGN.md, maintained from the implemented interface and repository-owned screenshots under docs/images/. The first GUI is dark-only.
• Build a local ad-hoc signed darwin/arm64 .app. Developer ID signing, notarization, light theme, universal binaries, publishing, telemetry, and auto-update are out of scope. Wails' ad-hoc signature is retained because it is required for reliable launch on supported macOS releases.

GUI Source Management (Iteration 8)

Iteration 8 adds source lifecycle actions to the existing macOS app while preserving the CLI contracts and the ownership/safety rules above.

• Add a Sources screen containing only Git repositories and local sources recorded in Skill Manager state. Unmanaged groups remain visible in Skills and are not presented as owned sources.
• Install uses an explicit inspect, review, and apply flow. Git inspection may clone a missing managed checkout; cancelling after that point retains the clean unrecorded checkout for a cheaper retry. Local sources are selected through the native macOS directory picker.
• The install dialog has one Install as OFF switch for the whole selection (Iteration 23). Review records the mode and apply always uses the reviewed mode.
• Installation selection is a per-skill Claude/Codex/Muse/Grok matrix. Extend the shared domain planner to accept exact cells while preserving the existing CLI --tool and --skill expansion semantics.
• Each install-matrix tool column has one explicit bulk-selection toggle. It reports ON, OFF, MIXED, or N/A; ON clears every non-conflict target in that column, while OFF or MIXED selects all of them. Its scope is every discovered skill, including rows hidden by the text filter. Since Iteration 25, cells waiting for a duplicate-copy choice are skipped like conflicts until a copy is chosen. This changes only the install selection and never toggles visibility of an installed skill.
• Update is available per Git repository and for all recorded repositories. Local link-in-place sources remain live and do not require update.
• The Sources table labels this distinction as Update mode: Managed Git with Use Update to fetch changes., or Linked folder with Changes are read directly; no update needed. Do not use ambiguous standalone states such as Ready and Live for this distinction.
• A healthy Git source with skills not yet recorded (Iteration 22) shows the new skill count and names in the Update mode cell and an Install new action that opens the install matrix with only those skills preselected.
• Uninstall removes a whole recorded source and requires typing its group name in the confirmation dialog. Git uninstall removes the managed checkout; local uninstall always preserves the user-owned source directory. Iteration 27 adds a separate Remove skills action for some recorded skills of a source.
• Extend to tool links every recorded source to one tool radio after a per-source link preview that surfaces blocked and skipped sources with their conflicts. Confirm stays disabled while any source is blocked or no new links are planned; apply stops at the first failure and reports it with a fresh snapshot like every other source mutation.
• Source actions are immediate, separately confirmed operations. They are blocked while Skills toggles are pending, and no other mutation or app close is allowed while a source operation is active.
• Frontend mutation calls use opaque draft/review/source identifiers plus skill and tool names. They never accept filesystem paths or prebuilt operations, except the Iteration 25 duplicate-copy choice, which is a selection from the draft's own options and is revalidated against fresh discovery. A Git URL is the only raw source locator accepted from the frontend.
• Long source operations expose phase progress but are not cancellable in this iteration. Keep the existing rollback and cleanup reporting semantics.
• The Discover mode backed by skills.sh is delivered separately in Iteration 9. It does not change the managed-only scope of this screen.

skills.sh Discover (Iteration 9)

Iteration 9 adds an experimental, anonymous catalog integration to the macOS app. It does not replace the established CLI/TUI source-management contracts.

• Add a top-level Discover screen with all-time, trending, and hot rankings, debounced search, progressive loading, details, and compact activity history.
• Isolate the observed anonymous skills.sh JSON endpoints behind one Go adapter. Do not use OIDC, scrape HTML, or silently switch to scraped responses.
• Cache normalized ranking/search pages and parsed detail metadata under ~/.skill-manager/cache/skills-sh/catalog-v1.json. Cached data may be browsed offline, but raw downloaded skill files must not be cached.
• Installation always requires a fresh live detail response and a distinct safety confirmation. Explain that third-party skill instructions may be unsafe and should be reviewed before use.
• Install exactly one selected GitHub-hosted skill for the selected Claude and/or Codex cells. Reuse the existing managed checkout, ownership, exact-cell planner, preflight, apply, backup, rollback, progress, and rescan machinery.
• Frontend mutation calls use only catalog session identifiers, skill identifiers, and tool names. They must not send repository URLs, skill paths, checkout paths, or prebuilt filesystem operations.
• Project every catalog entry against live local state as available, installed-on, installed-off, or conflict per tool. Individual-skill uninstall remains out of scope; installed entries link back to Skills.
• Catalog entries from well-known/non-GitHub sources remain visible and external-linkable but cannot be installed in this iteration.
• Catalog network failures do not block Dashboard, Skills, Sources, or local mutations. Offline cache state must be explicit and installation must remain disabled until live revalidation succeeds.
• Do not add telemetry, ratings, comments, publishing, or automatic background polling.

Active-First Skills Workspace (Iteration 10)

Iteration 10 restructures only the macOS Skills screen for large catalogs where most managed skills remain OFF until a specific task needs them. CLI, TUI, filesystem, state, and Apply semantics remain unchanged.

• Show Needs attention first when conflicts exist, then an always-expanded Active now section, followed by OFF skills in collapsed Available by source group accordions. Show read-only skills in their own grouped section only after explicit opt-in. A skill appears in exactly one section.
• Determine section placement from applied state. A pending enable or disable remains in its current section and shows its transition until successful Apply/rescan.
• Keep global search plus All / Active / Available and All tools / Claude / Codex / Muse / Grok chips visible. Move Group, Source, and Read only controls into an advanced Filters disclosure.
• Keep all tool columns visible. A selected tool chip changes classification and limits row, group, and filtered-result smart-toggle actions to that tool.
• The global action covers every filtered result, including rows inside collapsed groups. A group-header action covers the complete loaded group, independent of search and filters. Both report eligible cell counts and use the existing pending-change safety model.
• Search temporarily expands matching groups and restores the session's manual expansion state when cleared. Manual group expansion survives navigation during the current app process but is not persisted across restarts.
• Remove the repeated Group column and per-row group action. Active rows retain a compact group/source badge; available groups own their bulk action.
• Expose scoped Wails methods using only skill/group and tool identifiers. Go validates the scope and reuses staging.ToggleBatch; frontend code never submits paths or prebuilt operations.

Public Source Distribution (Iteration 11)

Iteration 11 prepares the source tree for a public GitHub repository without changing runtime skill-management semantics.

• Use Go modules under github.com/dees91/agent-skill-manager and bundle identifiers under io.github.dees91.skillmanager.
• Publish under MIT with practical security, privacy, and contribution docs.
• Keep public examples, test fixtures, screenshots, plans, and wiki synthesis free of real home inventories, private paths, machine fingerprints, and credentials. The current rules live in Public Text.
• Build the ignored frontend dist before compiling the embedded desktop module so a clean checkout is sufficient.
• GitHub Actions remain out of scope for this iteration.
• Keep the public repository source-only for Apple Silicon macOS. Universal binaries, notarization, release automation, configurable provider paths, and supported non-macOS behavior remain deferred.

GitHub Binary Distribution (Iteration 12)

Iteration 12 adds manually published GitHub Release artifacts without changing runtime skill-management semantics.

• Build and verify releases locally. Do not add GitHub Actions or automatic publishing in this iteration.
• Publish v0.4.0 as a prerelease in the private dees91/agent-skill-manager repository.
• Package the ad-hoc-signed Apple Silicon macOS app as ZIP and the darwin/arm64 CLI as tar.gz; publish one SHA-256 manifest for both.
• The CLI exposes skill-manager version and skill-manager --version. Release builds embed the release version; development builds report dev unless tagged Go module build information supplies a version.
• The packaging entry point validates a clean checkout, version consistency, tests, vet, frontend checks, build output, signatures, architecture, archive contents, and checksums before leaving ignored artifacts under dist/release/.
• Keep versioned release notes in the repository. README and release notes must disclose Apple Silicon/macOS 13+ support, ad-hoc signing, lack of notarization, and the expected Gatekeeper approval flow.
• Developer ID signing, notarization, DMG packaging, universal binaries, GitHub Actions, automatic publishing, and auto-update remain out of scope.
• Never restore or commit scripts/public-check.sh; release packaging uses the dedicated scripts/package-release.sh workflow.

Public Preview Hardening (Iteration 13)

Iteration 13 replaces the private v0.4.0 prerelease with a public v0.4.1 preview and tightens local privacy, distribution notices, and repository operations without changing skill ownership semantics.

• The public desktop build exposes Dashboard, Skills, and Sources. Keep the experimental skills.sh adapter/domain code tested in the repository, but do not bind or render Discover in v0.4.1.
• Startup and ordinary refresh use filesystem context estimates only. Provider diagnostics run only from an explicit user action and only through the fixed read-only allowlist: two codex debug prompt-input variants and claude plugin list --json.
• Diagnostic subprocesses receive the current home plus only a minimal path/temp/locale/terminal environment. Do not forward credentials, provider config overrides, tokens, or proxy variables.
• Use owner-only permissions for Skill Manager state directories (0700) and state/cache JSON files (0600) without rewriting managed checkout file modes. Retain at most 10 state backups and at most 30 days.
• Do not persist skills.sh search terms or results. On the next desktop launch, sanitize legacy cache version 1 into version 2 while retaining non-query ranking/detail metadata.
• Generate THIRD_PARTY_NOTICES.txt from exact locked Go/runtime/frontend production dependencies. Package it with both binary artifacts and include the project license plus notices inside the desktop app resources.
• Build and publish v0.4.1 manually from a clean local Apple Silicon macOS checkout. CI, Dependabot, issue/PR templates, private vulnerability reporting, and branch rules are repository operations completed after the source becomes public; release automation remains deferred.
• Treat v0.4.1 as a preview. Developer ID signing, notarization, universal binaries, SBOM/provenance, auto-update, and commercialization review remain required follow-up before a stable or commercial release.

Saved Skill Sets (Iteration 14)

Iteration 14 adds reusable, task-oriented recipes to the macOS app without changing CLI, TUI, source ownership, or filesystem toggle semantics.

• A Skill Set has a stable opaque identifier, a unique user-facing name, an optional When to use description, and a sorted unique list of skill basenames. It is distinct from the automatically detected source Group.
• Membership is tool-agnostic. Each use explicitly selects one or more of Claude, Codex, Muse, and Grok, in any combination (All selects or clears every tool), and stages changes through the existing Pending/Apply workflow.
• A set uses the existing smart-toggle rule: all eligible effective cells ON targets OFF; otherwise eligible OFF cells target ON. Sets may overlap and do not own or reference-count active skills.
• Persist sets separately in ~/.skill-manager/skill-sets.json; do not advance the ownership/toggle manifest from version 2. The file contains no source or filesystem paths and uses private atomic persistence plus bounded backups.
• Missing members remain in the set as unavailable. Reinstalling the same skill basename reconnects it, regardless of source. Source uninstall warns about affected sets but neither blocks nor rewrites them.
• Add a dedicated Skill Sets screen, Save as Skill Set from Pending, and Add to Skill Set from skill details. Creating, editing, and deleting set metadata is immediate and must not change skill state or existing Pending.
• Frontend mutations use set IDs, names, descriptions, skill names, and tool names only. They never accept or send filesystem paths or prebuilt toggle operations.
• Automatic history suggestions, active-set reference counting, project-local sets, import/export, per-skill notes, workflow steps, and CLI/TUI surfaces remain out of scope.

First-Party Skill Advisor (Iteration 15)

Iteration 15 adds a public first-party Agent Skill and a CLI-only temporary activation API without changing TUI, desktop, source ownership, or core toggle semantics.

• Keep the standard skill at skills/skill-advisor in this repository. It is optional and is installed through the existing Git/local install command; do not embed or auto-install it and do not depend on a private skill source.
• list --json exposes path-free apiVersion: 1 inventory data: skill name, description, group, source, and explicit Claude/Codex/Muse/Grok state plus toggleable status. --available-for claude|codex|muse|grok and repeated case-insensitive --query filters provide a bounded candidate view without external JSON tooling. Human list output remains unchanged.
• Add advisor activate --tool claude|codex|muse|grok --skill <name>..., advisor cleanup --receipt <id>, and advisor status. Mutating advisor commands support strict dry-run and all advisor commands support structured JSON.
• A state.json manifest newer than the binary supports yields advisor JSON error code STATE_VERSION_UNSUPPORTED with a path-free update hint instead of a generic command failure, so the skill can ask the user to update.
• One activation accepts 1-5 unique skill names for exactly one tool and fully preflights the requested cells. The binary never selects skills itself; the first-party skill chooses the smallest clearly relevant set.
• The first-party skill uses bounded metadata queries that retain both ON and OFF cells for the current host. It reports the selected already-active and needs-activation skills separately, selects at most five across both groups, and passes all selected toggleable cells through the activation API so baseline ON cells remain unowned while existing leases can be shared.
• Persist opaque receipts and reference-counted leases separately in ~/.skill-manager/advisor-activations.json. Keep state.json at version 2, serialize advisor access through ~/.skill-manager/advisor.lock, use atomic owner-only writes and bounded backups, and never store prompt/task content.
• A cell that was ON before advisor activation is never owned or disabled by a receipt. Multiple receipts may share a lease; only cleanup of the final claim restores the original OFF state.
• Cleanup must validate the exact tool/name, active/disabled paths, entry type, and symlink target before mutation. Drift or conflict preserves the receipt and blocks cleanup rather than touching an unexpected entry.
• The skill directly reads each selected SKILL.md, whether already ON or newly activated, before continuing, so same-turn use does not depend on provider catalog-refresh timing.
• A receipt returned to the first-party skill is a temporary resource owned by that invocation. The agent must clean that exact receipt before every normal final response, including successful, blocked, and abandoned task exits while it retains control. Successful cleanup is not delegated to the user. Cleanup failure preserves and reports the receipt plus the exact recovery command.
• Never automatically clean a receipt not returned by the current invocation or infer staleness from age. Do not add automatic expiry, hooks, plugins, or a GUI cleanup surface in this iteration. Iteration 28 adds the desktop surface.

Skill Favorites (Iteration 16)

Iteration 16 adds private, tool-agnostic favorites to the macOS Skills workspace without changing CLI, TUI, list JSON, Skill Advisor, source ownership, or filesystem toggle semantics.

• A favorite is identified by skill basename and applies across Claude and Codex. Managed user rows remain eligible while ON, OFF, or conflicted; read-only-only system and plugin rows are excluded.
• Persist sorted unique basenames separately in ~/.skill-manager/favorites.json; do not advance the ownership/toggle manifest from version 2. Use private atomic persistence and bounded backups.
• Missing favorites remain recorded and reconnect when the same basename is installed again. Source uninstall reports affected names but does not block, prune, or rewrite favorite metadata.
• Add accessible stars to Skills rows and details, a mutually exclusive Favorites availability chip, and favorite-first ordering. Favorites keep the active-first section placement and existing Pending/Apply behavior.
• Frontend mutations send only a skill name and desired boolean state. A corrupt favorites file disables favorite controls and shows a page-local warning without blocking normal scans, toggles, Apply, or source lifecycle.
• Separate Favorites navigation, folders/tags, notes, synchronization, project-local favorites, CLI/TUI controls, and advisor recommendations remain out of scope.

Native Desktop About (Iteration 17)

Iteration 17 adds version visibility through the standard macOS application menu without changing frontend state, CLI/TUI behavior, or filesystem semantics.

• Add Skill Manager → About Skill Manager through Wails' native macOS About support. Do not add a custom React dialog or repeat the version in the app workspace.
• Show the existing application icon, product name, current version, and short product description.
• Read the displayed product name, version, and description from the embedded desktop/wails.json metadata so the About dialog and generated app bundle use the same source of truth.
• Reject missing or malformed embedded About metadata instead of displaying a stale or fabricated version.
• Keep Wails bindings, provider APIs, application state, CLI/TUI behavior, and release/install workflows unchanged.

Ranked Skill Advisor Search (Iteration 18)

Iteration 18 replaces the first-party Skill Advisor's substring candidate lookup with an additive CLI-only ranked retrieval surface. Existing list --json --query behavior remains unchanged.

• Add skill-manager advisor search --tool claude|codex|muse|grok --query <text> [--limit <n>] [--json]. Require exactly one tool and one bounded query; default the result limit to 20 and accept values from 1 through 50.
• Search only toggleable ON and OFF cells for the requested tool. Continue to return path-free name, description, group, source, and explicit Claude/Codex/Muse/Grok state metadata in ranked order.
• Rank locally and deterministically with weighted BM25F over name, description, group, and source plus bounded token-level fuzzy matching and phrase bonuses. Do not add a model, network call, persisted index, cache, or third-party search dependency.
• Keep numeric scores, match explanations, filesystem paths, and raw query text out of the public response. Break equal internal scores by skill name.
• Keep advisor apiVersion: 1 and advertise the additive ranked_search_v1 capability through advisor status --json. A new first-party skill requires that capability and does not silently fall back to substring filtering when used with an older CLI.
• The first-party skill derives one concise search sentence from the task, retries once with broader terms when needed, and retains the existing metadata distrust, five-skill selection bound, activation, instruction-load, and exact-receipt cleanup rules.
• Keep TUI, desktop, toggle state, receipt persistence, install/source ownership, and existing human/list interfaces unchanged.

Managed Checkout Diagnosis and Repair (Iteration 21)

Iteration 21 turns opaque checkout conflicts into named diagnoses and adds one confirmed repair for the only repairable class.

• Every checkout blocker carries a stable kind alongside its unchanged message: symlink, not-directory, not-a-checkout, nested-checkout, identity, origin-missing, origin-mismatch, dirty-worktree, detached-head, no-upstream, foreign-upstream, unresolved-ref, and diverged.
• Only dirty-worktree is repairable. Detached HEAD, missing or foreign upstream, origin mismatch, divergence, and managed reference drift are explained with manual guidance and are never repaired automatically.
• Repair moves every offending checkout-relative path into ~/.skill-manager/trash/repair-* with rename, restores tracked paths from HEAD, unstages index-only paths, verifies the checkout, prunes directories left empty, then deletes the staging copy. Staging exists for rollback; the staged copies do not survive a successful repair.
• Do not add git clean, reset --hard, forced checkouts, or in-place deletion. Repair never writes state.json, moves symlinks, or changes remote refs, and it never leaves the managed checkout root.
• Repair requires the same ownership audit as update and uninstall, and re-runs it after restoring the checkout, before any recovery data is deleted. It refuses to stage a recorded skill directory, an ancestor of one, or an installed SKILL.md that HEAD does not hold as a regular file. A stray file inside a skill directory is repairable.
• Branch, upstream, and ancestry blockers are rejected before any mutation, even when the worktree is dirty. A dirty checkout that also has local-only commits or a detached HEAD is refused, never partially repaired.
• Repair snapshots the Git index before mutating and restores it on rollback, because restoring tracked paths rewrites the index as well as the worktree. Rollback also deletes paths repair recreated from HEAD at locations that were absent beforehand, and prunes directories that recreation added, so the worktree returns to its exact pre-operation shape. If the worktree, the recreated paths, or the index cannot be restored, recovery data is kept and the error names which restoration failed.
• Worktree enumeration uses git status --porcelain=v2 -z. Version 1 records may start with the space of an X status code, which the trimming Git runner removes, making it indistinguishable from a filename that begins with a space. Path bytes are preserved exactly apart from the documented directory suffix.
• Repair is idempotent. A clean, fast-forwardable checkout succeeds without mutating anything.
• A managed checkout whose installed SKILL.md was deleted locally stays blocked by the shared ownership audit; that pre-existing limitation is unchanged by this iteration.
• The desktop app surfaces the diagnosis twice: a Needs repair state in the Sources table and a cause plus Repair action in the dialog after a failed update. Source health is an explicit read-only inspection, never part of the shared snapshot reload, because enumerating ignored worktree content across every checkout is too expensive for routine refreshes.
• Repair is a separately confirmed source operation in the existing exclusive source lane. It is blocked while Skills toggles are pending. The repair confirmation lists paths and needs no typed group name, because it removes generated files rather than an installation.
• Repair previews report checkout-relative paths only. No absolute filesystem path crosses the desktop bridge.

New Skill Discovery for Managed Sources (Iteration 22)

Iteration 22 makes skills that a managed Git repository gained after installation visible. It does not change the rule that update never installs.

• A new skill is a skill discovered in the managed checkout whose name is not recorded in the repository's installedSkills. Matching is by name, so a recorded skill that moved to another path is not reported.
• There is no dismiss or ignore list and no new state. A skill stops being new only when it is installed.
• update lists new skills per repository after a successful update and prints skill-manager install <url> --skill <name>... with every argument shell-quoted. It prints one command per recorded tool with --tool <tool> unless the repository uses every tool. Skill names come from upstream directory names, so a name with control characters is shown quoted and the command is omitted. A discovery failure is a warning in the CLI and the GUI and does not fail the update.
• update --dry-run lists new skills already in the local checkout and still does not fetch.
• GUI source health carries newSkills for ok sources. The Sources row shows them with an Install new action that reuses the Git install flow on the recorded URL (reusing the checkout without pulling) and preselects new skills for the tools the source already uses, never conflict or already-installed cells. Since Iteration 25, unrecorded names whose copies differ are reported as ambiguous new skills and resolved through the install-matrix copy picker. Update result messages mention how many new skills are available and how many sources could not be checked. A healthy source whose check failed shows the path-free cause instead of new skills.
• Toggle, uninstall, extend, and repair semantics do not change.

Install as OFF (Iteration 23)

Iteration 23 lets an install add skills without making them visible to any tool until the user turns them ON.

• skill-manager install <git-url|local-path> [--tool …] [--skill …] --off and one desktop Install as OFF switch in both the Install source and Install new flows. The switch applies to every selected cell; there is no per-cell mode.
• New links are created directly at ~/.skill-manager/disabled/<tool>/<skill> in a private (0700) directory. A skill installed OFF never appears in a tool's active skills directory, even briefly. Do not create it ON and then disable it.
• Each link created OFF gets the disabled record a manual disable of the same active link would write: originalPath is the active path, entryType is symlink, symlinkTarget is the skill path, and source and group come from the scanner's managed classifier (local source, Git origin, or Skills CLI lock). The source manifest and every disabled record are written in one state save.
• Cells already ON stay ON; --off never disables anything and says so. Cells already OFF stay OFF.
• Install as OFF adds one conflict: the disabled path already exists. Every existing install conflict still applies, including a free active path.
• A failed install state save removes every link that install created, ON or OFF, for Git and local sources.
• The Iteration 22 update hint keeps the default ON install. Discover install, extend, the TUI, toggle, update, uninstall, and repair semantics do not change.

Optional TypeSafe Advisor (Iteration 24)

The implementation plan is planning/phase-24-typesafe-advisor-tasks.md.

• Keep local BM25F search as the default and preserve advisor search as offline.
• advisor recommend is a separate recommendation operation with optional user-owned TypeSafe credentials, explicit cloud opt-in, direct Go-to-provider HTTPS, and visible local fallback. A stored/environment key alone never enables cloud use.
• Limit cloud inputs to the supplied task brief plus names and bounded descriptions of every toggleable skill of the selected host, sent in as many parallel chunk requests as the token budget requires (never dropping skills; at most 16 chunks). Request bound 256 KiB; request count is chunks + 1. No transcript/project-code/full-instruction upload is in this iteration.
• Store keys in the OS credential store, with an environment-only CLI option; never bundle a maintainer key or add a Skill Manager-operated backend.
• Recommendation is read-only. The agent owns final selection and the existing activation, same-turn instruction reads, receipts, and cleanup.
• Deliver the complete feature in one agent run under one implementation task. Include synthetic quality fixtures and optional live measurement; missing API credentials do not block implementation or offline validation. Read the plan for acceptance criteria and genuine re-plan conditions.

Duplicate Skill-Name Resolution (Iteration 25)

Iteration 25 replaces the duplicate-basename install blockade with grouped resolution. One repository may ship the same skill name from several directories (multi-harness fan-out, generated copies, test fixtures); that alone no longer fails discovery, inspection, update checks, or extend.

• Discovery groups skills by basename. A name found at exactly one path behaves as before. A name found at two or more paths becomes a duplicate group with every copy ranked canonically: test/example copies last, then hidden directories after visible ones, then deeper paths after shallower ones, then lexicographic order.
• Copies are compared by a bounded content hash over file names, entry kinds, permission bits, and bytes inside each skill directory (symlinks by target text, never followed). Only skills in multi-copy groups are hashed. A copy that exceeds the file or byte bound is treated as differing.
• A group whose copies are all identical resolves automatically to the canonical copy. The CLI prints which copy was used (resolved "demo": 6 identical copies, using plugin/skills/demo); the desktop matrix shows the canonical path with an identical-copies note.
• A group whose copies differ is ambiguous and is never guessed. The CLI fails with every copy listed as a pasteable --skill <name>=<path> form; the desktop matrix shows one row with a copy picker and needs-choice cells that stay unselectable until a copy is chosen. Review and apply revalidate the choice against fresh discovery and reject any path outside the draft.
• skill-manager install <git-url|local-path> [--tool …] [--skill <name>[=<path>] …] accepts the qualified form for both Git and local sources. A bare name resolves automatically when possible and reports ambiguity otherwise. A value whose whole text matches a discovered name is treated as a bare name before any = split, so literal = names keep working.
• Resolution reuses the manifest-recorded path of the same source when it still holds the skill, so reinstalls and extend stay stable when upstream gains another identical copy. An explicit choice wins over the recorded path. A recorded path that no longer holds the skill is drift: the operation fails and names uninstall plus reinstall as the way to adopt a new location. Nothing silently switches copies.
• update reports unrecorded identical groups as ordinary new skills and unrecorded conflicting groups as ambiguous new skills with a qualified --skill <name>=<path> template instead of a command. Recorded names are never reported as new, even when new copies appear. update --dry-run still does not fetch.
• The desktop Install new flow lists ambiguous new skills first with the copy picker; their cells stay needs-choice and unselected until a copy is chosen. The install-matrix bulk-selection toggle skips needs-choice cells without a chosen copy, like conflicts.
• Frontend mutation calls still use opaque draft/review/source identifiers plus skill and tool names; the copy choice is an additional draft-constrained selection, never an arbitrary filesystem path.
• Toggle, uninstall, repair, advisor, favorites, skill sets, strict dry-run, ownership, backup, rollback, and .agents/.skill-lock.json semantics do not change.

Cross-Source Skill Alias (Iteration 26)

Iteration 26 lets two recorded sources (two Git repositories, or a repository and a local path) that ship skills with the same basename be installed side by side in the same tool. Iteration 25 behavior inside one source does not change.

• Mechanism: an install name. The second source links its skill under a different link basename. Links stay symlinks; SKILL.md is never edited or copied.
• Policy: explicit, with a suggestion. A cross-source collision still blocks. The CLI prints a pasteable --as '<name>=<install-name>' form; the desktop matrix shows a needs-name row with an install-name input prefilled with the suggestion. Nothing installs under another name without a user decision, and needs-name rows are never preselected.
• Suggestion scheme: <name>-<owner>, where a Git source uses its repository owner segment (alpha-acme) and a local source uses its root basename (alpha-sample-pack). When that is taken, the suggestion falls back to <name>-<owner>-<repo> (a local source uses its parent directory basename as the second segment), then a numeric suffix. Segments are sanitized to the Agent Skills name rule: 1-64 characters from [a-z0-9-] with no leading, trailing, or double hyphen. Taken names include every recorded install name, disabled entry, name discovered in the same source, other install names in the same request, and existing active or disabled paths.
• skill-manager install <git-url|local-path> … [--as <name>=<install-name>]… is repeatable, splits on the first =, and rejects empty sides, invalid install names, and one skill with two install names. An install name must differ from every skill name in the same source, from every other install name in the request, and from every install name the source already records for its other skills, selected or not. Apply rechecks that no two skills of the source share an install name before saving.
• One install name per (source, skill) across all tools; no per-tool aliases. The manifest records it as installedAs on the installed skill entry (manifest version 3); a value equal to the skill name is stored as absent.
• The recorded install name wins. Reinstall and extend reuse it without --as; a different --as for a recorded skill is drift and needs uninstall plus reinstall, mirroring the Iteration 25 recorded-path rule. When a source records the plain name and a new tool's cell is owned elsewhere, the failure names uninstall plus reinstall with --as, or installing only the other tools.
• Everything after install (scan, toggles, disabled entries, advisor, favorites, Skill Sets, context budget, TUI and desktop rows) already keys on the link basename per tool, so the aliased skill is an independent row. Ownership checks, audits, uninstall, extend claims, and OFF records use the install name; update, new-skill discovery, and repair stay on source names.
• CLI lines show tool/<install-name> (<name>) when the names differ, and a successful install prints installed "<name>" as "<install-name>". update appends a suggested --as to its new-skill install command when another source owns a new skill's plain name.
• The desktop matrix validates the install name locally with the same rule and against other rows, keeps the row's cells unselectable while it is invalid, excludes the row from column bulk toggles, and blocks Review until every selected needs-name row is valid. Review and apply revalidate the name: it must be the recorded install name, or the plain name must be owned by another source in the fresh manifest. A skill whose copies differ and whose name another source owns asks for both the copy and the install name in the same row. Conflict messages name the owning source by group, never by filesystem path. The Skills view shows a differing SKILL.md name as a secondary label and includes it in search.
• Host caveats: Claude Code takes the command from the directory name, so an alias gives a distinct /<install-name> command. Codex and Grok identify skills by the frontmatter name, so both installs load but can share one label there. Muse behavior is unverified and is treated like Codex. Claude settings.json skill overrides are keyed by directory name and do not follow an alias. Advisor search indexes the install name, not the frontmatter name.
• Non-goals: an install-name offer in Discover, per-tool aliases, and advisor indexing of frontmatter names.

Source Skill Removal (Iteration 27)

Iteration 27 lets you remove some recorded skills from one source. It also gives the desktop app a remedy for an update that stops because the repository removed an installed skill. Before this iteration, the only remedy was to uninstall the full source from the CLI and install it again.

• The new operation removes only the selected skills of one Git or local source. The source and its other skills stay installed.
• For each selected skill, the operation removes the exact active and disabled links in each recorded tool, the disabled records of these links, and the entry of the skill in the source record.
• The operation does not change the managed checkout, the local source directory, or the remote refs. It does not fetch. It does not require a clean checkout or a recoverable upstream.
• You can identify a skill by its source name or by its install name. A source can gain a skill whose name is the install name of a different recorded skill. Then that name identifies two skills, and the operation stops with an error before it changes a file. The desktop app sends source names only, because source names are unique in a source.
• The full reference audit of the source runs before the first change. A missing, changed, duplicate, or extra link of the source stops the operation.
• The operation does not let you select all the recorded skills of a source. To remove all of them, uninstall the source.
• The operation stages the links in ~/.skill-manager/trash/, saves state.json one time, and then deletes the staging directory. If the save is not successful, it moves the links back.
• Skill Sets and favorites that use a removed install name stay unchanged. The desktop confirmation shows them. They do not stop the operation. The CLI does not show them, as for the uninstall of a full source.
• If the checkout still contains the skill, the Iteration 22 new-skill report shows it again. There is no ignore list.
• The manifest version does not change.
• CLI: skill-manager uninstall <git-url|local-path> --skill <name>... [--dry-run]. Without --skill, the command removes the full source, as before. An unknown name stops the command before it changes a file.
• Update: when recorded skills have no regular SKILL.md at the target commit, the preflight returns a typed error of the kind skill-missing-upstream. The message text does not change. The error gives each affected skill by source name, install name, and checkout-relative path. The CLI prints the exact uninstall --skill remedy command. When all the recorded skills are missing, the CLI and the desktop app tell you to uninstall the full source, and they say that this also removes the managed checkout. They do not show a removal command or button for this case.
• Desktop: a Remove skills source action opens a checklist of the recorded skills. The confirmation shows the links that it will remove and the affected Skill Sets and favorites. It does not ask for the group name. The confirmation button stays disabled when no skill or all the skills are selected.
• Desktop: after a skill-missing-upstream update error, the update dialog shows the cause and a Remove from source button. The button opens the confirmation with the affected skills selected. You start the update again after the removal. The update of all repositories continues to stop at the first failure.
• The action is a source operation in the exclusive source lane. The frontend sends an opaque source identifier and skill names only.
• Do not remove a skill automatically during update. Do not combine removal and update in one operation.
• Non-goals: a relink of a skill that moved to a different path, an ignore list for skills that you do not want reported, an option to continue the update of all repositories after a failure, and a TUI surface.

Advisor Receipts View (Iteration 28)

Iteration 28 adds a desktop surface for recorded advisor receipts and a remedy for a receipt whose cleanup stops on drift.

• The desktop Advisor view shows a Receipts section. Each receipt shows its tool, its activation time, and each skill with the action of a cleanup dry-run: disable, release, or already off. A receipt whose dry-run stops on drift or on a conflict is blocked and shows a path-free cause. An unrecorded entry at the disabled destination of a skill that cleanup must turn off is a conflict. Other dry-run failures, such as a scan error, show a fixed path-free message; no raw filesystem error crosses the desktop bridge.
• Clean up runs advisor cleanup on one receipt. Clean up all cleans each receipt that is not blocked, in list order, and stops at the first failure.
• Forget is available only for a blocked receipt. It removes the receipt and its lease claims, and removes a lease without claims. It does not change a link, a disabled entry, or state.json. The CLI form is skill-manager advisor forget --receipt <id> [--dry-run] [--json]. It stops with an error when cleanup of the receipt is possible.
• Each action has a confirmation that tells you that an open agent session can still use these skills. Advisor actions use the exclusive source lane. Skills toggles that you did not apply stop them.
• A receipt is cleaned or forgotten only on a user action. Its age is not a cause for an action. The first-party skill does not change and never uses forget.
• Non-goals: a CLI command that cleans all receipts, a receipt badge outside the Advisor view, and an automatic expiry.

Skill Context Budget Dashboard (Iteration 7)

Iteration 7 adds read-only context-cost visibility to the existing Dashboard. It does not change toggle, install, update, uninstall, CLI, or TUI semantics.

• Show separate Claude Code, Codex, Muse, and Grok global skill-catalog reports.
• Measure the startup catalog metadata, not full SKILL.md bodies. Full skill instructions remain an on-demand cost after invocation.
• Estimate catalog tokens as ceil(characters / 4) and label token values as approximate.
• Codex uses a 2% model-context budget. Prefer its local read-only diagnostic interfaces to measure the rendered and untruncated global catalog, including user, system, and enabled plugin skills. Run diagnostics from a neutral directory so repository-scoped skills are excluded.
• Claude Code uses its configured skill-listing budget, defaulting to 1% of the model context. Estimate personal and enabled-plugin entries from local files and settings; label the report partial when bundled, managed, or account state cannot be established outside an active Claude session.
• If Claude's context window cannot be resolved, use a clearly labeled 200,000 token fallback. If Codex's context window is unavailable, use its 8,000 character fallback budget.
• Muse has no supported provider diagnostic. Always report it as a labeled filesystem estimate over managed Muse user skills, using a 1% budget of an assumed 200,000-token context.
• Grok has no supported provider diagnostic. Always report it as a labeled filesystem estimate over managed Grok user skills, using a 1% budget of an assumed 200,000-token context.
• Show both the applied report and a projected After Apply report when pending GUI toggles change the catalog.
• Context diagnostics are best-effort and read-only. Failure, timeout, missing binaries, or malformed output must not block scanning or toggling skills.
• The report scope is global. Repository, nested-directory, additional-directory, and active-session-only skills are excluded.

Validation Strategy

Use temp directories for tests. Do not test against the real global skill directories.

Backend tests should cover:

• Scanning symlink skills
• Scanning local directory skills
• Source classification from ~/.agents/.skill-lock.json
• Hiding entries without SKILL.md
• State manifest persistence
• Disable and enable round trip for symlink entries
• Disable and enable round trip for directory entries
• Conflict detection on restore
• Dry-run output without filesystem mutation
• Deterministic apply ordering
• Repo URL normalization for HTTPS and SSH Git URLs
• Managed checkout path resolution
• Recursive skill discovery with ignored directories, duplicate grouping, content fingerprints, canonical ranking, qualified selection, and recorded-path stability
• Install manifest persistence
• Install preflight conflicts and idempotency
• Strict install dry-run without clone
• Symlink apply rollback for links created by a failed install operation
• Read-only repos command output without filesystem mutation
• Fast-forward-only repository update with installed-path preflight
• Update dry-run without fetch, Git-ref mutation, or state mutation
• Whole-repository uninstall for active and disabled skills
• Uninstall conflict detection, staging rollback, and cleanup reporting
• Manifest v1-to-v2 migration and local-source persistence
• Local source path normalization and protected-path overlap rejection
• Single-skill and recursive local discovery
• Local install dry-run, ownership, idempotency, conflict, and rollback behavior
• Local uninstall with active/OFF/broken targets, rollback, and source preservation
• Manifest-backed local path scan classification
• skills.sh response normalization, validation, cache persistence, offline fallback, local search, and rejection of oversized or unsafe responses
• Discover projection for ON/OFF/conflict cells and exact one-skill/selected-tool installation through the existing managed-source services
• Scoped desktop smart-toggle validation and active/available grouping, pending placement, search expansion, and session-only accordion state
• Skill Set persistence, validation, corruption isolation, missing-member retention, scoped smart-toggle preview/staging, overlapping-set projection, contextual creation, and non-blocking uninstall impact
• Path-free JSON inventory, advisor argument/version contracts, receipt/lease reference counting, concurrency locking, dry-run, baseline-ON preservation, drift-safe cleanup, and first-party skill validation
• Ranked advisor search tokenization, field weighting, phrase/fuzzy behavior, deterministic ordering, bounded input/output, capability negotiation, path-free results, and regression coverage for legacy list-query semantics
• Favorites persistence, owner-only atomic writes, corruption isolation, managed-row eligibility, basename reconnection, GUI filter/sort behavior, Pending independence, and non-blocking uninstall impact
• Native macOS About metadata parsing, required-field validation, and exact version/description projection from the desktop build configuration
• Checkout conflict classification with unchanged message text, porcelain worktree entry parsing, and repair staging, HEAD restore, idempotency, refusal of non-repairable blockers, installed-skill protection, rollback, cleanup reporting, and absence of destructive Git commands
• GUI source health inspection, path-free repair preview, confirmed repair, repairable failure classification, and the source-lane and pending guards

TUI can be tested at the model/update layer. Full terminal rendering tests are optional for MVP.

Documentation Rules

Keep README.md as a concise, desktop-first introduction with visual evidence, a macOS quick start, a terminal alternative, and legal/privacy links at the end. This presentation order does not change the CLI/TUI product contracts above.

Keep docs/usage.md as the detailed user guide for installation alternatives, GUI workflows, CLI commands, TUI keys, Skill Advisor, paths, safety, and troubleshooting. Keep source-build instructions in CONTRIBUTING.md. Keep release download links, archive names, and checksum examples synchronized between README and the user guide.

Keep SECURITY.md as the support and vulnerability-reporting policy: the current public preview and main receive best-effort support with no guaranteed response or remediation time. Keep PRIVACY.md aligned with every supported provider path and actual data flow.

The editorial refresh is tracked in planning/readme-editorial-tasks.md.

Keep this file as the agent-facing source of truth for architecture and product decisions.

Keep planning/phase-1-mvp-tasks.md as the source of truth for task status.

Keep planning/phase-2-group-bulk-toggle-tasks.md as the source of truth for Iteration 2 group and bulk-toggle task status.

Keep planning/phase-3-repo-install-tasks.md as the source of truth for Iteration 3 repository install task status.

Keep planning/phase-4-repo-update-uninstall-tasks.md as the source of truth for Iteration 4 repository update and uninstall task status.

Keep planning/phase-5-local-path-install-tasks.md as the source of truth for Iteration 5 local path install and uninstall task status.

Keep planning/phase-6-macos-gui-tasks.md as the source of truth for Iteration 6 macOS GUI task status, and keep DESIGN.md as the design-system contract for that interface.

Keep planning/phase-7-skill-context-budget-tasks.md as the source of truth for Iteration 7 skill context-budget task status.

Keep planning/phase-8-gui-source-management-tasks.md as the source of truth for Iteration 8 GUI source-management task status.

Keep planning/phase-9-skillssh-discover-tasks.md as the source of truth for Iteration 9 skills.sh Discover task status.

Keep planning/phase-10-skills-workspace-tasks.md as the source of truth for Iteration 10 active-first Skills workspace task status.

Keep planning/phase-11-publication-readiness-tasks.md as the source of truth for Iteration 11 public-source preparation task status.

Keep planning/phase-12-github-release-tasks.md as the source of truth for Iteration 12 GitHub binary release task status.

Keep planning/phase-13-public-preview-hardening-tasks.md as the source of truth for Iteration 13 public-preview hardening and publication task status.

Keep planning/phase-14-skill-sets-tasks.md as the source of truth for Iteration 14 saved Skill Set task status.

Keep planning/phase-15-skill-advisor-tasks.md as the source of truth for Iteration 15 first-party Skill Advisor task status.

Keep planning/phase-16-skill-favorites-tasks.md as the source of truth for Iteration 16 skill favorites task status.

Keep planning/phase-17-desktop-about-tasks.md as the source of truth for Iteration 17 native desktop About task status.

Keep planning/phase-18-advisor-search-tasks.md as the source of truth for Iteration 18 ranked Skill Advisor search task status.

Keep planning/phase-19-muse-support-tasks.md as the source of truth for Iteration 19 Muse tool support task status.

Keep planning/phase-20-grok-support-tasks.md as the source of truth for Iteration 20 Grok tool support task status.

Keep planning/phase-21-checkout-repair-tasks.md as the source of truth for Iteration 21 managed checkout diagnosis and repair task status.

Keep planning/phase-22-new-skill-discovery-tasks.md as the source of truth for Iteration 22 new skill discovery task status.

Keep planning/phase-23-install-as-off-tasks.md as the source of truth for Iteration 23 install as OFF task status.

Keep planning/phase-24-typesafe-advisor-tasks.md as the source of truth for the single-run optional TypeSafe advisor assignment and its acceptance criteria.

Keep planning/phase-26-cross-source-skill-alias-tasks.md as the source of truth for Iteration 26 cross-source skill alias task status.

Keep planning/phase-27-source-skill-removal-tasks.md as the source of truth for Iteration 27 source skill removal task status.

Keep planning/phase-28-advisor-receipts-view-tasks.md as the source of truth for Iteration 28 advisor receipts view task status.

Keep docs/wiki/README.md as the source of truth for wiki maintenance rules, docs/wiki/index.md as the wiki content map, and docs/wiki/log.md as the append-only maintenance history.

If a future agent changes scope, semantics, paths, or UX, update this file and the planning task status table in the same change.