🔨 Skillforge

A Windsurf-native CLI tool to install and run AI agent skills from Git repos — like brew for AI prompts. All skills and config live inside .windsurf/ directories.

Quick Start

# Install globally
npm install -g skillforge

# Or link locally for development
npm link

# Configure your OpenAI API key
skillforge config set openai-key sk-your-key-here

# Install a skills repo (global — available everywhere)
skillforge install https://github.com/your-org/ai-skills.git

# Install a skills repo (local — only this project)
skillforge install https://github.com/your-org/ai-skills.git --local

# Create a skill in current project
skillforge init my-skill

# Create a global skill
skillforge init my-skill --global

# List available skills (merges local + global)
skillforge list

# Run a skill
skillforge run code-review --file "$(cat myfile.js)"

# Search for skills
skillforge search testing

Storage (Windsurf-native)

Skillforge stores everything inside .windsurf/ directories:

| Scope | Path | When to use | |---|---|---| | Global | ~/.windsurf/skillforge/ | Skills available across all projects | | Local | .windsurf/skillforge/ (in project root) | Skills scoped to this project only |

~/.windsurf/skillforge/         # Global
├── config.json                 # API keys, default model
├── repos/                      # Cloned skill repos
│   └── my-team-skills/
│       └── skills/*.md
└── skills/                     # Standalone global skills
    └── my-global-skill.md

your-project/.windsurf/skillforge/   # Local (per-project)
├── repos/                      # Project-scoped repos
└── skills/                     # Project-scoped skills
    └── my-local-skill.md

Local skills take precedence over global ones with the same name.

Example Output

$ skillforge list

📋 Installed Skills (2 total)

┌──────────────────┬──────────────────────────────┬──────────┬──────────────────┬────────┬──────────────┐
│ Skill            │ Description                  │ Model    │ Tags             │ Scope  │ Source       │
├──────────────────┼──────────────────────────────┼──────────┼──────────────────┼────────┼──────────────┤
│ test-global-sk…  │ Describe what this skill     │ gpt-4    │ custom           │ global │ global-skil… │
│                  │ does                         │          │                  │        │              │
├──────────────────┼──────────────────────────────┼──────────┼──────────────────┼────────┼──────────────┤
│ test-local-skill │ Describe what this skill     │ gpt-4    │ custom           │ local  │ local-skills │
│                  │ does                         │          │                  │        │              │
└──────────────────┴──────────────────────────────┴──────────┴──────────────────┴────────┴──────────────┘

Commands

| Command | Description | |---|---| | skillforge install <url> | Clone a skills repo globally (or --local) | | skillforge list | List all skills (local + global), filter with --scope local | | skillforge search <keyword> | Search skills by name, description, or tags | | skillforge run <skill> [--args] | Execute a skill (sends prompt to LLM) | | skillforge update | Pull latest changes from all repos | | skillforge info <skill-name> | Show details about a skill | | skillforge init [name] | Create a skill in local .windsurf/ (or --global) | | skillforge config <action> [key] [value] | Manage configuration |

Skill Format

Skills are Markdown files with YAML frontmatter:

---
name: my-skill
description: What this skill does
args:
  - name: input
    description: The primary input
    required: true
  - name: language
    default: auto-detect
tags: [coding, review]
model: gpt-4
---

Your prompt template here. Use {{input}} and {{language}} placeholders.

Creating Skills

# Create a local skill (in .windsurf/skillforge/skills/)
skillforge init my-awesome-skill

# Create a global skill (in ~/.windsurf/skillforge/skills/)
skillforge init my-awesome-skill --global

Sharing Skills via Git

Create a repo with a skills/ directory containing .md files, then anyone can install:

skillforge install <your-repo-url>
skillforge install <your-repo-url> --local   # project-only

Configuration

# Set OpenAI API key
skillforge config set openai-key sk-...

# Change default model
skillforge config set default-model gpt-4o

# View all config
skillforge config list

# Get specific value
skillforge config get default-model

Config is stored at ~/.windsurf/skillforge/config.json.

Requirements

• Node.js 18+
• An OpenAI API key (for running skills)