# How to Configure k-skill: Complete Setup Guide for the Workspace-Based Skill System

> Configure k-skill effortlessly with our complete setup guide. Learn to bootstrap the CLI, generate skill stubs, and secure your API credentials for the workspace-based skill system.

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

---

**k-skill configuration requires bootstrapping the CLI, generating skill stubs from [`skill.json`](https://github.com/NomaDamas/k-skill/blob/main/skill.json) manifests, and setting up a secure `~/.config/k-skill/secrets.env` file with API credentials.**

k-skill is a modular, workspace-based system developed by NomaDamas that combines a CLI front-end, autonomous skill packages, and an optional proxy server for free-API access. Understanding how to configure k-skill properly ensures your skills can resolve credentials, route requests, and execute across multiple runtimes without hard-coded secrets.

## Configuration Architecture Overview

k-skill organizes configuration across **three distinct layers**. Each layer has specific responsibilities, file locations, and key settings.

### Layer 1: CLI/Runtime Configuration

The CLI layer boots the skill system, discovers installed skills, and forwards requests to the appropriate runtime (Node.js, Python, or browser).

| Aspect | Details |
|--------|---------|
| **Location** | `packages/k-skill-cli/` — the core CLI package |
| **Bootstrap** | `npm install` at repository root |
| **Regeneration** | Run `npm run generate:skill-stubs` after editing [`skill.json`](https://github.com/NomaDamas/k-skill/blob/main/skill.json) or [`instruction.md`](https://github.com/NomaDamas/k-skill/blob/main/instruction.md) |
| **Guidelines** | Follow *Unified CLI skill instruction rules* in [`AGENTS.md`](https://github.com/NomaDamas/k-skill/blob/main/AGENTS.md) |

### Layer 2: Skill Definitions

Each autonomous capability lives in its own folder with standardized files.

| File | Purpose |
|------|---------|
| [`skill.json`](https://github.com/NomaDamas/k-skill/blob/main/skill.json) | Declares skill name, profile, required environment variables, and runtime |
| [`instruction.md`](https://github.com/NomaDamas/k-skill/blob/main/instruction.md) | Describes inputs, outputs, and external service requirements |
| `scripts/` | Optional folder for custom execution logic (e.g., [`zipcode-search/scripts/zipcode_search.py`](https://github.com/NomaDamas/k-skill/blob/main/zipcode-search/scripts/zipcode_search.py)) |

Example: [`zipcode-search/skill.json`](https://github.com/NomaDamas/k-skill/blob/main/zipcode-search/skill.json) defines the postal code lookup capability.

### Layer 3: Credential and Proxy Configuration

Secrets follow a strict **three-level precedence system**:

1. **Already-injected environment variables** (highest priority)
2. **Host vault** (Dolshoi) for enterprise deployments
3. **Local dotenv file** `~/.config/k-skill/secrets.env` with mode `0600` (default for standalone setups)

The proxy server at [`packages/k-skill-proxy/src/server.js`](https://github.com/NomaDamas/k-skill/blob/main/packages/k-skill-proxy/src/server.js) forwards requests requiring API keys and returns `503 upstream_not_configured` when a key is missing.

## Step-by-Step k-skill Configuration Workflow

### 1. Bootstrap the CLI and Workspace

After cloning the repository, install all workspace packages:

```bash
git clone https://github.com/NomaDamas/k-skill.git
cd k-skill
npm install

```

This creates the `node_modules` hierarchy across `packages/*`.

### 2. Generate and Sync Skill Stubs

Whenever you modify [`skill.json`](https://github.com/NomaDamas/k-skill/blob/main/skill.json) or [`instruction.md`](https://github.com/NomaDamas/k-skill/blob/main/instruction.md), regenerate the CLI adapters:

```bash
npm run generate:skill-stubs
npm run sync:cli-skills

```

The `sync:cli-skills` command copies top-level skill definitions into `packages/k-skill-cli/skills/`.

### 3. Create the Secrets File

Use the built-in **k-skill-setup** skill for first-time credential configuration:

```bash
npx -y @nomadamas/k-skill@0 exec k-skill-setup scripts/setup.sh -- config-check

```

This command:
- Creates `~/.config/k-skill/secrets.env` if absent
- Sets file mode to `0600` (owner read/write only)
- Prompts for required API keys

Alternatively, create the file manually:

```bash
mkdir -p ~/.config/k-skill
cat > ~/.config/k-skill/secrets.env <<'EOF'
DATA_GO_KR_API_KEY=YOUR_DATA_GO_KEY
NAVER_SEARCH_CLIENT_ID=YOUR_NAVER_ID
NAVER_SEARCH_CLIENT_SECRET=YOUR_NAVER_SECRET
KAKAO_REST_API_KEY=YOUR_KAKAO_KEY
EOF
chmod 600 ~/.config/k-skill/secrets.env

```

### 4. Export Required Environment Variables

Add entries for any skill needing external API access:

```bash
echo "DATA_GO_KR_API_KEY=your-key-here" >> ~/.config/k-skill/secrets.env

```

Each skill's [`skill.json`](https://github.com/NomaDamas/k-skill/blob/main/skill.json) declares its required environment variables.

### 5. Start the Proxy Server (Optional)

For free-API routes requiring key management, caching, or rate-limiting:

```bash
node packages/k-skill-proxy/src/server.js

```

The proxy:
- Reads credentials from the same secrets file
- Exposes routes under `http://localhost:3000/v1/...`
- Returns `503 upstream_not_configured` for missing keys

Enable a route by setting its associated environment variable (e.g., `NAVER_SEARCH_CLIENT_ID`). Reference the proxy README at [`packages/k-skill-proxy/README.md`](https://github.com/NomaDamas/k-skill/blob/main/packages/k-skill-proxy/README.md) for route-specific configuration.

### 6. Execute Skills

Run a skill through the CLI:

```bash
npx -y @nomadamas/k-skill@0 exec zipcode-search scripts/zipcode_search.py -- "서울 강남구"

```

The CLI resolves credentials from the secrets file, contacts the appropriate endpoint (direct or via proxy), and returns results.

## Key Configuration Files Reference

| File Path | Role |
|-----------|------|
| `packages/k-skill-cli/` | Core CLI implementation for skill discovery and command routing |
| [`packages/k-skill-proxy/src/server.js`](https://github.com/NomaDamas/k-skill/blob/main/packages/k-skill-proxy/src/server.js) | Proxy server with API-key handling, caching, and rate-limiting |
| [`k-skill-setup/skill.json`](https://github.com/NomaDamas/k-skill/blob/main/k-skill-setup/skill.json) | Setup skill definition that automates secrets file creation |
| `*/skill.json` (e.g., [`zipcode-search/skill.json`](https://github.com/NomaDamas/k-skill/blob/main/zipcode-search/skill.json)) | Per-skill manifest with environment variable requirements |
| `*/instruction.md` | Human-readable skill specifications |
| `~/.config/k-skill/secrets.env` | Secure local credential store (mode `0600` required) |
| [`AGENTS.md`](https://github.com/NomaDamas/k-skill/blob/main/AGENTS.md) | Repository-wide CLI generation and release guidelines |
| [`.github/workflows/ci.yml`](https://github.com/NomaDamas/k-skill/blob/main/.github/workflows/ci.yml) | CI pipeline running `npm run ci` for package verification |

## Summary

- **k-skill configuration** spans three layers: CLI/runtime, skill definitions, and credential management
- **Bootstrap** with `npm install`, then **regenerate stubs** with `npm run generate:skill-stubs` after any [`skill.json`](https://github.com/NomaDamas/k-skill/blob/main/skill.json) changes
- **Store secrets** exclusively in `~/.config/k-skill/secrets.env` with `chmod 600` permissions—never hard-code API keys
- **Use the k-skill-setup skill** or manual creation to initialize credential storage
- **Enable proxy routes** by setting corresponding environment variables; the proxy returns `503 upstream_not_configured` for unconfigured services
- **Reference skill manifests** at [`skill.json`](https://github.com/NomaDamas/k-skill/blob/main/skill.json) to identify required environment variables per capability

## Frequently Asked Questions

### Where does k-skill store API credentials?

k-skill searches for credentials in three locations, in order: (1) already-injected environment variables, (2) the host vault (Dolshoi) for enterprise setups, and (3) the local file `~/.config/k-skill/secrets.env`. The local file must have mode `0600` and is created automatically by the `k-skill-setup` skill.

### How do I regenerate CLI adapters after modifying a skill?

Run `npm run generate:skill-stubs` to update generated adapters, then `npm run sync:cli-skills` to copy skill definitions into `packages/k-skill-cli/skills/`. These commands are defined in the root [`package.json`](https://github.com/NomaDamas/k-skill/blob/main/package.json) and documented in [`AGENTS.md`](https://github.com/NomaDamas/k-skill/blob/main/AGENTS.md).

### What happens if the proxy server cannot find an API key?

The proxy at [`packages/k-skill-proxy/src/server.js`](https://github.com/NomaDamas/k-skill/blob/main/packages/k-skill-proxy/src/server.js) returns HTTP `503 upstream_not_configured` when a requested route requires an API key that is not set in the environment or secrets file. Check the specific skill's [`skill.json`](https://github.com/NomaDamas/k-skill/blob/main/skill.json) for required variable names.

### Can I run k-skill without the proxy server?

Yes. The proxy is optional and only required for skills that need free-API access with key management, caching, or rate-limiting. Direct API calls from skills work when credentials are available through environment variables or the secrets file.