skill-push

Simplify pushing local AI agent skills to GitHub using the gh CLI tool.

Features

• 🚀 Quick publishing of skills to GitHub
• 🔍 Automatic skill discovery (scans for SKILL.md files)
• 📦 Monorepo or individual repository support
• 🎯 Interactive and non-interactive modes
• ✅ Compatible with Claude Code, Cursor, and other AI agents

Prerequisites

• GitHub CLI installed and authenticated

  # Install gh CLI
  # https://cli.github.com/
  
  # Authenticate
  gh auth login

Installation

npm install -g skill-push
# or use directly with npx
npx skill-push

Usage

Interactive Mode (Recommended for first-time users)

npx skill-push

You'll be prompted for:

1. Where to scan for skills (home directory, current directory, or custom path)
2. How to organize skills (monorepo or individual repositories)
3. What to require for valid skill (SKILL.md only, or with README/metadata)

Non-Interactive Mode

# Use all defaults (scan ~ and PWD, create monorepo)
npx skill-push --yes

# Custom path
npx skill-push --path ~/my-skills

# Multiple paths
npx skill-push --path ~/my-skills ~/other-skills

# Individual repos per skill
npx skill-push --individual

# Specify repository name
npx skill-push --repo my-awesome-skills

# Create public repository
npx skill-push --public

# Dry run (preview what would happen)
npx skill-push --dry-run

# Verbose output
npx skill-push --verbose

Options

| Option | Alias | Description | Default | |--------|-------|-------------|---------| | --yes | -y | Skip interactive prompts, use defaults | false | | --path | -p | Custom path(s) to scan for skills | ~/ and PWD | | --monorepo | -m | Create monorepo structure | true | | --individual | -i | Create individual repos per skill | false | | --repo | -r | Repository name | skills | | --public | | Create public repositories | false | | --dry-run | -d | Preview actions without executing | false | | --verbose | -v | Verbose output | false | | --help | -h | Show help | - | | --version | -V | Show version | - |

Skill Format

A valid skill must contain at minimum:

your-skill/
  SKILL.md  # Required: Frontmatter with name, description
  README.md # Optional: Human-readable docs
  metadata.json # Optional: Version info
  AGENTS.md # Optional: Full agent documentation

Example SKILL.md

---
name: my-awesome-skill
description: A skill that does awesome things
---

# My Awesome Skill

This skill helps AI agents do awesome things.

Examples

Publish a single skill

npx skill-push --path ~/.agents/skills/my-skill --individual

Publish all skills as monorepo

npx skill-push --yes --repo my-awesome-skills

Dry run to see what would happen

npx skill-push --dry-run --verbose

Publish from custom location

npx skill-push --path ~/Documents/my-skills --public

How It Works

1. Scans the specified directories for SKILL.md files
2. Validates each skill directory
3. Creates GitHub repository using gh CLI
4. Initializes git and pushes skill files

Monorepo Mode (Default)

Creates a single repository with all skills as subdirectories:

username/skills/
  skill-1/
  skill-2/
  skill-3/

Individual Mode

Creates separate repository for each skill:

username/skills/skill-1
username/skills/skill-2
username/skills/skill-3

Compatibility

Works with skills pulled by:

• npx skills (Vercel agent-skills)
• npx openskills
• Manually created skill directories

Error Handling

• gh CLI not installed: Provides installation instructions
• gh CLI not authenticated: Prompts to run gh auth login
• No skills found: Suggests checking paths
• Repository exists: Skips with warning (doesn't overwrite)

Contributing

Contributions welcome! Please open an issue or PR.

License

MIT

Sources

• Vercel Launches Skills — "npm for AI Agents"
• vercel-labs/agent-skills
• AI SDK Tool Package Template