SKILLVIEW / FIELD GUIDE

Make yourself
at home.

From your first search to a clean inventory, here’s what you need to get moving.

Install SkillView

You need GitHub CLI version 2.102.0 or newer. For search and installation, authenticate with gh auth login.

Recommended: GitHub CLI extension

gh extension install harder/gh-skillview
gh skillview

Update it later with gh extension upgrade harder/gh-skillview.

Homebrew (macOS Apple Silicon and Linux x64)

brew install harder/tap/skillview
skillview

This installs the standalone app and its gh dependency. Update with brew upgrade harder/tap/skillview. The formula is maintained in the SkillView Homebrew tap.

Standalone app

Download a self-contained binary from the latest release and put it on your PATH. No separate .NET runtime is needed.

PlatformRelease asset
Windows x64skillview-windows-amd64.exe
Windows ARM64skillview-windows-arm64.exe
Linux x64skillview-linux-amd64
macOS ARM64skillview-darwin-arm64

On macOS and Linux, make the downloaded file executable with chmod +x <downloaded-file>.

Your first five minutes

  1. Launch the app with gh skillview or skillview.
  2. Search for a topic or skill and browse the Discover results.
  3. Select a result to read its SKILL.md before installing.
  4. Press i to review a standard install, or I for more options.
  5. Open Installed with 2 to see your local skills.
Current Installed screen showing sample physical copies, filters and coverage

Find your way around

SkillView has three main tabs: Discover for finding and previewing skills, Installed for your local inventory, and Issues for captured findings and supported repairs. Doctor and cleanup findings are available on demand.

Inspect an exact physical copy and its recorded consumers before choosing an action. Update availability is checked explicitly; findings and suggestions never apply changes by themselves. Saved updates review source changes and permission to retain the original separately, with a fresh review for Undo.

Use F5 for Locations and F4 for retained-operation History. Local browsing does not require a remote authentication check.

This guide follows the development version and may be ahead of your installed release. Check skillview --version and press ? or F1 for the current screen’s shortcuts.

Find skills wherever you keep them

Use Discover for public repository search and read-only previews. Use Installed for physical copies already on disk: user and project agent folders, universal/shared placements, and observed managed or plugin skills. Read-only inventory does not require remote authentication.

TaskWhere to startWhat it means
Search upstreamDiscover / search and previewSearch by topic and owner; review skill content and bundled files. Standard/advanced install chooses version, skills, scope, agents, custom path, local/upstream source and hidden-directory options.
Choose local coverageF5 Locations / --workspace, --scan-root, --profileWorkspaces add known project skill folders; scan roots name exact skills folders; profiles label explicit agent folders. Saved Locations apply to TUI launches; CLI subcommands use their explicit/default context.
Find a physical copyInstalled filters / list --jsonFilter by Agent, Project/location, Source/owner, Issue, pin and scope. Expand a heading and select an exact child to inspect every recorded consumer.
Understand scan limitsInstalled Coverage / F2 / doctor --inventory --jsonUnavailable, hidden, unsupported and unselected locations remain incomplete or outside coverage. Unobserved does not mean empty, healthy, enabled or loaded in a running agent.
Current Locations dialog for workspaces, scan roots and profiles
The 1.1 feature set, captured before the version bump; isolated sample inventory. Screens illustrate review paths, not successful repairs or live upstream results.

A simpler view of your skills

Discover, Installed and Issues keep clear headings and compact toolbars. Installed uses one row per physical copy, with expandable groups when copies share a known source. At narrow terminal widths, Enter opens full-width details and Esc returns to the list; wider terminals show details beside the list. Press f to reveal filters, and use More actions for package checks and detailed repair flows. Gold marks the current selection; technical evidence stays available with F2.

The screenshots and walkthroughs show the current source build with warm full-color terminal output and isolated sample data. They may differ from the latest released download until the next update. Watch the GIFs or videos and read the walkthrough steps.

Diagnose the exact problem

TaskWhere to startWhat it means
Local inventory findingsIssues / queue --json / inspectDistinguish broken links, empty residue, malformed files, conflicting records, grouped source/revision/method differences and unmatched gh records. A registry-only row offers guidance, not a repair target.
Package contentsInstalled K / More actions → Check package / checkBounded static metadata, missing local references, literal dependency declarations and portability checks. No skill code or AI client runs. Dependency availability, source trust and unmodeled agent compatibility stay unknown.
Differences between copiesExpand Issues family → exact child → Enter → Reference / Compare; Installed More actions / compareRead file, mode and recorded-source differences. Equal content does not establish redundancy or permission to delete. Keep both / Choices acknowledges an intentional difference without modifying skills.
Available updatesInstalled or Issues C / update --all --dry-runExplicit availability check only. Not checked, unknown, stale, pinned and failed differ from current. It does not prepare or apply an update.
Environment troubled Doctor / doctor --inventory --json / --debugInspect gh path/version, command support, on-demand authentication, agent homes, inventory and logs. Startup local browsing does not wait on remote auth.
Issues shows Problems, Review findings and incomplete coverage separately
Static package check of a sample skill with a missing reference

Review a supported fix

Choose an exact physical copy and inspect its consumers first. Findings, comparisons and suggestions do not approve writes. Source-changing plans freeze a candidate for review; source acknowledgement and permission to retain the original are separate. A changed target or uncertain ownership can refuse the action.

TaskWhere to startWhat it means
Update or choose a tagExact copy u / Review update; Choose version / update-planReview frozen source Diff and omissions, then approve retention. Existing pins require separate unpin review. Prepare the next copy after the previous apply reconciles.
Restore a missing resourceK then an eligible More actions resource-replacement reviewReplaces the whole package, retaining local edits/extras. The full saved comparison must establish the missing file; fresh post-apply verification remains distinct from native success.
Restore recorded Git contentrestore-planStage the recorded immutable revision, review its source changes and separately approve original retention. See the recorded-restoration guide for acknowledgement/apply/Undo commands.
Repair an attached damaged tracked copyMore actions → Review registry-recorded replacement / registry-restore-planRequires a compatible attached gh record and corroborating physical evidence. An unmatched record alone cannot authorize restoration or registry deletion.
Refresh/change local sourceMore actions → local reimport / source switch; reimport-plan / source-switch-planOwnerless local copies only: reimport from the same recorded source or choose another durable local source. Separate source review and retention; no new automatic local merge.
UnpinPurpose-specific unpin review / unpin-planPin-only transaction preserves installed content and recorded source revision; it is separate from ordinary update.
Remove a copy or residueInstalled x / Issues c / remove or cleanup previewFresh native review for an exact removable copy, eligible broken link or empty directory. Malformed/conflicting/owned/partial findings remain protected or review-only. Deletion has no automatic Undo.
Move aside temporarilyMore actions → Review standalone Move aside / quarantine previewAn admitted untracked standalone Custom copy can be retained by same-volume rename after separate declaration/effect approvals. Tracked, managed, shared or uncertain copies refuse. This does not unload an agent.
Keep evidence or an intentional suggestionbackup / history; cleanup Suppress suggestion / ignoreBackup evidence does not grant restore authority. External cleanup suppression does not edit or disable a skill; it is separate from Keep both family preferences.
Review several findingsIssues g Guided; n Next, s Skip, x Stop in the active sequenceOne eligible exact item at a time, with fresh individual approvals. No Apply all; family and registry-only observations do not choose targets.

After an attempted write, refresh inventory before another review. Filesystem success, inventory verification and running-agent reload are separate facts.

Explicit comparison of two captured sample copies
Choose a reference for comparison; matching content never chooses a deletion target.

Undo, recover and inspect retained data

Use fresh inspection before Undo or recovery; the original apply fingerprint is not current restoration approval. F4 History lists saved replacements and offers admitted inspection, abandonment of an unapplied review or explicit Discard Undo data. Discard is permanent; retained data is never purged automatically.

Moved-aside copies have a separate quarantine-history and undo --id workflow; F4 does not list quarantine. replacement-history gives saved-replacement hints, while history verifies retained backup journals and payload blobs. Interrupted or unknown operations remain protected for purpose-specific inspect/recover/undo commands.

Keep the same HOME/state, launch directory, workspace/profile/scan-root flags and saved IDs through review and recovery. Never delete journals to clear an error. Read the saved-update guide, recorded restoration, Move aside and Undo, and complete action matrix.

Essential shortcuts

KeysAction
1 / 2 / 3Discover / Installed / Issues
/Focus search
i / IStandard / advanced install
CCheck updates explicitly from Installed or Issues
uReview an eligible exact copy’s saved update
xReview removal of selected skill in Installed
c / dCleanup findings / Doctor
F4 / F5Retained-operation History / Locations
? / F1Full help
Ctrl+QQuit from anywhere

Work from the command line

Add a subcommand to run SkillView without the full-screen interface. Use gh skillview in place of skillview when installed as an extension.

skillview doctor
skillview search terraform
skillview preview OWNER/REPO SKILL
skillview install OWNER/REPO SKILL
skillview list --json
skillview queue --json
skillview --scan-root /path/to/skills check --path /path/to/skills/demo --json
skillview update --all --dry-run
skillview cleanup

Commands that support --json can feed scripts and AI agents. Run skillview --help for flags and options. Put global flags such as --scan-root before the subcommand:

skillview --scan-root /path/to/skills list --json

When something feels off

Run skillview doctor to inspect your GitHub CLI path, version, authentication, detected agent homes, and log location. In the TUI, press d.

For a bug report, include skillview --version, your OS and terminal, the command or flow you used, and whether gh auth status succeeds. Run with --debug if you need a more detailed log.

Go deeper

This documentation covers SkillView 1.1.1. Read the release notes and upgrade instructions; check skillview --version for your installed version.

Start with Find, diagnose and fix skills for the complete route map and sample screenshots.

The repository’s usage guide covers shortcuts, common CLI flags, exit codes, configuration, and troubleshooting. Run skillview --help for the complete command option list. For development setup and tests, see CONTRIBUTING.md.

SkillView is open source under the MIT License. Browse the source on GitHub or visit Kevin Harder and Harder Labs.