Grimoire

A TUI skill manager for AI coding tools. Browse, install, and manage skills across Claude Code, Cursor, Gemini CLI, Kiro, and more — all from one terminal interface.

  ██████╗ ██████╗ ██╗███╗   ███╗ ██████╗ ██╗██████╗ ███████╗
 ██╔════╝ ██╔══██╗██║████╗ ████║██╔═══██╗██║██╔══██╗██╔════╝
 ██║  ███╗██████╔╝██║██╔████╔██║██║   ██║██║██████╔╝█████╗
 ██║   ██║██╔══██╗██║██║╚██╔╝██║██║   ██║██║██╔══██╗██╔══╝
 ╚██████╔╝██║  ██║██║██║ ╚═╝ ██║╚██████╔╝██║██║  ██║███████╗
  ╚═════╝ ╚═╝  ╚═╝╚═╝╚═╝     ╚═╝ ╚═════╝ ╚═╝╚═╝  ╚═╝╚══════╝

What It Does

Skills are reusable instructions and resources that enhance AI coding tools. They live in tool-specific directories (e.g. ~/.claude/skills/) and are loaded automatically by the AI tool.

Grimoire gives you one place to:

• Browse the skills.sh leaderboard in a navigable grid TUI
• Search the skills.sh registry by keyword
• Install skills for one or many AI tools at once
• List what's currently installed with metadata
• Configure which tool and skills directory to use

Skills come from three sources:

1. Local — skills already on disk
2. skills.sh — open registry (https://skills.sh)
3. Impeccable — design suite (https://impeccable.style)

Quick Start

npm install
npm run build
npm start

On first run, Grimoire launches a setup wizard to pick your AI tool and skills directory. After that:

grimoire> browse          # grid TUI — browse, select, install
grimoire> search testing  # search the registry
grimoire> list            # see installed skills
grimoire> install anthropics/skills   # install by owner/repo
grimoire> help            # all commands

Browse TUI

The browse command opens a full-screen interactive grid:

  skills.sh Leaderboard  —  189 skills  |  2 selected

  ┌────────────────────────────────┐ ┌────────────────────────────────┐
  │ ● find-skills                  │ │ ○ vercel-react-best-pract...   │
  │   vercel-labs/skills           │ │   vercel-labs/agent-skills     │
  │   649.1K                   #1  │ │   233.2K                   #2  │
  └────────────────────────────────┘ └────────────────────────────────┘

  ↑↓←→ navigate  space select  a select all  i install  q quit

Pressing i opens an agent picker — choose which tools to install for:

  Selected Skills
  ──────────────────────────────────────────────────────
  ● find-skills  vercel-labs/skills
  ● frontend-design  anthropics/skills
  ──────────────────────────────────────────────────────

  Install for which tools?

  ▸ ● Claude Code
    ○ Cursor
    ○ Antigravity
    ○ Gemini CLI
    ...

  ↑↓ navigate  space toggle  a all  enter install  q cancel

Supported Tools

| Tool | Skills Directory | Auto-detected | |------|-----------------|---------------| | Claude Code | ~/.claude/skills/ | via $CLAUDE_CODE_VERSION | | Cursor | ~/.cursor/skills/ | via ~/.cursor/ | | Antigravity | ~/.agents/skills/ | via ~/.antigravity/ | | Gemini CLI | ~/.gemini/skills/ | via ~/.gemini/ | | Kiro | ~/.kiro/skills/ | via ~/.kiro/ | | Codex | ~/.codex/skills/ | via setup | | Copilot | ~/.copilot/skills/ | via setup | | Windsurf | ~/.windsurf/skills/ | via setup | | OpenCode | ~/.opencode/skills/ | via setup |

Custom directories can be set via $SKILLS_ROOT env var or the setup command.

Architecture

src/
  index.ts          Entry point — setup wizard on first run, banner, REPL
  repl.ts           Command loop — parses input, dispatches to commands
  detect.ts         Environment detection — finds active tool + skills root
  config.ts         Persistent config at ~/.grimoire/config.json
  banner.ts         ASCII banner with environment info
  skills.ts         Skill metadata parser (reads SKILL.md frontmatter)
  commands/
    help.ts         Command listing
    setup.ts        Interactive tool + directory config wizard
    list.ts         Installed skills table
    search.ts       Registry search via npx skills find
    browse.ts       Full-screen TUI grid browser + agent picker
    install.ts      Install via npx skills add

Zero runtime dependencies. Only TypeScript and @types/node as dev dependencies.

Detection priority: --tool flag > saved config > $SKILLS_ROOT > ./.skills/ > tool-specific checks > fallback ~/.ai-skills/.

Development

npm run build      # tsc — compiles to dist/
npm run dev        # build + run
npm start          # run dist/index.js

No test framework or linter configured yet.

Roadmap

Unimplemented Commands

These are specified in the PRD but not yet built:

• uninstall — Remove skills with [y/N] confirmation
• update — Check for and apply skill updates
• info — Detailed metadata for a single skill (version, source, files, dependencies)
• validate — Check skills for issues (missing SKILL.md, broken references)
• create — Scaffold a new skill interactively
• package — Bundle a skill into a .skill zip file
• doctor — Full environment diagnostics (npx, network, broken skills)
• impeccable — Subcommands for the Impeccable design suite (status, list, install, update)

Known Issues

1. Tool list divergence — detect.ts, setup.ts, and browse.ts each define their own tool lists with different entries. Should be a single shared constant.
2. HTML scraping for browse — skills.sh data is extracted from page HTML via regex. If the site changes, parsing breaks. An API would be more reliable.
3. No pagination — The PRD specifies paginating every 20 rows for list output, but it's not implemented for non-TUI commands.
4. No overwrite confirmation on install — If a skill already exists, install should prompt before overwriting.

Feature Ideas

• Offline cache — Cache the leaderboard locally so browse works offline with stale data
• Skill search within browse — Type / in the grid to filter skills by name
• Favorites — Mark skills as favorites for quick reinstall on new machines
• Skill diff — Show what changed between installed and latest version before updating
• Shell completions — Tab completion for bash/zsh/fish
• Config export/import — Export your skill setup to share or replicate across machines
• Skill groups — Install curated bundles (e.g. "web dev essentials", "devops toolkit")

How It Works

Grimoire wraps the skills CLI (npx skills) for registry operations. Skills are installed globally (--global) to the user's tool-specific directory. The browse TUI fetches the skills.sh leaderboard over HTTPS (no external dependencies like curl), renders a navigable grid, and lets you batch-select skills and choose which AI tools to install them for.

Skill metadata is read from SKILL.md YAML frontmatter in each skill directory:

---
name: my-skill
version: 1.0.0
source: owner/repo
description: What this skill does
---

License

ISC