@hiver/skills

A CLI tool to install and manage shared Claude Code skills & agents across Hiver repositories.

Skills are reusable AI prompt workflows (markdown files) that live in collections. This CLI copies them into the right directory for your IDE — Claude Code, Cursor, or Windsurf.

For Consumers

Install skills interactively

npx @hiver/skills add

This walks you through:

1. Pick your IDE — Claude Code, Cursor, or Windsurf
2. Pick a collection — common (generic) or web (React/Hiver-specific)
3. Pick type — Skills or Agents (only shown if both exist)
4. Pick items — Select which skills/agents to install

Dependencies are auto-resolved and installed.

Other commands

npx @hiver/skills list                          # List all available skills & agents
npx @hiver/skills add discuss-problem create-prd # Install specific skills directly
npx @hiver/skills update                         # Check for updates (shows diff, asks before overwriting)
npx @hiver/skills remove discuss-problem         # Remove an installed skill
npx @hiver/skills help                           # Show help

Navigation

• Arrow keys — move up/down
• Space — toggle selection (multi-select)
• Enter — confirm
• Esc — go back to previous step

For Contributors

Prerequisites

• Node.js >= 18
• Yarn

Setup

git clone <repo-url>
cd hiver-skills
yarn install
yarn build

Test locally

# Run any command directly
node dist/cli.js list
node dist/cli.js add
node dist/cli.js help

# Or link globally to test as a consumer would
yarn link
cd /path/to/any/project
hiver-skills add

Creating a new skill (AI-assisted)

This repo includes a built-in /create-skill skill that guides you through the entire process of creating a new skill or agent using AI. It works in both Claude Code and Cursor.

In Claude Code:

/create-skill

In Cursor: The create-skill.md rule is auto-loaded from .cursor/rules/.

The skill will:

1. Ask you what the skill should do, who it's for, and where it belongs
2. Discuss edge cases, dependencies, and scope boundaries through back-and-forth
3. Validate its understanding with you before writing anything
4. Create the properly structured SKILL.md (or agent .md) file with correct frontmatter
5. Verify it shows up in the CLI

This is the recommended way to add new skills — it ensures consistency with existing patterns and catches issues early.

Project structure

hiver-skills/
├── .claude/skills/create-skill/  # AI skill to help devs create new skills (Claude Code)
├── .cursor/rules/                # Same skill for Cursor
├── src/                          # Source code (React + Ink CLI)
│   ├── cli.jsx                   # Entry point — routes to commands
│   ├── commands/
│   │   ├── Add.jsx               # Interactive install wizard
│   │   ├── List.jsx              # List available skills/agents
│   │   ├── Update.jsx            # Diff-based update flow
│   │   └── Remove.jsx            # Remove installed skills/agents
│   ├── components/
│   │   ├── Select.jsx            # Single-select menu (for target, collection)
│   │   ├── MultiSelect.jsx       # Multi-select with checkboxes (for skills)
│   │   ├── Confirm.jsx           # Yes/no prompt
│   │   ├── DiffView.jsx          # Colored diff display
│   │   └── StatusMessage.jsx     # Success/warning/error messages
│   └── utils/
│       ├── collections.js        # Scan collections, parse frontmatter, resolve deps
│       ├── installer.js          # Copy/remove skills to IDE target directories
│       ├── targets.js            # IDE target configs (paths for Claude, Cursor, Windsurf)
│       └── diffUtil.js           # Compute diffs between local and latest files
│
├── collections/                  # Skill & agent markdown files
│   ├── common/                   # Repo-agnostic skills (work in any project)
│   │   ├── skills/
│   │   └── agents/
│   └── web/                      # Hiver web app specific
│       ├── skills/
│       └── agents/
│
├── dist/                         # Built output (do not edit directly)
│   └── cli.js                    # Bundled CLI binary
│
├── build.js                      # esbuild config
├── package.json
└── .github/workflows/            # CI/CD pipelines

How to: Common tasks

Add a new skill

1. Decide which collection it belongs to:

   • collections/common/skills/ — if it's repo-agnostic (no hardcoded paths, no specific frameworks)
   • collections/web/skills/ — if it's specific to the Hiver web app
   • Create a new collection directory if needed (e.g., collections/extension/skills/)

2. Create a directory for the skill:

   mkdir collections/common/skills/my-new-skill

3. Create a SKILL.md file inside it with YAML frontmatter:

   ---
   name: my-new-skill
   description: Short description of what this skill does. This shows up in the CLI.
   dependencies: []
   ---
   
   # My New Skill
   
   Instructions for the AI go here...

4. If the skill has supporting reference files, put them in subdirectories:

   my-new-skill/
   ├── SKILL.md
   └── references/
       ├── patterns.md
       └── examples.md

   The entire directory gets copied when a consumer installs the skill.

5. Build and test:

   yarn build
   node dist/cli.js list        # Verify it shows up
   node dist/cli.js add         # Test installing it

Add a new agent

1. Create a markdown file in the appropriate agents/ directory:

   # For repo-agnostic agents
   touch collections/common/agents/my-agent.md
   
   # For web-specific agents
   touch collections/web/agents/my-agent.md

2. Add YAML frontmatter:

   ---
   name: my-agent
   description: Short description shown in the CLI.
   dependencies: [write-test-cases]
   ---
   
   Agent instructions here...

3. Build and verify:

   yarn build
   node dist/cli.js list

Add a new collection (for a new repo/team)

1. Create the collection directory structure:

   mkdir -p collections/my-repo/{skills,agents}

2. Add skills and/or agents inside it (follow the steps above).

3. That's it — the CLI auto-discovers collections by scanning the collections/ directory. No registration needed.

Add a new IDE target

1. Open src/utils/targets.js

2. Add a new entry:

   export const targets = {
     claude: { name: 'Claude Code', skillsDir: '.claude/skills', agentsDir: '.claude/agents' },
     cursor: { name: 'Cursor', skillsDir: '.cursor/rules', agentsDir: '.cursor/rules' },
     windsurf: { name: 'Windsurf', skillsDir: '.windsurfrules', agentsDir: '.windsurfrules' },
     // Add new target here:
     newIde: { name: 'New IDE', skillsDir: '.newide/skills', agentsDir: '.newide/agents' },
   };

3. The CLI picks it up automatically in the target selection step.

Declare dependencies between skills/agents

Add a dependencies field in the YAML frontmatter:

---
name: build-feature
description: Orchestrates full feature build
dependencies: [build-milestone, write-test-cases]
---

When a consumer installs build-feature, the CLI will auto-install build-milestone and write-test-cases if they're not already selected.

Dependencies are resolved across all collections — a common skill can depend on a web agent, etc.

Modify the CLI UI

The CLI is built with Ink (React for the terminal).

• Components are in src/components/ — standard React components using Ink's <Box>, <Text>, useInput
• Commands are in src/commands/ — each command is a React component with step-based state machine
• Routing is in src/cli.jsx — maps CLI args to command components

After any source change:

yarn build                    # Rebuild
node dist/cli.js <command>    # Test

Add a new CLI command

1. Create src/commands/MyCommand.jsx:

   import React from 'react';
   import { Text, useApp } from 'ink';
   
   export function MyCommand() {
     const { exit } = useApp();
     setTimeout(() => exit(), 100);
     return <Text color="green">Hello from my command!</Text>;
   }

2. Register it in src/cli.jsx:

   import { MyCommand } from './commands/MyCommand.jsx';
   
   // Inside the App switch:
   case 'my-command':
     return <MyCommand />;

3. Add it to the help text in the Help component in the same file.

Build & Release

Build

yarn build

This runs esbuild to bundle src/cli.jsx into dist/cli.js — a single ESM file with a shebang that can run directly with Node.

GitHub Workflows

There are 4 workflows in .github/workflows/:

| Workflow | File | Trigger | Purpose | |----------|------|---------|---------| | Verify PR | verify-pull-request.yml | Auto on PR open/sync | Runs yarn install + yarn build to verify the PR compiles | | Stable Release | publish-to-npm.yml | Manual (workflow_dispatch) | Publishes a stable version to NPM | | Beta Release | publish-to-npm-beta.yml | Manual (workflow_dispatch) | Publishes a beta version to NPM from any branch |

How to release a change

Step 1: Get your PR merged

1. Create a feature branch and make your changes
2. Open a PR to main
3. The Verify PR workflow runs automatically — it must pass before merging
4. Get review and merge to main

Step 2a: Stable release (for production-ready changes)

1. Go to GitHub Actions → "Npm release process"
2. Click "Run workflow"
3. Enter the version number (e.g., 1.2.0)
4. Click "Run workflow"

What it does:

• Checks out main
• Installs dependencies and builds
• Bumps the version in package.json
• Publishes to NPM (npm publish)
• Commits the version bump and pushes
• Generates a changelog from merged PRs and commits it

After release, consumers get the new version with:

npx @hiver/skills@latest add

Step 2b: Beta release (for testing before stable)

Use this when you want others to test a change before making it the default version.

1. Go to GitHub Actions → "Beta Release Process"
2. Click "Run workflow"
3. Enter the branch to publish from (e.g., feat/new-skill or main)
4. Enter the beta version (e.g., 1.2.0-beta.1)
   • Always use the format x.y.z-beta.N
   • Increment N for subsequent beta releases (beta.1, beta.2, etc.)
5. Click "Run workflow"

What it does:

• Checks out the specified branch
• Installs dependencies and builds
• Bumps the version in package.json (does not commit)
• Publishes to NPM with the beta tag

Consumers can test the beta with:

npx @hiver/skills@beta add

The beta tag means npx @hiver/skills add (without a tag) still uses the latest stable version — beta is opt-in only.

When to use which?

| Scenario | Workflow | |----------|----------| | Merged a new skill, ready for everyone | Stable release | | Updated skill content, small fix | Stable release (patch bump) | | WIP feature on a branch, need someone to test | Beta release from that branch | | Big change, want to validate before going stable | Beta release first, then Stable release |

Required secrets

These GitHub secrets must be configured in the repository settings:

| Secret | Purpose | |--------|---------| | NPM_TOKEN_NEW | NPM authentication token for publishing | | CI_SYSTEM_GITHUB_WORKFLOW | GitHub PAT for pushing commits (version bumps, changelog) | | GITHUB_TOKEN | Auto-provided by GitHub Actions (used for PR checks) |

Key design decisions

• Copy-on-install (like shadcn/ui) — skills are copied into the consumer's project, not symlinked. Consumers own the files and can customize them.
• Markdown-only skills — skills are .md files with YAML frontmatter. No executable code in skills.
• Auto-discovery — collections, skills, and agents are discovered by scanning the filesystem. No central registry file to maintain.
• Single build output — esbuild bundles all JSX into one dist/cli.js. Dependencies stay external (loaded from node_modules at runtime).