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

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 – Metadata including name, description, and profiles
  • instruction.md – Agent-friendly workflow description
  • scripts/ – Runtime helpers and execution logic
  • 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	Rebuilds SKILL.md files from skill metadata

The proxy server implementation resides in packages/k-skill-proxy/src/server.js, with tests in 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:

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:

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:

mkdir my-new-skill
cd my-new-skill

Create skill.json with metadata:

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

Create instruction.md describing the agent workflow:

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

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

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 and update the CLI layer automatically.

4. Test Your Changes

Run the full test suite:

npm run lint
npm run test
npm run ci

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

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 – Feature page with endpoints, secrets, and usage examples
• 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 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 for complete guidelines on npm Changesets and Python release-please configuration.

Local Testing with the CLI

Verify your skill works end-to-end:

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, 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 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 files are auto-generated from skill.json and 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. 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, 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.

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