iskills

中文

Personal skill collection for AI coding agents — discover, collect, install, and maintain skills that agents load via SKILL.md.

iskills is a terminal-first app: a full-screen TUI for day-to-day work, plus a small set of CLI commands for search, import, install, and Git setup. One collection per developer; no cloud account, no team admin surface.

Why iskills

Agent skills scatter across repos, global dirs, and project folders. iskills keeps a single personal collection as the source of truth, then installs into the places your agents already look:

You want to…	How
Discover	Live search skills.sh, or scan local / agent global directories
Collect	Import paths or Git sources into your collection with metadata, tags, and same-origin checks
Install	Link (default) or copy skills into the current project or agent global dirs
Maintain	Browse, update, delete, note, tag, and optionally sync the collection with Git — all in the TUI

Data integrity comes first: writes are transactional where it matters; conflicts never land in skills you are actively using.

Requirements

• Node.js 20.6+
• Bun recommended for the full-screen TUI (OpenTUI native FFI). iskills re-execs under Bun when the current Node lacks node:ffi. Pure CLI paths (help, non-TTY flags) work on Node alone.
• macOS or Linux
• A TTY for the interactive UI (stdin and stdout)
• Git optional — enable only if you want collection versioning / remote sync

UI language: Defaults to the system locale — Chinese (zh*) for Chinese UI, English otherwise. Override with iskills config (Chinese / English / follow system).

Install

bun install -g iskills

Verify:

iskills --version
iskills --help

Quick start

# Open the main browser (project · global · collection)
iskills

# Search skills.sh and save into your collection
iskills search react

# Import a local skill or a Git repository
iskills import ./my-skill
iskills import https://github.com/org/skills-repo.git

# Scan agent global skill directories
iskills import -g
iskills import -g --agent pi

# Create a new skill in the collection and open its directory
iskills create my-skill

# Install from your collection into this project (symlink)
iskills add my-skill

# Install into agent global dirs, or as a detached copy
iskills add my-skill -g --agent claude
iskills add my-skill --copy

# Optional: turn the collection into a Git repo (and set origin)
iskills init
iskills init --remote git@github.com:you/my-skills.git

# Configure UI language (follow system / Chinese / English)
iskills config

# MCP collection TUI (project / global / collection)
iskills mcp

In the main TUI, day-to-day work (browse, delete, update, notes, tags, sync) lives on the keyboard-driven browser. With a remote configured, press s on the Collection tab to sync.

Commands

Command	Description
iskills	Main TUI — project / global / collection browser
iskills search [query]	Search TUI against skills.sh; save selections to the collection
iskills create [name]	Create a new skill in the collection and open its directory
iskills import [source]	Import a local path or Git URL
iskills add [skill…]	Install from the collection into a project or global agent dir
iskills init	Initialize Git for the collection (optional remote)
iskills config	Configure UI preferences (language, collection Git remote)
iskills mcp	MCP collection TUI — project / global / collection

Common flags (see iskills help <command> for the full set):

• import: -g / --global, --agent <name>, --all, --replace, -y
• add: -g / --global, --agent <name>, --to <dir>, --copy, --replace, -y
• init: --remote <git-url>
• search: --replace
• mcp import / mcp add: -g / --global, --agent <name>, -y

Supported --agent values: agents, codex, claude, cursor, opencode, pi, zcode, trae, qoder, grok.

Collection layout

Item	Location
Collection root	$XDG_CONFIG_HOME/iskills, or ~/.config/iskills if unset
Git	Optional. When the collection is a Git repo, changes are auto-committed and can sync asynchronously
Source conflicts	.local/conflicts under the collection — resolve with an editor + Git, or copy a handoff from Alerts via Copy for Agent

After you commit a merge resolution, the next main TUI start (or a retained collection command) applies the result. Active in-use skills are never overwritten by conflict material.

Development

git clone https://github.com/eightHundreds/iskills.git
cd iskills
pnpm install --frozen-lockfile
pnpm run build
pnpm start -- --help
pnpm run type-check
pnpm pack --dry-run

Stack: TypeScript (strict), OpenTUI, React. The published package ships compiled dist/src only.

Non-goals

• Skill marketplace, hosting, accounts, or cloud sync as a product
• Desktop or web GUI
• CI/CD or headless machine API as the primary interface
• Multi-user / org permissions

Contributing

Tests and internal documentation live outside this public tree. Issues are welcome — bugs, ideas, and questions.

License

MIT