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

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 for project overview, LICENSE for the open-source terms, and CONTRIBUTING.md for contribution guidelines. The root package.json defines the npm workspace configuration, enabling the monorepo structure by declaring packages/* as workspace members.

TypeScript compilation settings live in 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 workflow runs automated tests across all skill folders and packages, while release-npm.yml and 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. 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 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), feature references (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, 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, 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, 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 – 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 – User-facing documentation explaining features and usage examples.
• 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, 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.

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 file to build the execution context:

# 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 files, and registers them under the k-skill namespace.

For individual skill execution without full installation:

# 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, and executes the query against the entry point defined in skill.json.

Shared libraries integrate through standard imports:

// 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 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:

# 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, 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 (metadata), SKILL.md (user docs), and 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 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 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 run tests across all skill folders and packages simultaneously. The root 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.

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 declaring the skill metadata and entry points, SKILL.md for user documentation, and 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, while the .github/workflows/ directory handles the automated release pipelines for publishing packages to npm and PyPI.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}