# Understanding the k-skill Project Structure: A Complete Guide to NomaDamas/k-skill

> Explore the NomaDamas/k-skill project structure. Learn how independent skill modules organize metadata, runtime instructions, and documentation for easy installation and management.

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

---

**The k-skill repository is organized as a flat collection of independent skill modules, where each subdirectory represents a single installable skill containing metadata, runtime instructions, and documentation.**

This **skill-based architecture** makes the NomaDamas/k-skill repository uniquely modular. Rather than a monolithic package, it delivers hundreds of Korean-focused automation capabilities as discrete, individually installable units. The flat structure ensures any skill can be located, developed, and published without navigating complex nested hierarchies.

## Top-Level Directory Layout

The repository root contains several organizational elements that enable discovery, installation, and maintenance.

| Element | Purpose | Source Reference |
|---------|---------|----------------|
| [`README.md`](https://github.com/NomaDamas/k-skill/blob/main/README.md) | Entry point with installation shortcuts and feature matrix | [[`README.md`](https://github.com/NomaDamas/k-skill/blob/main/README.md)](https://github.com/NomaDamas/k-skill/blob/main/README.md) |
| `docs/` | Centralized documentation including install guides, security policies, and feature pages | [[`docs/install.md`](https://github.com/NomaDamas/k-skill/blob/main/docs/install.md)](https://github.com/NomaDamas/k-skill/blob/main/docs/install.md) |
| `*.skill-directory/` | Individual skill modules (e.g., `zipcode-search/`, `daangn-realty-search/`) | [[`zipcode-search/skill.json`](https://github.com/NomaDamas/k-skill/blob/main/zipcode-search/skill.json)](https://github.com/NomaDamas/k-skill/blob/main/zipcode-search/skill.json) |
| `k-skill-cleaner/` | Utility skill for analyzing usage and recommending removals | [[`k-skill-cleaner/skill.json`](https://github.com/NomaDamas/k-skill/blob/main/k-skill-cleaner/skill.json)](https://github.com/NomaDamas/k-skill/blob/main/k-skill-cleaner/skill.json) |
| `.github/workflows/` | CI pipelines for linting, testing, and automated releases | [[`.github/workflows/ci.yml`](https://github.com/NomaDamas/k-skill/blob/main/.github/workflows/ci.yml)](https://github.com/NomaDamas/k-skill/blob/main/.github/workflows/ci.yml) |
| [`AGENTS.md`](https://github.com/NomaDamas/k-skill/blob/main/AGENTS.md) & [`CLAUDE.md`](https://github.com/NomaDamas/k-skill/blob/main/CLAUDE.md) | Repository-specific guidance for Opencode agents and Claude-Code integration | [[`AGENTS.md`](https://github.com/NomaDamas/k-skill/blob/main/AGENTS.md)](https://github.com/NomaDamas/k-skill/blob/main/AGENTS.md) |
| [`CONTRIBUTING.md`](https://github.com/NomaDamas/k-skill/blob/main/CONTRIBUTING.md) | Contribution policies including Changeset handling and proxy rules | [[`CONTRIBUTING.md`](https://github.com/NomaDamas/k-skill/blob/main/CONTRIBUTING.md)](https://github.com/NomaDamas/k-skill/blob/main/CONTRIBUTING.md) |
| `LICENSE` | MIT license for core; AGPL-3.0-only for proxy-related packages | [`LICENSE`](https://github.com/NomaDamas/k-skill/blob/main/LICENSE) |

## Individual Skill Directory Structure

Every skill directory in k-skill follows a **consistent three-file pattern** that enables both machine processing and human readability.

### Core Files in Every Skill

1. **[`skill.json`](https://github.com/NomaDamas/k-skill/blob/main/skill.json)** — Machine-readable metadata defining name, version, required credentials, and runtime profiles
2. **[`instruction.md`](https://github.com/NomaDamas/k-skill/blob/main/instruction.md)** — Low-level runtime instructions specifying API communication patterns, proxy usage, and browser fallback behavior
3. **[`SKILL.md`](https://github.com/NomaDamas/k-skill/blob/main/SKILL.md)** — User-facing documentation auto-generated from [`skill.json`](https://github.com/NomaDamas/k-skill/blob/main/skill.json) and rendered by agent systems

Optional `scripts/` subdirectories contain language-specific helper implementations in Python, Node.js, or other runtimes.

The **k-skill-cli** tooling (located in `packages/k-skill-cli/` in the upstream workspace) consumes this uniform structure to auto-generate CLI stubs and synchronize assets across the repository.

## Installation and Distribution Model

The k-skill project structure supports **npm-style global installation** via npx, treating the entire repository as a skill registry.

### Installing Skills

Install every available skill globally:

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

```

Install a single skill (example: `srt-booking`):

```bash
npx --yes skills add NomaDamas/k-skill --skill srt-booking -g

```

These commands pull the appropriate skill directories into the user's global skill store at `~/.agents/skills/`.

### Running Installed Skills

Once installed, invoke skills using the `/k-skill:` prefix:

```bash
/k-skill:zipcode-search "서울특별시 강남구"

```

## Documentation Organization

The `docs/` directory serves as the **centralized knowledge hub** for the k-skill ecosystem.

| Document | Contents |
|----------|----------|
| [`docs/install.md`](https://github.com/NomaDamas/k-skill/blob/main/docs/install.md) | Node.js, Python, and Claude-Code installation procedures |
| [`docs/setup.md`](https://github.com/NomaDamas/k-skill/blob/main/docs/setup.md) | Environment variable resolution order and credential handling |
| [`docs/security-and-secrets.md`](https://github.com/NomaDamas/k-skill/blob/main/docs/security-and-secrets.md) | Secret management policies and proxy usage guidelines |
| `docs/features/` | Feature-specific guides referencing corresponding skill directories |
| [`docs/releasing.md`](https://github.com/NomaDamas/k-skill/blob/main/docs/releasing.md) | Changeset-based release procedures for npm packages |

Each feature guide explains required environment variables, API keys, and optional selection behaviors where user-provided secrets are needed.

## CI/CD and Release Automation

The [`.github/workflows/ci.yml`](https://github.com/NomaDamas/k-skill/blob/main/.github/workflows/ci.yml) pipeline orchestrates validation and distribution across multiple package ecosystems.

### Key Automation Components

- **npm packages**: Managed through **Changesets** (documented in [[`docs/releasing.md`](https://github.com/NomaDamas/k-skill/blob/main/docs/releasing.md)](https://github.com/NomaDamas/k-skill/blob/main/docs/releasing.md))
- **Python packages**: Use **release-please** scaffolding for automated versioning
- **Universal validation**: The `npm run ci` command ensures every skill builds and passes tests before any release proceeds

The CI workflow also handles **Manus bundle** generation for distribution through alternative channels.

## Proxy Architecture and Licensing

Free API usage routes through the **k-skill-proxy** server, which carries an **AGPL-3.0-only** license distinct from the core MIT license.

Proxy implementation code resides in `packages/k-skill-proxy/` (upstream workspace) with documentation at [[`docs/features/k-skill-proxy.md`](https://github.com/NomaDamas/k-skill/blob/main/docs/features/k-skill-proxy.md)](https://github.com/NomaDamas/k-skill/blob/main/docs/features/k-skill-proxy.md). This licensing split ensures proxy-related packages remain open while allowing broader use of core skills.

## Utility Skills: The k-skill-cleaner Example

The `k-skill-cleaner/` directory demonstrates how **utility skills** function without external API dependencies. This skill analyzes usage statistics and recommends removal of unused skills.

Install and run the cleaner:

```bash
npx --yes skills add NomaDamas/k-skill --skill k-skill-cleaner -g
/k-skill:k-skill-cleaner

```

Its [`skill.json`](https://github.com/NomaDamas/k-skill/blob/main/skill.json) follows the same schema as API-dependent skills, proving the uniformity of the k-skill project structure across all skill types.

## Viewing Skill Documentation Locally

Access a skill's rendered documentation directly:

```bash
cat $(npx skills path NomaDamas/k-skill/zipcode-search)/SKILL.md

```

This pattern applies to any installed skill, leveraging the consistent [`SKILL.md`](https://github.com/NomaDamas/k-skill/blob/main/SKILL.md) placement within each directory.

## Summary

- **Flat architecture**: Each skill occupies its own top-level directory for immediate discoverability
- **Three-file standard**: [`skill.json`](https://github.com/NomaDamas/k-skill/blob/main/skill.json), [`instruction.md`](https://github.com/NomaDamas/k-skill/blob/main/instruction.md), and [`SKILL.md`](https://github.com/NomaDamas/k-skill/blob/main/SKILL.md) provide complete skill definitions
- **Npm-based distribution**: Global installation via `npx skills add` with single-skill or full-suite options
- **Centralized docs**: All guides live under `docs/` with feature-specific subdirectories
- **Dual-licensed**: MIT for core skills, AGPL-3.0-only for proxy infrastructure
- **CI-validated**: Every skill undergoes automated testing before release across npm and Python ecosystems

## Frequently Asked Questions

### What makes k-skill different from a traditional monorepo?

Unlike typical monorepos that nest packages in `packages/`, k-skill uses a **flat top-level structure** where each skill directory stands independently. This design prioritizes discoverability and allows the `npx skills` CLI to resolve any skill by simple directory name without complex path mappings.

### How does k-skill handle different programming languages?

The **skill definition layer remains language-agnostic** through the [`skill.json`](https://github.com/NomaDamas/k-skill/blob/main/skill.json) and [`instruction.md`](https://github.com/NomaDamas/k-skill/blob/main/instruction.md) files. Optional `scripts/` subdirectories contain language-specific implementations—Python, Node.js, or others—while the core metadata structure stays consistent. The **k-skill-cli** consumes this uniform interface regardless of underlying implementation language.

### Why are there two different license files in the repository?

The **dual-licensing model** separates concerns: core skills use the permissive MIT license, while proxy-related packages fall under AGPL-3.0-only to ensure network-interacting code remains open source. This distinction appears in the top-level `LICENSE` file and affects which directories you can modify for proprietary use.

### Where should I add documentation for a new skill?

Create your skill directory at the repository root (e.g., `my-new-skill/`), then add corresponding entries in **two locations**: a feature guide at [`docs/features/my-new-skill.md`](https://github.com/NomaDamas/k-skill/blob/main/docs/features/my-new-skill.md) explaining environment setup, and the standard [`SKILL.md`](https://github.com/NomaDamas/k-skill/blob/main/SKILL.md) inside your skill directory for agent-facing reference. The CI pipeline in [`.github/workflows/ci.yml`](https://github.com/NomaDamas/k-skill/blob/main/.github/workflows/ci.yml) will validate both files exist before allowing release.