k-skill System Requirements: Node.js 18+ and Python 3.9+ Setup Guide

k-skill requires Node.js 18 or higher with npx, plus Python 3.9+ only for skills that use Python helpers.

The k-skill repository by NomaDamas is a hybrid codebase that combines Node.js (npm workspaces) with optional Python helpers to expose AI-driven skills. Runtime requirements are intentionally minimal—you can install the entire skill suite with a recent Node runtime and, where needed, a modern Python interpreter.

Core Requirements

Node.js Runtime (Required)

Node.js ≥ 18 is mandatory. This version provides a built-in global fetch implementation, which k-skill relies on instead of external HTTP libraries.

As documented in the repository README.md: "Node.js 18 이상과 npx만 있으면 됩니다" (only Node.js 18+ and npx are needed).

The k-skill-proxy package explicitly verifies this at runtime. In packages/k-skill-proxy/src/vworld.js at line 634, the source includes a fetch guard that checks for a native fetch implementation and polyfills only when necessary.

To verify your Node installation:

# Check Node version (must be ≥ 18)

node -v

# Verify global fetch exists (Node 18+ includes this automatically)

node -e "if (typeof fetch !== 'function') throw new Error('fetch missing')"

npm and npx (Required)

npm ships with Node 18—any recent version works. npx is required for the one-liner install commands that make k-skill distribution‑free:

# Install all skills globally

npx --yes skills add NomaDamas/k-skill --all -g

# Install a single skill

npx --yes skills add NomaDamas/k-skill --skill seoul-bike -g

Python Requirements (Conditional)

Python is only needed for skills that declare Python helpers. Most skills are pure Node.js.

Skill	Python Version	Dependencies
seoul-bike	Python 3 (stdlib only)	None
ticket-availability	Python 3.9+	httpx

The seoul-bike/instruction.md explicitly states: "Python 3 표준 라이브러리만 사용한다" (uses only Python 3 standard library). Meanwhile, ticket-availability/instruction.md specifies Python 3.9+ and requires installing httpx.

Verify and run Python helpers:

# Check Python version

python3 -V

# Install optional dependency for ticket-availability

python3 -m pip install httpx

# Run helper directly

python3 packages/k-skill-cli/skills/ticket-availability/scripts/ticket_availability.py --date 2024-08-04

Operating System Compatibility

k-skill runs on any OS that supports Node 18 and Python 3.9:

• Linux (validated in CI)
• macOS
• Windows

The .github/workflows/ci.yml CI workflow runs on Linux with both Node 18 and Python 3.9+ installed, confirming cross-platform viability.

Installation Verification Steps

1. Verify Node.js ≥ 18

   node -v  # Should print v18.x.x or higher
   

2. Confirm fetch availability

   node -e "console.log(typeof fetch)"  # Should print "function"
   

3. Check Python (if using Python-based skills)

   python3 -V  # Should print 3.9.x or higher
   

4. Install k-skill

   npx --yes skills add NomaDamas/k-skill --all -g

Architecture Notes

• Node side: Located under packages/* as an npm workspace. Each skill exports a CLI wrapper and optional library API.
• Python side: Located in scripts/ and individual skill directories (e.g., seoul-bike/scripts/). Invoked by Node wrappers only when declared.
• k-skill-proxy: AGPL‑3.0 licensed credential-free path that forwards API calls; assumes Node 18's fetch.

No additional system-wide dependencies—such as a Rust toolchain—are required for core functionality.

Summary

• Node.js 18+ with npx is the sole hard requirement for k-skill
• npm is included with Node; no separate installation needed
• Python 3.9+ is only required for specific skills with Python helpers
• Optional Python packages (httpx, mcp, OCR libraries) install per-skill on demand
• Cross-platform: Linux, macOS, and Windows supported
• No credential setup required—k-skill-proxy handles API forwarding

Frequently Asked Questions

Does k-skill work with Node.js 16 or 17?

No. k-skill requires Node.js 18 or higher because it depends on the native fetch API introduced in that version. The k-skill-proxy source code at packages/k-skill-proxy/src/vworld.js checks for this implementation at runtime. Running on older Node versions will trigger fetch-related errors unless you manually polyfill.

Is Python required for all k-skill features?

No. Python is only needed for skills that explicitly declare Python helpers. Many skills, including several in the core collection, run entirely on Node.js. Check the instruction.md file in each skill directory to determine Python requirements.

How do I install k-skill without global permissions?

Use npx with the --yes flag to run the installer without global installation. The skills CLI handles local or global placement based on your -g flag. The command npx --yes skills add NomaDamas/k-skill --all works in any directory where you have write permissions.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}