# Understanding the Repository Structure of k-skill: A Complete Monorepo Guide

> Explore the k-skill monorepo structure. Discover how AI agent skills, shared libraries, and CI infrastructure are organized using npm workspaces for efficient development.

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

---

**The k-skill repository is organized as a monorepo that groups independent AI agent skills with shared libraries, CI infrastructure, and deployment assets, using npm workspaces to manage reusable packages alongside individual skill implementations.**

The **k-skill** repository by NomaDamas serves as a centralized hub for AI agent capabilities. Understanding the repository structure of k-skill is essential for developers looking to contribute new skills, consume shared libraries, or deploy the proxy infrastructure. The codebase follows a clear separation between reusable tooling in `packages/`, individual skill implementations at the root level, and supporting infrastructure in dedicated configuration directories.

## Root-Level Configuration and Metadata

The repository root contains project-wide definitions that govern the entire monorepo. Key files include [`README.md`](https://github.com/NomaDamas/k-skill/blob/main/README.md) for project overview, `LICENSE` for the open-source terms, and [`CONTRIBUTING.md`](https://github.com/NomaDamas/k-skill/blob/main/CONTRIBUTING.md) for contribution guidelines. The root [`package.json`](https://github.com/NomaDamas/k-skill/blob/main/package.json) defines the npm workspace configuration, enabling the monorepo structure by declaring `packages/*` as workspace members.

TypeScript compilation settings live in [`tsconfig.json`](https://github.com/NomaDamas/k-skill/blob/main/tsconfig.json) at the root, ensuring consistent type checking across all Node.js-based packages and skills. This centralized configuration allows individual skill directories to inherit compiler options without duplicating settings.

## CI/CD and Automation Infrastructure

The `.github/workflows/` directory houses GitHub Actions pipelines that maintain code quality across the monorepo. The [`ci.yml`](https://github.com/NomaDamas/k-skill/blob/main/ci.yml) workflow runs automated tests across all skill folders and packages, while [`release-npm.yml`](https://github.com/NomaDamas/k-skill/blob/main/release-npm.yml) and [`release-python.yml`](https://github.com/NomaDamas/k-skill/blob/main/release-python.yml) handle language-specific publishing. A dedicated workflow for Manus.ai bundling ensures compatibility with that platform.

Version management uses the Changesets workflow, configured in [`.changeset/config.json`](https://github.com/NomaDamas/k-skill/blob/main/.changeset/config.json). This system coordinates version bumping across the npm packages in the `packages/` directory, ensuring synchronized releases for interdependent libraries.

## Plugin and Documentation Assets

The `.claude-plugin/` directory contains files exposing the repository as a Claude-Code plugin, including [`plugin.json`](https://github.com/NomaDamas/k-skill/blob/main/plugin.json) for the manifest and marketplace configuration. This integration allows Claude to discover and invoke skills directly from the repository structure.

Human-readable documentation resides in `docs/`, containing installation guides ([`install.md`](https://github.com/NomaDamas/k-skill/blob/main/install.md)), feature references ([`features/kbo-results.md`](https://github.com/NomaDamas/k-skill/blob/main/features/kbo-results.md)), security policies, release processes, and roadmap documents. These files provide end-user guidance separate from the developer-focused instructions embedded within individual skill directories.

## Reusable Node Packages

The `packages/` directory implements npm workspaces containing self-contained libraries that skills can depend on. Each package maintains its own `src/`, `test/`, and [`README.md`](https://github.com/NomaDamas/k-skill/blob/main/README.md), following standard Node.js project structure.

Key packages include:
- **`k-skill-proxy`** – Core proxy server implementation found in [`packages/k-skill-proxy/src/server.js`](https://github.com/NomaDamas/k-skill/blob/main/packages/k-skill-proxy/src/server.js), providing free-API access for skills that require external data sources.
- **`k-skill-browser-runtime`** – Browser execution environment for skills requiring web automation.
- **`toss-securities`** – Financial API client demonstrated in [`packages/toss-securities/src/official-client.js`](https://github.com/NomaDamas/k-skill/blob/main/packages/toss-securities/src/official-client.js), showing how reusable libraries expose typed clients for external services.

Dependencies between packages and skills resolve through the workspace mechanism, allowing imports like `@nomadamas/k-skill-proxy` to resolve to the local source code rather than remote npm registries during development.

## Individual Skill Directories

Unlike traditional monorepos where applications live in `apps/` or `samples/`, k-skill places each skill at the repository root as a top-level directory (e.g., `zipcode-search/`, `yebigun-training/`). This flat structure makes skills immediately discoverable and emphasizes their status as primary consumer-facing units.

Every skill directory contains standardized files:
- **[`skill.json`](https://github.com/NomaDamas/k-skill/blob/main/skill.json)** – Metadata declaring the skill name, required credentials, entry points, and runtime configuration. The k-skill CLI reads this file to register and execute the skill.
- **[`SKILL.md`](https://github.com/NomaDamas/k-skill/blob/main/SKILL.md)** – User-facing documentation explaining features and usage examples.
- **[`instruction.md`](https://github.com/NomaDamas/k-skill/blob/main/instruction.md)** – Developer-focused guide for implementing, debugging, and maintaining the skill.
- **`scripts/`** – Implementation code written in Python or Node.js that contains the actual agent logic.

For example, the `zipcode-search` skill implements its logic in [`zipcode-search/scripts/zipcode_search.py`](https://github.com/NomaDamas/k-skill/blob/main/zipcode-search/scripts/zipcode_search.py), importing utilities shipped with the skill to perform HTTP requests against the Korean postal service API.

## Python Packages Scaffold

The `python-packages/` directory provides a scaffold for future Python distributions. Currently empty, this structure anticipates the need for shared Python libraries analogous to the Node.js packages in `packages/`, enabling code reuse across Python-based skills without duplicating utility functions.

## Deployment and Legacy Infrastructure

Supporting assets reside in dedicated directories outside the main code flow. The `infra/` directory contains deployment assets for the k-skill proxy server, including Dockerfiles, Helm charts for Kubernetes deployment, and a monitoring dashboard documented in [`infra/k-skill-proxy-dashboard/README.md`](https://github.com/NomaDamas/k-skill/blob/main/infra/k-skill-proxy-dashboard/README.md).

Deprecated skill implementations that are no longer maintained reside in `legacy/unsupported-packages/`, such as the blue-ribbon-nearby skill. This segregation prevents obsolete code from cluttering active development while preserving historical reference and migration paths.

## How Skills Integrate with the Repository Structure

Skills interact with the monorepo structure through the CLI and workspace dependencies. When installing skills globally, the CLI reads each [`skill.json`](https://github.com/NomaDamas/k-skill/blob/main/skill.json) file to build the execution context:

```bash

# Install the entire skill collection globally (requires Node ≥ 18)

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

```

The command scans the repository root, identifies directories containing [`skill.json`](https://github.com/NomaDamas/k-skill/blob/main/skill.json) files, and registers them under the `k-skill` namespace.

For individual skill execution without full installation:

```bash

# Run a single skill (e.g., zipcode-search)

npx --yes skills add NomaDamas/k-skill --skill zipcode-search -g
k-skill:zipcode-search "강남역"

```

The CLI resolves the `zipcode-search` folder, loads [`scripts/zipcode_search.py`](https://github.com/NomaDamas/k-skill/blob/main/scripts/zipcode_search.py), and executes the query against the entry point defined in [`skill.json`](https://github.com/NomaDamas/k-skill/blob/main/skill.json).

Shared libraries integrate through standard imports:

```javascript
// Using the proxy package inside a Node.js skill
import { fetchWithProxy } from '@nomadamas/k-skill-proxy';
await fetchWithProxy('https://openapi.somegov.kr/data');

```

The import resolves to [`packages/k-skill-proxy/src/server.js`](https://github.com/NomaDamas/k-skill/blob/main/packages/k-skill-proxy/src/server.js) via the workspace configuration, allowing skills to leverage centralized infrastructure for rate limiting, caching, and authentication.

Python skills follow a similar pattern, importing local utilities:

```python

# A Python skill script (zipcode-search)

from utils import http_get   # utility shipped with the skill

def main(query):
    resp = http_get(f"https://api.zipcode.kr/search?q={query}")
    print(resp.json())

```

## Summary

- **The k-skill repository uses a monorepo structure** combining npm workspaces for reusable libraries with individual skill directories at the root level.
- **Root configuration** includes [`tsconfig.json`](https://github.com/NomaDamas/k-skill/blob/main/tsconfig.json), [`package.json`](https://github.com/NomaDamas/k-skill/blob/main/package.json) workspaces, and GitHub Actions in `.github/workflows/` for CI/CD.
- **Shared libraries** live in `packages/` (Node.js) and `python-packages/` (future Python), while **individual skills** occupy top-level directories like `zipcode-search/`.
- **Each skill requires three standard files**: [`skill.json`](https://github.com/NomaDamas/k-skill/blob/main/skill.json) (metadata), [`SKILL.md`](https://github.com/NomaDamas/k-skill/blob/main/SKILL.md) (user docs), and [`instruction.md`](https://github.com/NomaDamas/k-skill/blob/main/instruction.md) (developer guide), plus a `scripts/` directory for implementation code.
- **Infrastructure and legacy code** reside in `infra/` and `legacy/` respectively, supporting deployment and historical reference without interfering with active skill execution.
- **The k-skill CLI** discovers skills by scanning for [`skill.json`](https://github.com/NomaDamas/k-skill/blob/main/skill.json) files and resolves dependencies through the npm workspace mechanism.

## Frequently Asked Questions

### What is the difference between packages/ and individual skill directories?

The `packages/` directory contains reusable libraries like `k-skill-proxy` and `toss-securities` that multiple skills can import as dependencies. Individual skill directories (e.g., `zipcode-search/`) at the repository root are standalone agent implementations that consume these libraries. Packages export functionality through npm modules, while skills expose executable entry points via [`skill.json`](https://github.com/NomaDamas/k-skill/blob/main/skill.json) files that the k-skill CLI recognizes.

### How does the CI/CD system handle the monorepo structure?

The GitHub Actions workflows in [`.github/workflows/ci.yml`](https://github.com/NomaDamas/k-skill/blob/main/.github/workflows/ci.yml) run tests across all skill folders and packages simultaneously. The root [`package.json`](https://github.com/NomaDamas/k-skill/blob/main/package.json) defines workspaces that allow the CI to install dependencies for the entire repository with a single `npm install` command, while still maintaining separate version management for individual packages through the Changesets configuration in [`.changeset/config.json`](https://github.com/NomaDamas/k-skill/blob/main/.changeset/config.json).

### What files are required to create a new skill in k-skill?

A new skill requires a top-level directory containing three mandatory files: [`skill.json`](https://github.com/NomaDamas/k-skill/blob/main/skill.json) declaring the skill metadata and entry points, [`SKILL.md`](https://github.com/NomaDamas/k-skill/blob/main/SKILL.md) for user documentation, and [`instruction.md`](https://github.com/NomaDamas/k-skill/blob/main/instruction.md) for developer guidance. Additionally, a `scripts/` subdirectory must contain the implementation code (Python or Node.js) that the CLI invokes when users run the skill command.

### Where are deployment configurations stored for the k-skill infrastructure?

Deployment assets live in the `infra/` directory, which contains Dockerfiles, Helm charts for Kubernetes orchestration, and monitoring dashboard configurations. For example, the proxy server deployment documentation resides in [`infra/k-skill-proxy-dashboard/README.md`](https://github.com/NomaDamas/k-skill/blob/main/infra/k-skill-proxy-dashboard/README.md), while the `.github/workflows/` directory handles the automated release pipelines for publishing packages to npm and PyPI.