# How to Integrate k-skill into Custom Korean Web Service Automation

> Integrate k-skill into your Korean web service automation via CLI commands, direct module import, or the HTTP proxy. Automate your services efficiently with NomaDamas/k-skill.

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

---

**You can integrate k-skill into your Korean web service automation by invoking its CLI commands from your server, importing skill modules directly, or routing requests through the optional HTTP proxy server.**

The `k-skill` repository from NomaDamas provides a modular collection of Korean-focused automation skills that handle tasks like zip-code lookups, highway traffic monitoring, and legal document searches. Each skill is self-contained and returns structured JSON, making it straightforward to integrate k-skill into custom Korean web service automation pipelines using your preferred approach.

## Understanding the k-skill Architecture

Before integrating, understand how k-skill organizes its components. The architecture revolves around three core concepts that ensure consistency across all automation tasks.

### Skill Definition and Manifests

Every skill is declared via a [`skill.json`](https://github.com/NomaDamas/k-skill/blob/main/skill.json) manifest file that specifies the skill name, required inputs, optional credentials, and runtime environment (Node.js or Python). These manifests live at `*/skill.json` within the repository, such as [`zipcode-search/skill.json`](https://github.com/NomaDamas/k-skill/blob/main/zipcode-search/skill.json), and allow the `k-skill-cli` front-end to discover available capabilities automatically.

### Documentation and Implementation

Each skill includes human-readable documentation ([`instruction.md`](https://github.com/NomaDamas/k-skill/blob/main/instruction.md) for CLI usage and [`SKILL.md`](https://github.com/NomaDamas/k-skill/blob/main/SKILL.md) for feature guides) alongside the executable implementation. The actual automation logic resides in `*/scripts/*`—for example, [`zipcode-search/scripts/zipcode_search.py`](https://github.com/NomaDamas/k-skill/blob/main/zipcode-search/scripts/zipcode_search.py) contains the Python implementation for postal code lookups.

### CLI Discovery and Execution

The `k-skill-cli` discovers installed skills by reading their [`skill.json`](https://github.com/NomaDamas/k-skill/blob/main/skill.json) files and exposes them as commands formatted as `k-skill:<skill-name>`. When executed, the CLI loads the manifest, resolves credentials via the `k-skill-setup` helper, runs the appropriate script, and returns JSON on stdout for downstream consumption.

## Installation and Setup

To begin integrating k-skill into your web service, install the required skills and configure authentication.

### Installing Skills

Install the full skill set globally or select specific capabilities using the skills CLI:

```bash

# Install all available skills

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

# Or install a single skill (e.g., zip-code search)

npx --yes skills add NomaDamas/k-skill --skill zipcode-search -g

```

Detailed installation procedures are documented in the repository's [`docs/install.md`](https://github.com/NomaDamas/k-skill/blob/main/docs/install.md) and the top-level [`README.md`](https://github.com/NomaDamas/k-skill/blob/main/README.md).

### Configuring Credentials

Run the common setup helper to provision API keys, login cookies, or other secrets required by specific skills:

```bash
k-skill:k-skill-setup

```

This helper follows the credential handling policies defined in [`docs/setup.md`](https://github.com/NomaDamas/k-skill/blob/main/docs/setup.md), supporting environment variables, `.env` files, and user-provided secrets.

## Integration Methods

You can embed k-skill functionality into your web service using three distinct approaches depending on your architecture needs.

### CLI-Based Invocation

Spawn k-skill commands as subprocesses from your server application. This method requires no additional dependencies but incurs the overhead of process creation.

**Node.js Example:**

```javascript
const { execSync } = require('child_process');

function getZipCode(address) {
  // k-skill:zipcode-search expects a free-form address string
  const cmd = `k-skill:zipcode-search "${address}"`;
  const raw = execSync(cmd, { encoding: 'utf8' });
  return JSON.parse(raw);
}

// Express route implementation
app.get('/api/zip', (req, res) => {
  const result = getZipCode(req.query.q);
  res.json(result);
});

```

### Direct Script Import

Import the skill's implementation module directly into your application code for tighter error handling and better performance. This bypasses the CLI wrapper entirely.

**Python Example:**

```python

# Import from the skill's scripts directory

from zipcode_search import search_zipcode

def get_zipcode(address: str) -> dict:
    return search_zipcode(address)

# Flask endpoint

@app.route('/api/zip')
def zip_endpoint():
    address = request.args.get('q')
    return jsonify(get_zipcode(address))

```

This approach is ideal when you need fine-grained control over exceptions or want to avoid the latency of subprocess spawning.

### HTTP Proxy Approach

Deploy the optional `k-skill-proxy` server ([`packages/k-skill-proxy/src/server.js`](https://github.com/NomaDamas/k-skill/blob/main/packages/k-skill-proxy/src/server.js)) to expose skills via REST endpoints. This method suits microservice architectures that prefer HTTP interfaces over CLI integration.

**Example Request:**

```bash
curl -X POST https://k-skill-proxy.nomadamas.org/skill/zipcode-search \
     -H "Content-Type: application/json" \
     -d '{"address":"강남구 청담동"}'

```

The proxy forwards requests to the appropriate skill implementation and returns the JSON response, allowing any language or platform to consume k-skill capabilities via standard HTTP.

## Handling Output and Extending Skills

All k-skill commands return structured JSON payloads that your web service can process, store, or forward to clients. For example, the zip-code search returns objects like `{ "postalCode": "06100", "address": "...", "englishAddress": "..." }`.

Because each skill is self-contained within its own directory, you can customize behavior by forking the repository, modifying the logic in `scripts/*`, and updating the [`skill.json`](https://github.com/NomaDamas/k-skill/blob/main/skill.json) manifest to register your modified version under a different name. The CLI automatically discovers these changes upon restart.

## Summary

- **k-skill** is a modular collection of Korean automation tasks packaged as self-contained skills with JSON outputs.
- Install skills via `npx skills add NomaDamas/k-skill` and configure credentials using `k-skill-setup`.
- Integrate via **CLI invocation** (simplest), **direct script import** (best performance), or **HTTP proxy** (microservice-friendly).
- Each skill follows the [`skill.json`](https://github.com/NomaDamas/k-skill/blob/main/skill.json) manifest pattern and stores implementation logic in `*/scripts/*`.
- Customize skills by modifying the source scripts and updating the manifest files to register new variants.

## Frequently Asked Questions

### Can I use k-skill with programming languages other than Node.js and Python?

Yes. While the skills themselves are implemented in Node.js or Python, you can invoke them from any language that can spawn shell processes or make HTTP requests. Use the CLI-based method with `subprocess` or `system()` calls in languages like Go, Ruby, or Java, or deploy the HTTP proxy to enable REST access for any HTTP client.

### How does k-skill handle authentication for services requiring API keys?

The `k-skill-setup` helper resolves credentials through environment variables, `.env` files, or interactive prompts, as documented in [`docs/setup.md`](https://github.com/NomaDamas/k-skill/blob/main/docs/setup.md). Each skill's [`skill.json`](https://github.com/NomaDamas/k-skill/blob/main/skill.json) declares required credentials, and the CLI ensures these are available before executing the script. Your web service should set these environment variables before invoking skills or running the proxy server.

### What is the performance difference between CLI invocation and direct script import?

Direct script import offers significantly lower latency because it avoids process spawning overhead and JSON serialization through stdout. CLI invocation creates a new process per request, which adds milliseconds of overhead suitable for low-frequency operations but may bottleneck high-throughput services. For production environments handling many requests, prefer direct imports or the HTTP proxy with connection pooling.

### Where can I find documentation for a specific skill's input parameters?

Each skill includes an [`instruction.md`](https://github.com/NomaDamas/k-skill/blob/main/instruction.md) file documenting CLI usage examples and a [`SKILL.md`](https://github.com/NomaDamas/k-skill/blob/main/SKILL.md) file describing feature limitations, login requirements, and input formats. Additionally, the [`skill.json`](https://github.com/NomaDamas/k-skill/blob/main/skill.json) manifest formally declares all required and optional inputs. Refer to these files within the skill's directory—such as [`zipcode-search/SKILL.md`](https://github.com/NomaDamas/k-skill/blob/main/zipcode-search/SKILL.md)—for authoritative parameter specifications.