⚓ Skillport

Skillport is a cross-platform terminal UI for managing agent skills installed on your machine.

The goal is to provide one place to discover, fetch, install, organize, move, enable, and disable local skills across agent providers. The current release focuses on inventory and availability toggles; fetching, installation, and moving skills are future directions and are not implemented yet.

Currently, Skillport collects installed global skills into a three-level tree:

Provider
└── Plugin or skill root
    └── Skill

It manages skill availability without deleting content. Disabling a skill renames its marker file:

SKILL.md ⇄ SKILL.md.disabled

✨ Current features

• 🌐 Locally installed skill inventory grouped by provider and plugin/root
• 🎛️ Individual skill toggles
• 📦 Confirmed bulk toggles for every skill in a container
• 🛡️ Preflight checks and rollback for bulk operations
• ⚠️ Conflict detection when both marker files exist
• 🔗 Symlink alias detection
• 🩺 Malformed frontmatter warnings without hiding the skill
• 🔎 Search across providers, containers, names, descriptions, and paths
• 📝 Adaptive details pane with wrapped descriptions and paths
• 🎨 Nerd Font icons with Unicode and ASCII fallbacks
• 🔄 Manual refresh with an automatic rescan after mutations

The current release reports filesystem state only. It does not yet manage remote skill catalogs, installations, agent configuration, model runtime state, hooks, commands, MCP servers, or executable tools.

🤖 Supported global locations

Built-in discovery covers standard global locations for:

• 🟣 OMP personal, managed, marketplace, npm, and linked plugin skills
• 🟠 Claude Code personal and installed-plugin skills
• 🔵 GitHub Copilot CLI personal and installed-plugin skills
• 🟢 Codex personal skills
• 🟡 OpenCode personal skills
• 🧩 Shared ~/.agent/skills and ~/.agents/skills roots

Missing locations are ignored. Discovery currently targets user-global locations; repository-scoped skill roots are not scanned yet.

📋 Requirements

• 🟢 Node.js 20 or newer
• 📦 pnpm 10 or newer
• 💻 An interactive terminal
• 🔣 A Nerd Font for the default icon set

🚀 Quick start

Run the latest published release without installing it globally:

npx @jsun969/skillport

Or install it globally with pnpm:

pnpm add --global @jsun969/skillport
skillport

Install from source

git clone https://github.com/jsun969/skillport.git
cd skillport
pnpm install
pnpm build
pnpm link --global

For development:

pnpm dev

🎨 Icon modes

Nerd Font icons are used by default:

skillport --icons=nerd

Use a fallback when Nerd Font glyphs are unavailable:

skillport --icons=unicode
skillport --icons=ascii

⌨️ Keybindings

| Key | Action | | --- | --- | | ↑ / k | Move up | | ↓ / j | Move down | | → / l | Expand branch | | ← / h | Collapse branch or select parent | | Enter | Toggle branch expansion | | Space | Toggle a skill or container | | / | Search | | r | Refresh inventory | | ? | Toggle help | | q | Quit |

Container toggles require confirmation. A mixed container enables all descendants when toggled.

🚦 Marker states

| State | Meaning | | --- | --- | | ✅ Enabled | SKILL.md exists | | ⏸️ Disabled | SKILL.md.disabled exists | | 🌓 Mixed | A container has enabled and disabled descendants | | ⚠️ Conflict | Both marker files exist; toggling is blocked | | 🩺 Warning | Metadata is missing, malformed, or inaccessible | | 🔗 Linked | Another tree entry resolves to the same physical skill directory |

Skillport never overwrites an existing marker. If a bulk rename fails after changes begin, it attempts to roll back every completed rename and reports any rollback failures.

🛠️ Development

pnpm typecheck
pnpm test
pnpm build

The test suite covers provider discovery, disabled and conflicted markers, manifest-declared plugin skills, symlink aliases, plugin-root deduplication, tree filtering, toggle planning, preflight protection, and transaction rollback.