How to Build k‑skill From Source: Complete Installation Guide for Contributors

Clone the repository, run npm install and npm run build to compile the entire k‑skill monorepo from source—no manual package linking required.

The k‑skill project by NomaDamas is a monorepo housing dozens of AI agent skill packages and a shared CLI runtime. It uses npm workspaces to link internal dependencies automatically, making local builds straightforward for contributors who want to modify skills or add new capabilities.

Prerequisites for Building k‑skill

Before starting, ensure your environment meets these requirements defined in the root package.json:

• Node.js ≥ 18 (required by the workspace configuration)
• Git for cloning
• A package runner such as npx (included with Node), pnpm dlx, or bunx

Verify your Node version:

node --version

Step 1: Clone the k‑skill Repository

Download the source code from GitHub:

git clone https://github.com/NomaDamas/k-skill.git
cd k-skill

The repository structure follows standard monorepo conventions with packages/ containing all publishable workspaces.

Step 2: Install Workspace Dependencies

Run a single install command to pull dependencies for all packages:

npm install

This command leverages the npm workspaces configuration declared in package.json ("workspaces": ["packages/*"]). It creates a hoisted node_modules folder and automatically links internal packages—no npm link or manual symlinking required.

Step 3: Build All Packages From Source

Compile every package in the workspace:

npm run build

This invokes npm run build --workspaces --if-present, walking each package that defines a build script. Most skill packages contain TypeScript compilation steps; the CLI and runtime packages bundle their assets.

For faster iteration when modifying only one package, build selectively:

npm run build --workspace @nomadamas/k-skill

Step 4: Verify the Build With Tests

Run the comprehensive CI script to validate your build:

npm run ci

The npm run ci command executes:

• Linting
• TypeScript type-checking
• Unit tests (JavaScript via node --test and Python via unittest)
• Dry-run npm pack for each workspace to verify packaging

This ensures the repository remains release-ready after your changes.

Step 5: Use the CLI Locally (No Global Install)

After building k‑skill from source, invoke skills directly without publishing:

npx -y @nomadamas/k-skill@0 instruct <skill-name>
npx -y @nomadamas/k-skill@0 exec <skill-name> <script> -- <args>

The CLI automatically resolves locally built packages from the workspace.

Example: run the Korean law search skill:

npx -y @nomadamas/k-skill@0 instruct korean-law-search

Optional: Global Installation

For system-wide availability, install the CLI globally:

npm install -g @nomadamas/k-skill@0
k-skill list
k-skill instruct srt-booking

This pulls the built version from your local workspace into global node_modules.

Key Directories and Files in the k‑skill Source

Understanding the repository layout helps you navigate and contribute effectively:

Path	Purpose
package.json (root)	Workspace definition, Node ≥18 requirement, global npm scripts
packages/*	Individual skill packages and shared runtime modules
packages/k-skill-cli/	Generated CLI entry point (created by scripts/generate-skill-stubs.js)
packages/k-skill-proxy/src/server.js	Express proxy server routing calls to public APIs
docs/install.md	Official installation documentation
scripts/	CI helpers, stub generation, testing utilities
SKILL.md (per package)	Declarative skill metadata consumed by the CLI

Complete Build Workflow Example

# 1. Clone and enter directory

git clone https://github.com/NomaDamas/k-skill.git && cd k-skill

# 2. Install all dependencies

npm install

# 3. Build entire workspace

npm run build

# 4. Run full verification

npm run ci

# 5. Test a skill locally

npx -y @nomadamas/k-skill@0 instruct korean-weather

Summary

• k‑skill uses npm workspaces to manage dozens of skill packages under a single build system
• npm install resolves and links all internal dependencies automatically
• npm run build compiles every workspace package with TypeScript or bundlers
• npm run ci validates linting, types, tests, and packaging
• Local CLI execution via npx requires no global install or npm publishing
• Each skill package contains a SKILL.md file that the CLI reads to expose capabilities

Frequently Asked Questions

What Node.js version is required to build k‑skill?

Node.js 18 or higher is required. The root package.json enforces this via the "engines" field, and npm will warn if your version is incompatible.

Do I need to publish packages to npm before testing them locally?

No. The npm workspace configuration links internal packages automatically. After running npm run build, use npx -y @nomadamas/k-skill@0 to execute the locally built CLI and skills without publishing.

How do I add a new skill to the k‑skill repository?

Create a new directory under packages/, add a package.json and SKILL.md following existing patterns, then run npm run build. The CLI generator (scripts/generate-skill-stubs.js) will pick up your skill automatically. Re-run npm run ci to verify integration.

What is k‑skill‑proxy and why does it exist?

k-skill-proxy (located at packages/k-skill-proxy/src/server.js) is a lightweight Express server that routes API calls through free public endpoints with optional authentication layers. Many skills depend on it to access external services without exposing API keys directly in skill code.

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