SkillForge

Expose TypeScript skills as MCP tools in 5 minutes.

MCP Quick Start | Security Model | API Reference | Experimental Features

---

SkillForge is a lightweight framework for registering TypeScript functions as AI agent tools. It exposes them via the Model Context Protocol (MCP) so Claude Desktop, Cursor, VS Code, and any MCP client can discover and execute them directly. Credentials are AES-256 encrypted. Skills auto-discover from a directory. Zero config required.

---

MCP Quick Start

Add SkillForge to Claude Desktop:

{
  "mcpServers": {
    "skillforge": {
      "command": "npx",
      "args": ["-y", "@ganeshvardhineedi/skillforge", "serve-mcp"]
    }
  }
}

Claude now has access to all your skills as native tools. Same pattern works for Cursor (.cursor/mcp.json) and VS Code.

Generate keys and start the server:

export SKILLFORGE_ENCRYPTION_KEY=$(node -e "console.log(require('crypto').randomBytes(32).toString('hex'))")
export SKILLFORGE_SECRET=$(node -e "console.log(require('crypto').randomBytes(32).toString('hex'))")
npx skillforge serve 3456

Open http://localhost:3456/ui/v2 -- login with admin / changeme.

30-second embed

import { SkillForge } from "@ganeshvardhineedi/skillforge";

const sf = new SkillForge();
sf.startServer(3456);
// Skills auto-discover, API starts, UI is ready.

---

Features

• MCP Server -- stdio and HTTP transports, any MCP client
• SKILL.md -- define HTTP skills in markdown, no code required
• AES-256 Credentials -- encrypted at rest, never in logs or MCP responses
• Feature Flags -- FNV-1a hashing, rollout %, user targeting
• Multi-User Auth -- bcryptjs passwords, JWT tokens, role-based access
• Auto-generated UI + OpenAPI -- forms from JSON Schema, Swagger-ready spec

---

Security

Layer	Protection
Credentials	AES-256-CBC encryption, never exposed via MCP or logs
MCP Responses	13 regex patterns strip API keys, tokens, secrets
Network	HTTPS required for SKILL.md, private IP blocking, DNS rebinding guard
Auth	bcryptjs hashing, JWT with expiration, RBAC (admin/operator/viewer)
SSE	Short-lived tokens (5min), connection limits per user
Rate Limiting	Global + per-endpoint limits, MCP tool call rate cap

See SECURITY.md for the full security policy and reporting process.

---

Bundled Skills

Skill	Description
weather	Weather via OpenWeatherMap
github	Repos, issues, PRs
gmail	Read, search, send via Google OAuth
telegram	Messages, groups, polls
trading	Crypto signals, backtesting
hive	Docker container monitoring
stripe	Payments, subscriptions, refunds
slack	Messages, channels, files, reactions
notion	Search, read, create, update pages
jira	Issues, projects, JQL search
twilio	SMS, calls, phone lookup
memory	Persistent action history

---

Adding a Skill

TypeScript

import type { ISkill } from "@ganeshvardhineedi/skillforge";

export default {
  name: "my-service",
  description: "My API integration",
  version: "1.0.0",
  actions: [
    {
      name: "do_thing",
      description: "Do the thing",
      inputSchema: {
        type: "object",
        properties: { query: { type: "string" } },
        required: ["query"],
      },
      run: async (params, ctx) => {
        const apiKey = await ctx.getCredential("api_key");
        return { result: "done" };
      },
    },
  ],
  triggers: [],
  credentials: [{ name: "api_key", type: "apikey", requiredFields: ["key"] }],
  schema: { type: "object", properties: {} },
} satisfies ISkill;

SKILL.md (no code)

Define HTTP skills in markdown with YAML frontmatter. See SKILL.md Format.

Decorator helper

import { toSkill, actionFromFunction } from "@ganeshvardhineedi/skillforge";

const forecast = actionFromFunction(
  async (params: { city: string }) => ({ temp: 72 }),
  { name: "get_forecast", description: "Get weather forecast" }
);

export default toSkill("weather", "Weather API", [forecast]);

---

CLI

npx skillforge list              # List registered skills
npx skillforge validate          # Validate skill schemas
npx skillforge doctor            # Check setup health
npx skillforge serve 3456        # Start HTTP server
npx skillforge serve-mcp         # Start MCP server (stdio)
npx skillforge load-md <path>    # Load skills from SKILL.md
npx skillforge run <skill> <action> [json-params]

---

Environment Variables

Variable	Required	Description
SKILLFORGE_SECRET	Admin features	JWT signing secret
SKILLFORGE_ENCRYPTION_KEY	Credentials	AES-256 key (min 16 chars)
SKILLFORGE_ADMIN_PASSWORD	No	Default admin password (default: changeme)
SKILLFORGE_PORT	No	Server port (default: 3456)
SKILLFORGE_CORS_ORIGIN	No	Comma-separated allowed origins
SKILLFORGE_MCP_RATE_LIMIT	No	Max MCP tool calls/min (default: 100)

node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

---

Architecture

See docs/ARCHITECTURE.md for the full system diagram and module breakdown.

---

API Reference

See docs/API.md for the complete endpoint reference, or access the auto-generated spec at /api/openapi.json when the server is running.

---

Hermes Integration

SkillForge integrates with the Hermes agent framework as a local-first MCP tool gateway, providing x-skillforge metadata for safe auto-run decisions. See docs/integrations/hermes.md.

---

Experimental Features

These features work but their APIs may change:

• Goals -- Autonomous multi-step goal execution with budget tracking
• Memory -- Persistent action history, observations, timeline queries
• Bridge Inventory -- Import tools from external agent frameworks (Hermes, OpenClaw)

See docs/EXPERIMENTAL.md for details and current stability status.

---

Compatibility

Requirement	Version
Node.js	>= 20.0.0
TypeScript	5.3+
MCP Protocol	Compatible (stdio + HTTP)
Module System	ESM ("type": "module")

---

License

MIT (c) 2026 Ganesh Vardhineedi