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

> Build k-skill from source with this complete installation guide. Clone the repo, install dependencies, and compile the monorepo effortlessly. Perfect for contributors.

- Repository: [NomaDamas/k-skill](https://github.com/NomaDamas/k-skill)
- Tags: how-to-guide
- Published: 2026-08-04

---

**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`](https://github.com/NomaDamas/k-skill/blob/main/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:

```bash
node --version

```

## Step 1: Clone the k‑skill Repository

Download the source code from GitHub:

```bash
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:

```bash
npm install

```

This command leverages the **npm workspaces** configuration declared in [`package.json`](https://github.com/NomaDamas/k-skill/blob/main/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:

```bash
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:

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

```

## Step 4: Verify the Build With Tests

Run the comprehensive CI script to validate your build:

```bash
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:

```bash
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:

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

```

## Optional: Global Installation

For system-wide availability, install the CLI globally:

```bash
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`](https://github.com/NomaDamas/k-skill/blob/main/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`](https://github.com/NomaDamas/k-skill/blob/main/scripts/generate-skill-stubs.js)) |
| [`packages/k-skill-proxy/src/server.js`](https://github.com/NomaDamas/k-skill/blob/main/packages/k-skill-proxy/src/server.js) | Express proxy server routing calls to public APIs |
| [`docs/install.md`](https://github.com/NomaDamas/k-skill/blob/main/docs/install.md) | Official installation documentation |
| `scripts/` | CI helpers, stub generation, testing utilities |
| [`SKILL.md`](https://github.com/NomaDamas/k-skill/blob/main/SKILL.md) (per package) | Declarative skill metadata consumed by the CLI |

## Complete Build Workflow Example

```bash

# 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`](https://github.com/NomaDamas/k-skill/blob/main/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`](https://github.com/NomaDamas/k-skill/blob/main/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`](https://github.com/NomaDamas/k-skill/blob/main/package.json) and [`SKILL.md`](https://github.com/NomaDamas/k-skill/blob/main/SKILL.md) following existing patterns, then run `npm run build`. The CLI generator ([`scripts/generate-skill-stubs.js`](https://github.com/NomaDamas/k-skill/blob/main/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`](https://github.com/NomaDamas/k-skill/blob/main/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.