# How to Contribute to the k-skill Project: A Complete Guide for Open-Source Developers

> Learn how to contribute to the k-skill project. This guide covers creating AI skills, mono-repo structure, branch conventions, CLI stubs, and releases. Start contributing to open source today.

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

---

**Contributing to k-skill involves creating or modifying AI-driven "skills" in a mono-repo structure, following branch naming conventions, generating CLI stubs, and using Changesets for releases.**

The **k-skill** project by NomaDamas is a modular collection of AI-powered skills that expose Korean public data services, e-commerce searches, and convenience APIs. If you want to **contribute to the k-skill project**, you'll work within a strict Node.js and Python workspace architecture where each skill lives as an independent package with standardized metadata and workflow definitions.

## Understanding the k-skill Architecture

Before contributing, you need to understand how the repository organizes its code.

### Mono-Repo Structure

The k-skill repository uses **workspaces** to manage multiple packages:

- **`packages/*`** – Node.js workspaces containing individual skills and shared tooling
- **`python-packages/*`** – Python workspaces for Python-based skills
- **Individual skill folders** – Each skill (e.g., `kakao-map/`, `ev-charger-nearby/`) contains:
  - [`skill.json`](https://github.com/NomaDamas/k-skill/blob/main/skill.json) – Metadata including name, description, and profiles
  - [`instruction.md`](https://github.com/NomaDamas/k-skill/blob/main/instruction.md) – Agent-friendly workflow description
  - `scripts/` – Runtime helpers and execution logic
  - [`SKILL.md`](https://github.com/NomaDamas/k-skill/blob/main/SKILL.md) – **Auto-generated** CLI adapter (do not edit manually)

### Key Components

| Component | Location | Purpose |
|-----------|----------|---------|
| **k-skill-proxy** | `packages/k-skill-proxy/` | Forwards calls to free public APIs requiring keys |
| **CLI package** | `@nomadamas/k-skill` | Bundles all skill stubs for end-user execution |
| **Documentation** | `docs/features/<skill>.md` | Feature-specific usage guides |
| **Generators** | [`scripts/generate-skill-stubs.js`](https://github.com/NomaDamas/k-skill/blob/main/scripts/generate-skill-stubs.js) | Rebuilds [`SKILL.md`](https://github.com/NomaDamas/k-skill/blob/main/SKILL.md) files from skill metadata |

The proxy server implementation resides in [`packages/k-skill-proxy/src/server.js`](https://github.com/NomaDamas/k-skill/blob/main/packages/k-skill-proxy/src/server.js), with tests in [`packages/k-skill-proxy/test/server.test.js`](https://github.com/NomaDamas/k-skill/blob/main/packages/k-skill-proxy/test/server.test.js). Production deployment runs on GPU-01, and changes only take effect after merging to `main`.

## Setting Up Your Contribution Environment

### Prerequisites

Ensure you have the following installed:

- Node.js with npm (supports workspaces)
- Python 3.x (for Python-based skills)
- Git with branch naming discipline

### Installation

Clone the repository and install dependencies:

```bash
git clone https://github.com/NomaDamas/k-skill.git
cd k-skill
npm install

```

## Contribution Workflow: Step by Step

### 1. Create a Feature Branch

Name your branch according to the convention:

```bash
git checkout -b feature/42        # If issue #42 exists

# OR

git checkout -b feature/#42       # Alternative format

```

**Critical rule**: Pull requests must target the `dev` branch. Only maintainers can merge to `main`.

### 2. Develop Your Skill

When you **contribute to k-skill** with a new capability, create these files in your skill folder:

```bash
mkdir my-new-skill
cd my-new-skill

```

Create [`skill.json`](https://github.com/NomaDamas/k-skill/blob/main/skill.json) with metadata:

```json
{
  "name": "my-new-skill",
  "description": "Brief description of what the skill does",
  "frontmatter": { "profile": "action" },
  "profiles": ["action"]
}

```

Create [`instruction.md`](https://github.com/NomaDamas/k-skill/blob/main/instruction.md) describing the agent workflow:

```markdown

# My New Skill – Instruction

This skill fetches data from a public API and returns a formatted JSON response.

## Workflow

1. Validate input parameters.
2. Call the upstream endpoint.
3. Return the parsed result.

## Parameters

- `query`: Search term (string, required)

```

Add your runtime script in `scripts/`:

```python
#!/usr/bin/env python3
import sys, requests, json

def main():
    import argparse
    parser = argparse.ArgumentParser()
    parser.add_argument("--query", required=True)
    args = parser.parse_args()
    resp = requests.get("https://api.example.com/search", params={"q": args.query})
    print(json.dumps(resp.json(), ensure_ascii=False, indent=2))

if __name__ == "__main__":
    main()

```

### 3. Generate Required Stubs

From the repository root, rebuild all generated assets:

```bash
npm run generate:skill-stubs   # Creates/updates SKILL.md adapters

npm run sync:cli-skills        # Syncs CLI package with new skill

```

These commands execute [`scripts/generate-skill-stubs.js`](https://github.com/NomaDamas/k-skill/blob/main/scripts/generate-skill-stubs.js) and update the CLI layer automatically.

### 4. Test Your Changes

Run the full test suite:

```bash
npm run lint
npm run test
npm run ci

```

For new skills, add unit tests in your skill's `tests/` folder:

```python
def test_my_new_skill():
    from scripts.run_my_new_skill import main
    # Mock HTTP requests and assert output format

```

### 5. Update Documentation

Modify two files to document your skill:

- **[`docs/features/my-new-skill.md`](https://github.com/NomaDamas/k-skill/blob/main/docs/features/my-new-skill.md)** – Feature page with endpoints, secrets, and usage examples
- **[`README.md`](https://github.com/NomaDamas/k-skill/blob/main/README.md)** – Add your skill to the master feature table

### 6. Submit Your Pull Request

Push your branch and open a PR to `dev`. Ensure CI checks pass before requesting review.

## API Proxy Policy

A critical rule when you contribute to the k-skill project involves API routing:

- **Free public APIs** – Must route through `k-skill-proxy` (handles key management)
- **Private or paid APIs** – Call directly from your skill scripts

This policy protects API keys and ensures consistent rate limiting for free services.

## Release and Versioning

Never edit [`package.json`](https://github.com/NomaDamas/k-skill/blob/main/package.json) versions manually. The project uses **Changesets** for version bumps:

1. Run `npx changeset` to document your changes
2. Commit the generated Changeset file
3. Maintainers will handle the release process

See [`docs/releasing.md`](https://github.com/NomaDamas/k-skill/blob/main/docs/releasing.md) for complete guidelines on npm Changesets and Python release-please configuration.

## Local Testing with the CLI

Verify your skill works end-to-end:

```bash
npx -y @nomadamas/k-skill@0 exec my-new-skill scripts/run_my_new_skill.py -- --query "서울"

```

The CLI automatically assembles the correct runtime profile (browser, vault, legal) based on your skill's configuration.

## Summary

To **contribute to the k-skill project**, follow these key practices:

- Use `feature/<issue-number>` branches targeting `dev`
- Structure skills with [`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 `scripts/`
- Run `npm run generate:skill-stubs` and `npm run sync:cli-skills` after changes
- Route free APIs through `k-skill-proxy`; call paid APIs directly
- Update `docs/features/<skill>.md` and [`README.md`](https://github.com/NomaDamas/k-skill/blob/main/README.md) for documentation
- Use Changesets for releases, never manual version edits
- Ensure `npm run ci` passes before submitting PRs

## Frequently Asked Questions

### What branch should I target for my pull request?

Always target the `dev` branch. The `main` branch is protected and only maintainers can merge to it. Use branch names like `feature/42` or `feature/#42` where 42 is your issue number.

### Can I manually edit the SKILL.md file in my skill folder?

No. [`SKILL.md`](https://github.com/NomaDamas/k-skill/blob/main/SKILL.md) files are auto-generated from [`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). Run `npm run generate:skill-stubs` to regenerate them. Editing them manually will cause your changes to be overwritten.

### How do I handle API keys in my skill?

Free public APIs must use the `k-skill-proxy` at [`packages/k-skill-proxy/src/server.js`](https://github.com/NomaDamas/k-skill/blob/main/packages/k-skill-proxy/src/server.js). This centralizes key management and rate limiting. Private or paid APIs can be called directly from your skill scripts without the proxy.

### What files must I update when adding a new skill?

You must create [`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 scripts in your skill folder. Additionally, run the generators, add tests, create `docs/features/<skill>.md`, and update the feature table in [`README.md`](https://github.com/NomaDamas/k-skill/blob/main/README.md).