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

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	Entry point with installation shortcuts and feature matrix	[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)
*.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)
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)
.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)
AGENTS.md & CLAUDE.md	Repository-specific guidance for Opencode agents and Claude-Code integration	[AGENTS.md](https://github.com/NomaDamas/k-skill/blob/main/AGENTS.md)
CONTRIBUTING.md	Contribution policies including Changeset handling and proxy rules	[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

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 — Machine-readable metadata defining name, version, required credentials, and runtime profiles
2. instruction.md — Low-level runtime instructions specifying API communication patterns, proxy usage, and browser fallback behavior
3. SKILL.md — User-facing documentation auto-generated from 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:

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

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

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:

/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	Node.js, Python, and Claude-Code installation procedures
docs/setup.md	Environment variable resolution order and credential handling
docs/security-and-secrets.md	Secret management policies and proxy usage guidelines
docs/features/	Feature-specific guides referencing corresponding skill directories
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 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))
• 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). 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:

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

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

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

This pattern applies to any installed skill, leveraging the consistent 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, instruction.md, and 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 and 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 explaining environment setup, and the standard SKILL.md inside your skill directory for agent-facing reference. The CI pipeline in .github/workflows/ci.yml will validate both files exist before allowing release.

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