# How to Use the k-skill API: CLI and HTTP Proxy Methods Explained

> Learn to use the k-skill API with CLI and HTTP proxy methods. Access Korean public data seamlessly via this Fastify-based proxy handling auth, caching, and rate-limiting.

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

---

**The k-skill API provides a unified interface to Korean public data sources through a Fastify-based proxy server that handles authentication, caching, and rate-limiting automatically.**

The k-skill API is a collection of thin wrappers around public Korean data services. Built by NomaDamas, it abstracts away the complexity of dealing with diverse upstream APIs by providing a single, consistent interface. Whether you prefer command-line tools or direct HTTP calls, the API normalizes requests, injects secrets securely, and returns sanitized JSON payloads.

## Architecture Overview

Understanding how the k-skill API works helps you choose the right integration path. The system consists of three main layers working together.

### CLI and Skill Dispatcher

The `k-skill` CLI resolves skill names to executable scripts or proxy endpoints. When you run a command, it either executes a local helper or forwards the request to the proxy server. This layer is ideal for automation scripts and AI agents that need reliable data access.

### Proxy Server Core

The heart of the system lives in [`packages/k-skill-proxy/src/server.js`](https://github.com/NomaDamas/k-skill/blob/main/packages/k-skill-proxy/src/server.js). This Fastify-based server implements:

- **`makeConfig`** – Reads environment variables and builds route configurations
- **`createMemoryCache`** – Caches responses keyed by SHA-256 hash of request payload
- **`buildRateLimiter`** – Tracks per-IP request counts to prevent abuse
- **Normalization helpers** – Functions like `trimOrNull`, `parseInteger`, and `normalizeFineDustQuery` ensure valid parameters reach upstream APIs

Each route follows a consistent pattern: normalize parameters, proxy the request with injected credentials, cache successful responses, and return sanitized data.

### Hosted vs. Local Deployment

| Deployment | URL | Use Case |
|------------|-----|----------|
| **Hosted proxy** | `https://k-skill-proxy.nomadamas.org` | Quick start, no API keys needed |
| **Local proxy** | `http://localhost:4020` | Development, custom secrets, debugging |

The hosted instance at `k-skill-proxy.nomadamas.org` is maintained by the project operators. It contains pre-configured secrets for most skills, so you can call endpoints immediately without managing credentials.

## Method 1: Using the k-skill CLI

The CLI is the recommended approach for agents and automation workflows. It handles skill resolution, argument passing, and output formatting.

### Installation and Setup

```bash

# Install all k-skill abilities globally (run once)

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

```

This command downloads skill definitions and helper scripts to your local environment.

### Executing a Skill

```bash

# Search Korean law using the built-in script

k-skill exec korean-law-search scripts/search_law.py -- --query "민법"

```

The CLI resolves `korean-law-search` to its implementation, passes your arguments through, and prints the JSON response. The `--` separator ensures flags are forwarded to the skill script rather than consumed by the CLI itself.

## Method 2: Direct HTTP Requests to the Hosted Proxy

For applications that need simple HTTP access, call the hosted proxy directly. No API keys required—the proxy injects operator-managed secrets.

### Fine Dust Information Endpoint

```bash
curl -fsS --get 'https://k-skill-proxy.nomadamas.org/v1/fine-dust/info' \
  --data-urlencode 'regionHint=서울' \
  --data-urlencode 'stationName=종로구청'

```

This endpoint queries the Air Korea service through `proxyAirKoreaRequest`, which normalizes parameters, adds the backend API key, and returns standardized air quality data.

### Korean Law Search Endpoint

```bash
curl -fsS --get 'https://k-skill-proxy.nomadamas.org/v1/korean-law/search' \
  --data-urlencode 'query=민법' \
  --data-urlencode 'pageNo=1' \
  --data-urlencode 'numOfRows=10'

```

The proxy validates your parameters with `normalizeData4LibraryIsbn13`-style helpers, contacts `open.law.go.kr`, and returns a clean JSON envelope with search results.

## Method 3: JavaScript/Node.js Integration

Modern applications can consume the k-skill API using standard fetch patterns.

```javascript
import fetch from 'node-fetch';

async function koreanLawSearch(term) {
  const url = new URL('https://k-skill-proxy.nomadamas.org/v1/korean-law/search');
  url.searchParams.set('query', term);
  url.searchParams.set('pageNo', '1');
  url.searchParams.set('numOfRows', '5');

  const resp = await fetch(url);
  const data = await resp.json();
  console.log(data);
}

koreanLawSearch('민법');

```

This request flows through the same Fastify pipeline as CLI and curl calls: normalization in `normalizeFineDustQuery` (or equivalent), rate-limiting via `buildRateLimiter`, and caching through `createMemoryCache`.

## Method 4: Local Proxy with Custom Secrets

Some skills require user-provided credentials. Run the proxy locally to inject your own API keys.

### Setting Up Environment Variables

```bash

# Obtain from https://www.data.go.kr/ (Air Korea service)

export AIR_KOREA_OPEN_API_KEY=YOUR_KEY_HERE

```

Never commit secrets to version control. The proxy reads these via `buildConfig` in [`server.js`](https://github.com/NomaDamas/k-skill/blob/main/server.js).

### Starting the Local Proxy

```bash

# Start proxy on default port 4020

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

```

### Calling the Local Instance

```bash
curl -fsS --get 'http://localhost:4020/v1/fine-dust/info' \
  --data-urlencode 'regionHint=부산' \
  --data-urlencode 'stationName=해운대'

```

The `proxyAirKoreaRequest` function injects your `AIR_KOREA_OPEN_API_KEY` into the request to `apis.data.go.kr`, keeping your credentials server-side.

## Error Handling and Response Format

The k-skill API wraps all errors into a consistent envelope. Functions like `isFailureResponse` and `getSeoulOpenApiSemanticError` in [`server.js`](https://github.com/NomaDamas/k-skill/blob/main/server.js) ensure you receive predictable error objects:

```json
{
  "error": "UPSTREAM_ERROR",
  "message": "Invalid station name provided",
  "upstream": "AirKorea API returned 400"
}

```

Successful responses contain the normalized data directly or in a `data` field, depending on the skill.

## Key Source Files and References

| File | Purpose |
|------|---------|
| [`packages/k-skill-proxy/src/server.js`](https://github.com/NomaDamas/k-skill/blob/main/packages/k-skill-proxy/src/server.js) | Core Fastify server, normalization, caching, rate-limiting |
| [`README.md`](https://github.com/NomaDamas/k-skill/blob/main/README.md) | Skill catalog and quick-start commands |
| [`docs/install.md`](https://github.com/NomaDamas/k-skill/blob/main/docs/install.md) | CLI installation and `k-skill-setup` configuration |
| [`docs/features/k-skill-proxy.md`](https://github.com/NomaDamas/k-skill/blob/main/docs/features/k-skill-proxy.md) | Hosted proxy documentation and security details |
| [`docs/setup.md`](https://github.com/NomaDamas/k-skill/blob/main/docs/setup.md) | Credential resolution order and environment setup |
| [`packages/k-skill-proxy/src/airkorea.js`](https://github.com/NomaDamas/k-skill/blob/main/packages/k-skill-proxy/src/airkorea.js), [`korean-law.js`](https://github.com/NomaDamas/k-skill/blob/main/korean-law.js) | Individual upstream API implementations |

## Summary

- **CLI method**: Install with `npx skills add NomaDamas/k-skill --all -g`, then run `k-skill exec <skill-name>`

- **Hosted proxy**: Call `https://k-skill-proxy.nomadamas.org/v1/{endpoint}` with URL-encoded parameters—no API keys needed

- **JavaScript integration**: Standard `fetch` to hosted endpoints with automatic caching and rate-limiting

- **Local proxy**: Export secrets like `AIR_KOREA_OPEN_API_KEY`, run [`server.js`](https://github.com/NomaDamas/k-skill/blob/main/server.js) locally, call `localhost:4020`

- **Core architecture**: Fastify server in [`packages/k-skill-proxy/src/server.js`](https://github.com/NomaDamas/k-skill/blob/main/packages/k-skill-proxy/src/server.js) handles normalization via helpers like `normalizeFineDustQuery`, caching via `createMemoryCache`, and proxying via functions like `proxyAirKoreaRequest`

## Frequently Asked Questions

### What is the difference between the hosted proxy and running the proxy locally?

The hosted proxy at `k-skill-proxy.nomadamas.org` is pre-configured with operator-managed API keys for most services, requiring no setup from you. Running the proxy locally lets you inject your own credentials via environment variables and is useful for development, debugging, or accessing services that require personal API keys. Both use identical code from [`packages/k-skill-proxy/src/server.js`](https://github.com/NomaDamas/k-skill/blob/main/packages/k-skill-proxy/src/server.js).

### Do I need to register for API keys to use the k-skill API?

For the hosted proxy, no—most endpoints work without user-provided keys. For local proxy deployment, some skills like fine-dust queries require `AIR_KOREA_OPEN_API_KEY` from data.go.kr. Check [`docs/setup.md`](https://github.com/NomaDamas/k-skill/blob/main/docs/setup.md) for credential requirements per skill.

### How does the k-skill API handle rate limits and caching?

The proxy uses `buildRateLimiter` to track per-IP request counts and `createMemoryCache` to store successful responses by SHA-256 hash of the request. This protects upstream services and improves response times for repeated queries. Cached responses bypass upstream calls entirely.

### What happens when an upstream API returns an error?

The proxy catches failures through `isFailureResponse` and transforms them into a consistent JSON error envelope with `error`, `message`, and `upstream` fields. Your application receives predictable error handling regardless of which Korean data source failed.