windsurf-skillforge 1.0.0

package/README.md

@@ -0,0 +1,156 @@
+# 🔨 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
+
+```bash
+# 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:
+
+```md
+---
+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
+
+```bash
+# 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:
+```bash
+skillforge install <your-repo-url>
+skillforge install <your-repo-url> --local   # project-only
+```
+
+## Configuration
+
+```bash
+# 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)

package/bin/skillforge.js

@@ -0,0 +1,72 @@
+#!/usr/bin/env node
+
+import { createRequire } from 'module';
+import { program } from 'commander';
+import chalk from 'chalk';
+
+import { installCommand } from '../src/commands/install.js';
+import { listCommand } from '../src/commands/list.js';
+import { searchCommand } from '../src/commands/search.js';
+import { runCommand } from '../src/commands/run.js';
+import { updateCommand } from '../src/commands/update.js';
+import { infoCommand } from '../src/commands/info.js';
+import { initCommand } from '../src/commands/init.js';
+import { configCommand } from '../src/commands/config.js';
+
+const require = createRequire(import.meta.url);
+const pkg = require('../package.json');
+
+program
+  .name('skillforge')
+  .description(chalk.bold('🔨 Skillforge') + ' — Install and run AI agent skills from Git repos')
+  .version(pkg.version, '-v, --version');
+
+program
+  .command('install <repo-url>')
+  .description('Install a skills repo from a Git URL')
+  .option('-n, --name <name>', 'Custom name for the repo')
+  .option('-l, --local', 'Install to local .windsurf/ (project scope)')
+  .action(installCommand);
+
+program
+  .command('list')
+  .description('List all installed skills (global + local)')
+  .option('-r, --repo <repo>', 'Filter by repo name')
+  .option('-s, --scope <scope>', 'Filter by scope: local or global')
+  .action(listCommand);
+
+program
+  .command('search <keyword>')
+  .description('Search skills by name, description, or tags')
+  .action(searchCommand);
+
+program
+  .command('run <skill-name>')
+  .description('Run an AI skill')
+  .option('-m, --model <model>', 'Override the LLM model')
+  .allowUnknownOption(true)
+  .action(runCommand);
+
+program
+  .command('update')
+  .description('Update all installed skill repos (git pull)')
+  .option('-r, --repo <repo>', 'Update a specific repo only')
+  .action(updateCommand);
+
+program
+  .command('info <skill-name>')
+  .description('Show details of a specific skill')
+  .action(infoCommand);
+
+program
+  .command('init [name]')
+  .description('Create a new skill template (defaults to local .windsurf/)')
+  .option('-g, --global', 'Create in global ~/.windsurf/ instead of local')
+  .action(initCommand);
+
+program
+  .command('config <action> [key] [value]')
+  .description('Manage configuration (set, get, list, delete)')
+  .action(configCommand);
+
+program.parse();

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "windsurf-skillforge",
+  "version": "1.0.0",
+  "description": "A CLI tool to install and run AI agent skills from Git repos — like brew for AI prompts",
+  "type": "module",
+  "bin": {
+    "skillforge": "bin/skillforge.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "skills/",
+    "skillforge.yaml",
+    "README.md"
+  ],
+  "scripts": {
+    "start": "node bin/skillforge.js",
+    "test": "node --test test/**/*.test.js"
+  },
+  "keywords": [
+    "cli",
+    "ai",
+    "skills",
+    "prompts",
+    "llm",
+    "agent"
+  ],
+  "author": "",
+  "license": "MIT",
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "commander": "^12.1.0",
+    "conf": "^13.0.1",
+    "gray-matter": "^4.0.3",
+    "openai": "^4.68.0",
+    "ora": "^8.1.0",
+    "simple-git": "^3.27.0",
+    "cli-table3": "^0.6.5"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/skillforge.yaml

@@ -0,0 +1,4 @@
+# Skillforge Skills Repository
+name: skillforge-default-skills
+description: Default AI agent skills bundled with Skillforge
+version: 1.0.0

package/skills/code-review.md

@@ -0,0 +1,40 @@
+---
+name: code-review
+description: Reviews code for best practices, bugs, and performance issues
+args:
+  - name: file
+    description: Path to the file to review
+    required: true
+  - name: language
+    description: Programming language
+    default: auto-detect
+  - name: focus
+    description: What to focus on (bugs, performance, style, security)
+    default: all
+tags: [review, quality, bugs]
+model: gpt-4
+---
+
+You are an expert code reviewer with deep knowledge of software engineering best practices.
+
+Review the following code thoroughly for:
+- **Bugs and edge cases** — logic errors, off-by-one, null checks
+- **Performance issues** — unnecessary loops, memory leaks, inefficient patterns
+- **Best practices violations** — naming, structure, SOLID principles
+- **Security concerns** — injection, XSS, sensitive data exposure
+
+Focus area: {{focus}}
+Language: {{language}}
+
+Code to review:
+```
+{{file}}
+```
+
+Provide your review in this format:
+1. **Summary** — overall assessment (1-2 sentences)
+2. **Critical Issues** — bugs or security problems that must be fixed
+3. **Improvements** — recommended changes for better code quality
+4. **Positive Highlights** — things done well
+
+Be specific with line references and provide corrected code snippets where applicable.

package/skills/explain-code.md

@@ -0,0 +1,31 @@
+---
+name: explain-code
+description: Explains code in plain English with visual diagrams
+args:
+  - name: code
+    description: The code to explain
+    required: true
+  - name: level
+    description: Explanation level (beginner, intermediate, expert)
+    default: intermediate
+tags: [learning, documentation, explain]
+model: gpt-4
+---
+
+You are a patient and clear technical educator.
+
+Explain the following code at a {{level}} level:
+
+```
+{{code}}
+```
+
+Structure your explanation as:
+
+1. **Overview** — What does this code do in one sentence?
+2. **Step-by-step breakdown** — Walk through the logic line by line
+3. **Key concepts** — Explain any patterns, algorithms, or techniques used
+4. **Flow diagram** — Show the execution flow using ASCII art
+5. **Potential gotchas** — What could trip someone up?
+
+Use analogies and simple language where possible.

package/skills/generate-tests.md

@@ -0,0 +1,35 @@
+---
+name: generate-tests
+description: Generates unit tests for a given function or module
+args:
+  - name: code
+    description: The code to generate tests for
+    required: true
+  - name: framework
+    description: Test framework to use (jest, mocha, vitest, pytest)
+    default: jest
+  - name: style
+    description: Test style (unit, integration, e2e)
+    default: unit
+tags: [testing, automation, quality]
+model: gpt-4
+---
+
+You are an expert test engineer. Generate comprehensive {{style}} tests for the following code.
+
+Test framework: {{framework}}
+
+Code to test:
+```
+{{code}}
+```
+
+Requirements:
+1. Cover all public functions/methods
+2. Include edge cases (empty input, null, boundary values)
+3. Include both positive and negative test cases
+4. Use descriptive test names that explain the expected behavior
+5. Mock external dependencies appropriately
+6. Aim for high code coverage
+
+Output the complete test file ready to run.

package/src/commands/config.js

@@ -0,0 +1,66 @@
+import chalk from 'chalk';
+import { config } from '../config/store.js';
+
+export async function configCommand(action, key, value) {
+  switch (action) {
+    case 'set':
+      if (!key || value === undefined) {
+        console.error(chalk.red('\n✗ Usage: skillforge config set <key> <value>\n'));
+        console.error(chalk.dim('  Examples:'));
+        console.error(chalk.dim('    skillforge config set openai-key sk-...'));
+        console.error(chalk.dim('    skillforge config set default-model gpt-4o\n'));
+        process.exit(1);
+      }
+      config.set(key, value);
+      // Mask API keys in output
+      const displayValue = key.includes('key') ? value.slice(0, 6) + '...' + value.slice(-4) : value;
+      console.log(chalk.green(`\n✓ Set "${key}" = "${displayValue}"\n`));
+      break;
+
+    case 'get':
+      if (!key) {
+        console.error(chalk.red('\n✗ Usage: skillforge config get <key>\n'));
+        process.exit(1);
+      }
+      const val = config.get(key);
+      if (val === undefined) {
+        console.log(chalk.yellow(`\n"${key}" is not set.\n`));
+      } else {
+        const display = key.includes('key') && typeof val === 'string'
+          ? val.slice(0, 6) + '...' + val.slice(-4)
+          : (typeof val === 'object' ? JSON.stringify(val, null, 2) : val);
+        console.log(`\n${chalk.bold(key)}: ${display}\n`);
+      }
+      break;
+
+    case 'list':
+      console.log(chalk.bold('\n⚙️  Configuration\n'));
+      const store = config.store;
+      for (const [k, v] of Object.entries(store)) {
+        if (k === 'repos') {
+          const repoNames = Object.keys(v);
+          console.log(`  ${chalk.cyan(k)}: ${repoNames.length > 0 ? repoNames.join(', ') : chalk.dim('(none)')}`);
+        } else if (k.includes('key') && typeof v === 'string' && v.length > 10) {
+          console.log(`  ${chalk.cyan(k)}: ${v.slice(0, 6)}...${v.slice(-4)}`);
+        } else {
+          console.log(`  ${chalk.cyan(k)}: ${v || chalk.dim('(not set)')}`);
+        }
+      }
+      console.log('');
+      break;
+
+    case 'delete':
+      if (!key) {
+        console.error(chalk.red('\n✗ Usage: skillforge config delete <key>\n'));
+        process.exit(1);
+      }
+      config.delete(key);
+      console.log(chalk.green(`\n✓ Deleted "${key}"\n`));
+      break;
+
+    default:
+      console.error(chalk.red(`\n✗ Unknown action "${action}".`));
+      console.error(chalk.dim('  Available: set, get, list, delete\n'));
+      process.exit(1);
+  }
+}

package/src/commands/info.js

@@ -0,0 +1,51 @@
+import chalk from 'chalk';
+import { findSkill } from '../utils/scanner.js';
+
+export async function infoCommand(skillName) {
+  const skill = findSkill(skillName);
+
+  if (!skill) {
+    console.error(chalk.red(`\n✗ Skill "${skillName}" not found.`));
+    console.error(chalk.dim('  Run: skillforge list to see available skills\n'));
+    process.exit(1);
+  }
+
+  console.log('');
+  console.log(chalk.bold(`🔨 ${skill.skillName}`));
+  console.log(chalk.dim('─'.repeat(50)));
+
+  if (skill.meta.description) {
+    console.log(chalk.white(`  Description: ${skill.meta.description}`));
+  }
+
+  console.log(chalk.white(`  Model:       ${skill.meta.model || 'gpt-4'}`));
+  console.log(chalk.white(`  Repo:        ${skill.repoName}`));
+  console.log(chalk.white(`  File:        ${skill.filePath}`));
+
+  if (skill.meta.tags && skill.meta.tags.length > 0) {
+    console.log(chalk.white(`  Tags:        ${skill.meta.tags.join(', ')}`));
+  }
+
+  if (skill.meta.args && skill.meta.args.length > 0) {
+    console.log(chalk.bold('\n  Arguments:'));
+    for (const arg of skill.meta.args) {
+      const required = arg.required ? chalk.red('(required)') : chalk.dim('(optional)');
+      const defaultVal = arg.default ? chalk.dim(` [default: ${arg.default}]`) : '';
+      console.log(`    --${arg.name}  ${arg.description || ''} ${required}${defaultVal}`);
+    }
+  }
+
+  console.log(chalk.bold('\n  Prompt Preview:'));
+  console.log(chalk.dim('  ┌' + '─'.repeat(48) + '┐'));
+  const previewLines = skill.prompt.split('\n').slice(0, 8);
+  for (const line of previewLines) {
+    const truncated = line.length > 46 ? line.substring(0, 43) + '...' : line;
+    console.log(chalk.dim('  │ ') + truncated);
+  }
+  if (skill.prompt.split('\n').length > 8) {
+    console.log(chalk.dim('  │ ...'));
+  }
+  console.log(chalk.dim('  └' + '─'.repeat(48) + '┘'));
+
+  console.log('');
+}

package/src/commands/init.js

@@ -0,0 +1,62 @@
+import { writeFileSync, existsSync, mkdirSync } from 'fs';
+import { join } from 'path';
+import chalk from 'chalk';
+import { GLOBAL_SKILLS_DIR, ensureLocalDirs, getLocalDirs } from '../config/store.js';
+
+const SKILL_TEMPLATE = `---
+name: {{SKILL_NAME}}
+description: Describe what this skill does
+args:
+  - name: input
+    description: The primary input for this skill
+    required: true
+  - name: language
+    description: Programming language context
+    default: auto-detect
+tags: [custom]
+model: gpt-4
+---
+
+You are an expert assistant. Follow these instructions carefully.
+
+Input: {{input}}
+Language: {{language}}
+
+Please provide a thorough and helpful response.
+`;
+
+export async function initCommand(name, options) {
+  const skillName = name || 'my-skill';
+  const isLocal = !options.global; // default to local (in project .windsurf/)
+
+  let skillsDir;
+  if (isLocal) {
+    const local = ensureLocalDirs();
+    skillsDir = local.SKILLS_DIR;
+  } else {
+    skillsDir = GLOBAL_SKILLS_DIR;
+  }
+
+  if (!existsSync(skillsDir)) {
+    mkdirSync(skillsDir, { recursive: true });
+  }
+
+  const filePath = join(skillsDir, `${skillName}.md`);
+  const scope = isLocal ? 'local' : 'global';
+
+  if (existsSync(filePath)) {
+    console.error(chalk.red(`\n✗ File already exists: ${filePath}\n`));
+    process.exit(1);
+  }
+
+  const content = SKILL_TEMPLATE.replace('{{SKILL_NAME}}', skillName);
+  writeFileSync(filePath, content, 'utf-8');
+
+  console.log(chalk.green(`\n✓ Created skill template (${scope}): ${filePath}`));
+  console.log(chalk.dim('  Edit the file to customize your skill.'));
+  if (isLocal) {
+    console.log(chalk.dim('  This skill is available in the current project.\n'));
+  } else {
+    console.log(chalk.dim('  This skill is available globally across all projects.\n'));
+  }
+}

package/src/commands/install.js

@@ -0,0 +1,58 @@
+import { join, basename } from 'path';
+import { existsSync } from 'fs';
+import simpleGit from 'simple-git';
+import chalk from 'chalk';
+import ora from 'ora';
+import { config, GLOBAL_REPOS_DIR, ensureLocalDirs, getLocalDirs } from '../config/store.js';
+
+export async function installCommand(repoUrl, options) {
+  // Derive repo name from URL or use custom name
+  let repoName = options.name;
+  if (!repoName) {
+    repoName = basename(repoUrl, '.git').replace(/[^a-zA-Z0-9_-]/g, '-');
+  }
+
+  // Determine scope: --local installs to .windsurf/skillforge/repos/ in cwd
+  const isLocal = options.local || false;
+  let reposDir;
+
+  if (isLocal) {
+    const local = ensureLocalDirs();
+    reposDir = local.REPOS_DIR;
+  } else {
+    reposDir = GLOBAL_REPOS_DIR;
+  }
+
+  const repoPath = join(reposDir, repoName);
+  const scope = isLocal ? 'local' : 'global';
+
+  if (existsSync(repoPath)) {
+    console.log(chalk.yellow(`\n⚠ Repo "${repoName}" already installed (${scope}) at ${repoPath}`));
+    console.log(chalk.dim('  Run: skillforge update to pull latest changes\n'));
+    return;
+  }
+
+  const spinner = ora(`Cloning ${repoUrl} (${scope})...`).start();
+
+  try {
+    const git = simpleGit();
+    await git.clone(repoUrl, repoPath);
+
+    // Register in config
+    const repos = config.get('repos') || {};
+    repos[repoName] = {
+      url: repoUrl,
+      path: repoPath,
+      scope,
+      installedAt: new Date().toISOString()
+    };
+    config.set('repos', repos);
+
+    spinner.succeed(chalk.green(`Installed "${repoName}" (${scope}) successfully`));
+    console.log(chalk.dim(`  Path: ${repoPath}`));
+    console.log(chalk.dim('  Run: skillforge list to see available skills\n'));
+  } catch (err) {
+    spinner.fail(chalk.red(`Failed to clone repo: ${err.message}`));
+    process.exit(1);
+  }
+}

package/src/commands/list.js

@@ -0,0 +1,64 @@
+import chalk from 'chalk';
+import Table from 'cli-table3';
+import { scanAllSkills, scanRepoSkills } from '../utils/scanner.js';
+import { config } from '../config/store.js';
+
+export async function listCommand(options) {
+  let skills;
+
+  if (options.repo) {
+    const repos = config.get('repos') || {};
+    const repoInfo = repos[options.repo];
+    if (!repoInfo) {
+      console.log(chalk.red(`\n✗ Repo "${options.repo}" not found.\n`));
+      return;
+    }
+    skills = scanRepoSkills(options.repo, repoInfo.path, repoInfo.scope || 'global');
+  } else {
+    skills = scanAllSkills();
+  }
+
+  // Filter by scope if requested
+  if (options.scope) {
+    skills = skills.filter(s => s.scope === options.scope);
+  }
+
+  if (skills.length === 0) {
+    console.log(chalk.yellow('\nNo skills found.'));
+    console.log(chalk.dim('  Install a skills repo: skillforge install <repo-url>'));
+    console.log(chalk.dim('  Or create one:         skillforge init my-skill\n'));
+    return;
+  }
+
+  const table = new Table({
+    head: [
+      chalk.cyan('Skill'),
+      chalk.cyan('Description'),
+      chalk.cyan('Model'),
+      chalk.cyan('Tags'),
+      chalk.cyan('Scope'),
+      chalk.cyan('Source')
+    ],
+    colWidths: [18, 30, 10, 18, 8, 14],
+    wordWrap: true
+  });
+
+  for (const skill of skills) {
+    const scopeLabel = skill.scope === 'local'
+      ? chalk.green('local')
+      : chalk.blue('global');
+
+    table.push([
+      chalk.white.bold(skill.skillName),
+      skill.meta.description || chalk.dim('—'),
+      chalk.dim(skill.meta.model || 'gpt-4'),
+      (skill.meta.tags || []).join(', ') || chalk.dim('—'),
+      scopeLabel,
+      chalk.dim(skill.repoName)
+    ]);
+  }
+
+  console.log(`\n${chalk.bold('📋 Installed Skills')} (${skills.length} total)\n`);
+  console.log(table.toString());
+  console.log('');
+}

package/src/commands/run.js

@@ -0,0 +1,69 @@
+import chalk from 'chalk';
+import { findSkill } from '../utils/scanner.js';
+import { renderPrompt } from '../engine/renderer.js';
+import { executeSkill } from '../engine/runner.js';
+import { config } from '../config/store.js';
+
+export async function runCommand(skillName, options, command) {
+  const skill = findSkill(skillName);
+
+  if (!skill) {
+    console.error(chalk.red(`\n✗ Skill "${skillName}" not found.`));
+    console.error(chalk.dim('  Run: skillforge list to see available skills\n'));
+    process.exit(1);
+  }
+
+  // Parse extra args from command line (--file=test.js or --file test.js)
+  const userArgs = {};
+  const rawArgs = command.parent.args.slice(1); // skip skill name
+  for (let i = 0; i < rawArgs.length; i++) {
+    const arg = rawArgs[i];
+    if (arg.startsWith('--')) {
+      const key = arg.replace(/^--/, '');
+      if (key.includes('=')) {
+        const [k, v] = key.split('=');
+        userArgs[k] = v;
+      } else if (i + 1 < rawArgs.length && !rawArgs[i + 1].startsWith('--')) {
+        userArgs[key] = rawArgs[i + 1];
+        i++;
+      } else {
+        userArgs[key] = 'true';
+      }
+    }
+  }
+
+  // Check required args
+  const requiredArgs = (skill.meta.args || []).filter(a => a.required);
+  const missingArgs = requiredArgs.filter(a => !userArgs[a.name]);
+
+  if (missingArgs.length > 0) {
+    console.error(chalk.red(`\n✗ Missing required arguments:`));
+    for (const arg of missingArgs) {
+      console.error(chalk.yellow(`  --${arg.name}  ${arg.description || ''}`));
+    }
+    console.error('');
+    process.exit(1);
+  }
+
+  // Fill defaults
+  for (const argDef of skill.meta.args || []) {
+    if (userArgs[argDef.name] === undefined && argDef.default !== undefined) {
+      userArgs[argDef.name] = argDef.default;
+    }
+  }
+
+  // Render prompt
+  const renderedPrompt = renderPrompt(skill.prompt, userArgs);
+
+  // Determine model
+  const model = options.model || skill.meta.model || config.get('default-model') || 'gpt-4';
+
+  console.log(chalk.bold(`\n🔨 Running skill: ${skill.skillName}`));
+  console.log(chalk.dim(`   From repo: ${skill.repoName}`));
+
+  if (Object.keys(userArgs).length > 0) {
+    console.log(chalk.dim(`   Args: ${JSON.stringify(userArgs)}`));
+  }
+
+  await executeSkill(renderedPrompt, model, skill.meta);
+}

package/src/commands/search.js

@@ -0,0 +1,44 @@
+import chalk from 'chalk';
+import Table from 'cli-table3';
+import { scanAllSkills } from '../utils/scanner.js';
+
+export async function searchCommand(keyword) {
+  const allSkills = scanAllSkills();
+  const query = keyword.toLowerCase();
+
+  const results = allSkills.filter(skill => {
+    const nameMatch = skill.skillName.toLowerCase().includes(query);
+    const descMatch = (skill.meta.description || '').toLowerCase().includes(query);
+    const tagMatch = (skill.meta.tags || []).some(t => t.toLowerCase().includes(query));
+    return nameMatch || descMatch || tagMatch;
+  });
+
+  if (results.length === 0) {
+    console.log(chalk.yellow(`\nNo skills matching "${keyword}".\n`));
+    return;
+  }
+
+  const table = new Table({
+    head: [
+      chalk.cyan('Skill'),
+      chalk.cyan('Description'),
+      chalk.cyan('Tags'),
+      chalk.cyan('Repo')
+    ],
+    colWidths: [20, 40, 20, 15],
+    wordWrap: true
+  });
+
+  for (const skill of results) {
+    table.push([
+      chalk.white.bold(skill.skillName),
+      skill.meta.description || chalk.dim('—'),
+      (skill.meta.tags || []).join(', ') || chalk.dim('—'),
+      chalk.dim(skill.repoName)
+    ]);
+  }
+
+  console.log(`\n${chalk.bold('🔍 Search Results')} for "${keyword}" (${results.length} found)\n`);
+  console.log(table.toString());
+  console.log('');
+}

package/src/commands/update.js

@@ -0,0 +1,46 @@
+import simpleGit from 'simple-git';
+import chalk from 'chalk';
+import ora from 'ora';
+import { config } from '../config/store.js';
+
+export async function updateCommand(options) {
+  const repos = config.get('repos') || {};
+  const repoEntries = Object.entries(repos);
+
+  if (repoEntries.length === 0) {
+    console.log(chalk.yellow('\nNo repos installed.'));
+    console.log(chalk.dim('  Run: skillforge install <repo-url>\n'));
+    return;
+  }
+
+  // Filter to specific repo if requested
+  const toUpdate = options.repo
+    ? repoEntries.filter(([name]) => name === options.repo)
+    : repoEntries;
+
+  if (toUpdate.length === 0) {
+    console.log(chalk.red(`\n✗ Repo "${options.repo}" not found.\n`));
+    return;
+  }
+
+  console.log(chalk.bold(`\n🔄 Updating ${toUpdate.length} repo(s)...\n`));
+
+  for (const [repoName, repoInfo] of toUpdate) {
+    const spinner = ora(`Updating "${repoName}"...`).start();
+
+    try {
+      const git = simpleGit(repoInfo.path);
+      const result = await git.pull();
+
+      if (result.summary.changes > 0) {
+        spinner.succeed(chalk.green(`"${repoName}" updated (${result.summary.changes} changes)`));
+      } else {
+        spinner.succeed(chalk.dim(`"${repoName}" already up to date`));
+      }
+    } catch (err) {
+      spinner.fail(chalk.red(`"${repoName}" failed: ${err.message}`));
+    }
+  }
+
+  console.log('');
+}

package/src/config/store.js

@@ -0,0 +1,57 @@
+import Conf from 'conf';
+import { homedir } from 'os';
+import { join } from 'path';
+import { mkdirSync, existsSync } from 'fs';
+
+// Global: ~/.windsurf/skillforge/
+const GLOBAL_WINDSURF_DIR = join(homedir(), '.windsurf');
+const GLOBAL_SKILLFORGE_DIR = join(GLOBAL_WINDSURF_DIR, 'skillforge');
+const GLOBAL_REPOS_DIR = join(GLOBAL_SKILLFORGE_DIR, 'repos');
+const GLOBAL_SKILLS_DIR = join(GLOBAL_SKILLFORGE_DIR, 'skills');
+
+// Ensure global directories exist
+for (const dir of [GLOBAL_WINDSURF_DIR, GLOBAL_SKILLFORGE_DIR, GLOBAL_REPOS_DIR, GLOBAL_SKILLS_DIR]) {
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+}
+
+// Local: .windsurf/skillforge/ (relative to cwd)
+function getLocalDirs() {
+  const localWindsurf = join(process.cwd(), '.windsurf');
+  const localSkillforge = join(localWindsurf, 'skillforge');
+  const localRepos = join(localSkillforge, 'repos');
+  const localSkills = join(localSkillforge, 'skills');
+  return {
+    WINDSURF_DIR: localWindsurf,
+    SKILLFORGE_DIR: localSkillforge,
+    REPOS_DIR: localRepos,
+    SKILLS_DIR: localSkills
+  };
+}
+
+function ensureLocalDirs() {
+  const local = getLocalDirs();
+  for (const dir of [local.WINDSURF_DIR, local.SKILLFORGE_DIR, local.REPOS_DIR, local.SKILLS_DIR]) {
+    if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  }
+  return local;
+}
+
+const config = new Conf({
+  projectName: 'skillforge',
+  cwd: GLOBAL_SKILLFORGE_DIR,
+  defaults: {
+    'openai-key': '',
+    'default-model': 'gpt-4',
+    'repos': {}
+  }
+});
+
+export {
+  config,
+  GLOBAL_WINDSURF_DIR,
+  GLOBAL_SKILLFORGE_DIR,
+  GLOBAL_REPOS_DIR,
+  GLOBAL_SKILLS_DIR,
+  getLocalDirs,
+  ensureLocalDirs
+};

package/src/engine/parser.js

@@ -0,0 +1,43 @@
+import matter from 'gray-matter';
+import { readFileSync } from 'fs';
+
+/**
+ * Parse a skill markdown file into structured data.
+ * Returns { meta, prompt } where meta is the YAML frontmatter
+ * and prompt is the markdown body.
+ */
+export function parseSkillFile(filePath) {
+  const raw = readFileSync(filePath, 'utf-8');
+  const { data, content } = matter(raw);
+
+  return {
+    meta: {
+      name: data.name || '',
+      description: data.description || '',
+      args: data.args || [],
+      tags: data.tags || [],
+      model: data.model || 'gpt-4',
+      ...data
+    },
+    prompt: content.trim()
+  };
+}
+
+/**
+ * Parse skill content from a string (not file).
+ */
+export function parseSkillContent(rawContent) {
+  const { data, content } = matter(rawContent);
+
+  return {
+    meta: {
+      name: data.name || '',
+      description: data.description || '',
+      args: data.args || [],
+      tags: data.tags || [],
+      model: data.model || 'gpt-4',
+      ...data
+    },
+    prompt: content.trim()
+  };
+}

package/src/engine/renderer.js

@@ -0,0 +1,35 @@
+/**
+ * Replace {{arg}} placeholders in the prompt with user-provided values.
+ * Also supports {{arg | default_value}} syntax.
+ */
+export function renderPrompt(promptTemplate, args) {
+  let rendered = promptTemplate;
+
+  // Replace {{argName}} and {{ argName | default }} patterns
+  rendered = rendered.replace(/\{\{\s*(\w+)\s*(?:\|\s*([^}]*))?\s*\}\}/g, (match, argName, defaultVal) => {
+    if (args[argName] !== undefined && args[argName] !== null) {
+      return String(args[argName]);
+    }
+    if (defaultVal !== undefined) {
+      return defaultVal.trim();
+    }
+    return match; // Leave unresolved placeholders as-is
+  });
+
+  return rendered;
+}
+
+/**
+ * Extract all placeholder names from a prompt template.
+ */
+export function extractPlaceholders(promptTemplate) {
+  const placeholders = [];
+  const regex = /\{\{\s*(\w+)\s*(?:\|\s*[^}]*)?\s*\}\}/g;
+  let match;
+  while ((match = regex.exec(promptTemplate)) !== null) {
+    if (!placeholders.includes(match[1])) {
+      placeholders.push(match[1]);
+    }
+  }
+  return placeholders;
+}

package/src/engine/runner.js

@@ -0,0 +1,54 @@
+import OpenAI from 'openai';
+import chalk from 'chalk';
+import { config } from '../config/store.js';
+
+/**
+ * Send a rendered prompt to the LLM and stream the response to stdout.
+ */
+export async function executeSkill(renderedPrompt, model, skillMeta) {
+  const apiKey = config.get('openai-key');
+
+  if (!apiKey) {
+    console.error(chalk.red('\n✗ OpenAI API key not configured.'));
+    console.error(chalk.yellow('  Run: skillforge config set openai-key <your-key>\n'));
+    process.exit(1);
+  }
+
+  const openai = new OpenAI({ apiKey });
+
+  const systemMessage = skillMeta.system
+    ? skillMeta.system
+    : 'You are a helpful AI assistant executing a skill. Follow the instructions precisely.';
+
+  console.log(chalk.dim(`\nUsing model: ${model}\n`));
+  console.log(chalk.dim('─'.repeat(60)));
+
+  try {
+    const stream = await openai.chat.completions.create({
+      model: model,
+      messages: [
+        { role: 'system', content: systemMessage },
+        { role: 'user', content: renderedPrompt }
+      ],
+      stream: true
+    });
+
+    for await (const chunk of stream) {
+      const content = chunk.choices[0]?.delta?.content;
+      if (content) {
+        process.stdout.write(content);
+      }
+    }
+
+    console.log('\n' + chalk.dim('─'.repeat(60)));
+    console.log(chalk.green('\n✓ Skill execution complete.\n'));
+  } catch (err) {
+    if (err.code === 'invalid_api_key') {
+      console.error(chalk.red('\n✗ Invalid OpenAI API key.'));
+      console.error(chalk.yellow('  Run: skillforge config set openai-key <your-key>\n'));
+    } else {
+      console.error(chalk.red(`\n✗ LLM Error: ${err.message}\n`));
+    }
+    process.exit(1);
+  }
+}

package/src/utils/scanner.js

@@ -0,0 +1,145 @@
+import { readdirSync, statSync, existsSync } from 'fs';
+import { join, extname, basename } from 'path';
+import { config, GLOBAL_SKILLS_DIR, GLOBAL_REPOS_DIR, getLocalDirs } from '../config/store.js';
+import { parseSkillFile } from '../engine/parser.js';
+
+/**
+ * Scan all installed repos + standalone skill directories (global & local).
+ * Returns an array of { repoName, filePath, meta, prompt, scope }
+ */
+export function scanAllSkills() {
+  const skills = [];
+
+  // 1. Scan registered repos from config
+  const repos = config.get('repos') || {};
+  for (const [repoName, repoInfo] of Object.entries(repos)) {
+    const repoSkills = scanRepoSkills(repoName, repoInfo.path, repoInfo.scope || 'global');
+    skills.push(...repoSkills);
+  }
+
+  // 2. Scan global standalone skills (~/.windsurf/skillforge/skills/)
+  const globalStandalone = scanDirectory(GLOBAL_SKILLS_DIR, 'global-skills', 'global');
+  skills.push(...globalStandalone);
+
+  // 3. Scan local standalone skills (.windsurf/skillforge/skills/ in cwd)
+  const local = getLocalDirs();
+  if (existsSync(local.SKILLS_DIR)) {
+    const localStandalone = scanDirectory(local.SKILLS_DIR, 'local-skills', 'local');
+    skills.push(...localStandalone);
+  }
+
+  // 4. Scan local repos (.windsurf/skillforge/repos/ in cwd)
+  if (existsSync(local.REPOS_DIR)) {
+    try {
+      const localRepoDirs = readdirSync(local.REPOS_DIR);
+      for (const dir of localRepoDirs) {
+        const dirPath = join(local.REPOS_DIR, dir);
+        if (statSync(dirPath).isDirectory()) {
+          const repoSkills = scanRepoSkills(dir, dirPath, 'local');
+          skills.push(...repoSkills);
+        }
+      }
+    } catch {
+      // skip
+    }
+  }
+
+  return skills;
+}
+
+/**
+ * Scan a single repo for skill files.
+ */
+export function scanRepoSkills(repoName, repoPath, scope = 'global') {
+  const skills = [];
+  const skillsDir = join(repoPath, 'skills');
+
+  // Look for .md files in skills/ directory, or root
+  const searchDirs = [skillsDir, repoPath];
+
+  for (const dir of searchDirs) {
+    try {
+      const files = readdirSync(dir);
+      for (const file of files) {
+        if (extname(file) !== '.md') continue;
+        if (file.toLowerCase() === 'readme.md') continue;
+
+        const filePath = join(dir, file);
+        if (!statSync(filePath).isFile()) continue;
+
+        try {
+          const { meta, prompt } = parseSkillFile(filePath);
+          if (meta.name || meta.description) {
+            skills.push({
+              repoName,
+              filePath,
+              skillName: meta.name || basename(file, '.md'),
+              meta,
+              prompt,
+              scope
+            });
+          }
+        } catch {
+          // Skip files that can't be parsed
+        }
+      }
+    } catch {
+      // Directory doesn't exist, skip
+    }
+  }
+
+  return skills;
+}
+
+/**
+ * Scan a standalone skills directory for .md files.
+ */
+function scanDirectory(dirPath, sourceName, scope) {
+  const skills = [];
+  try {
+    const files = readdirSync(dirPath);
+    for (const file of files) {
+      if (extname(file) !== '.md') continue;
+      if (file.toLowerCase() === 'readme.md') continue;
+
+      const filePath = join(dirPath, file);
+      if (!statSync(filePath).isFile()) continue;
+
+      try {
+        const { meta, prompt } = parseSkillFile(filePath);
+        if (meta.name || meta.description) {
+          skills.push({
+            repoName: sourceName,
+            filePath,
+            skillName: meta.name || basename(file, '.md'),
+            meta,
+            prompt,
+            scope
+          });
+        }
+      } catch {
+        // Skip
+      }
+    }
+  } catch {
+    // Directory doesn't exist
+  }
+  return skills;
+}
+
+/**
+ * Find a specific skill by name across all repos.
+ * Local skills take precedence over global ones.
+ */
+export function findSkill(skillName) {
+  const allSkills = scanAllSkills();
+  // Prefer local over global
+  const local = allSkills.find(
+    s => (s.skillName === skillName || s.meta.name === skillName) && s.scope === 'local'
+  );
+  if (local) return local;
+
+  return allSkills.find(
+    s => s.skillName === skillName || s.meta.name === skillName
+  );
+}