How to Report a Bug in k-skill: A Step-by-Step Guide

Report bugs in k-skill by opening a GitHub issue with a clear, reproducible description written in Korean, following the CONTRIBUTING.md workflow.

The k-skill project by NomaDamas is an open-source skill framework that requires structured bug reports to maintain code quality. This guide walks you through the exact process defined in the repository's contribution guidelines, ensuring your report gets attention from maintainers.

Prerequisites: Read the Contribution Guide

Before filing any issue, review CONTRIBUTING.md at the repository root. This file establishes mandatory rules for all external contributors, including:

• The required Korean language for all communication
• Branch naming and commit conventions
• Where and how to open issues

Skipping this step risks having your report rejected or delayed.

Step 1: Open a GitHub Issue

Navigate to the issue tracker: https://github.com/NomaDamas/k-skill/issues

Click "New issue" to begin your report. Unlike projects with complex issue templates, k-skill uses a free-form approach—so structure matters.

Step 2: Structure Your Bug Report

Use this exact format, adapted from the project's conventions:

# [Bug] <짧은 요약>

## 영향을 받는 스킬

`<skill-name>`  <!-- 예: `kbo-results` -->

## 재현 단계

1. <첫 번째 단계>
2. <두 번째 단계>
3. <세 번째 단계>

## 기대 동작

<설明>

## 실제 동작

<설명>

## 오류 메시지 / 로그

<여기에 콘솔 로그 또는 스택 트레이스 삽입>

## 환경

- OS: `<예: macOS 13.5>`  
- Node: `<예: v18.17.0>`  
- k‑skill version: `<git commit SHA 또는 tag>`  
- 사용 중인 프록시: `<예: k-skill-proxy>` (있다면)

Step 3: Include Essential Details

Every k-skill bug report needs these components:

• Concise title – Prefix with [Bug] and keep under 60 characters
• Affected skill name – Reference specific skills like kbo-results found in docs/features/
• Reproduction steps – Numbered, minimal steps that trigger the bug
• Expected vs. actual behavior – Clear contrast showing what's wrong
• Error messages or logs – Full stack traces from console output
• Environment details – Node version, OS, and whether you used k-skill-proxy

Step 4: Add Labels and Engage

After submission:

• Request the bug label (maintainers will add it if missing)
• Monitor for follow-up questions within 48-72 hours
• Provide additional logs or test proposed fixes when asked

Key Files for Reference

When investigating or describing bugs, consult these source files:

File	Purpose
CONTRIBUTING.md	Official contribution and bug-report workflow
README.md	Project overview and issue tracker links
docs/**/*.md	Skill-specific specifications (e.g., docs/features/kbo-results.md)
packages/k-skill-proxy/src/server.js	Proxy server implementation for API-related bugs
AGENTS.md	Agent behavior enforcement rules

Common Mistakes to Avoid

• Writing in English – All communication must be in Korean per CONTRIBUTING.md#소통-언어
• Vague reproduction steps – "It doesn't work" wastes maintainer time
• Missing skill context – Always specify which skill is affected
• Incomplete environment info – Proxy usage and Node version often determine bug root cause

Summary

• Read CONTRIBUTING.md before filing any k-skill bug report
• Write in Korean – this is mandatory, not optional
• Use the structured template with [Bug] prefix, affected skill, reproduction steps, and environment details
• Reference appropriate files like docs/features/*.md or packages/k-skill-proxy/src/server.js for technical context
• Engage responsively when maintainers request clarification or testing

Frequently Asked Questions

Does k-skill provide an issue template for bug reports?

No. The k-skill repository does not use GitHub's templated issue forms. Contributors must manually structure reports using the format specified in CONTRIBUTING.md. Copy the markdown template provided in this guide to ensure completeness.

What language must I use when reporting a bug in k-skill?

Korean is mandatory. The CONTRIBUTING.md file explicitly states that all communication—including issue descriptions, comments, and PR reviews—must be conducted in Korean. Reports submitted in English may be closed without review.

Where is the k-skill proxy server code located?

The proxy implementation resides in packages/k-skill-proxy/src/server.js. Reference this file when your bug involves API routing, request handling, or proxy-specific behavior. Include proxy usage details in your environment section when relevant.

How do I identify which skill is affected by a bug?

Check the docs/features/ directory for skill documentation. Each skill (e.g., kbo-results) has a dedicated markdown file describing its expected behavior. Compare your observed behavior against this specification to confirm the bug and cite the file in your report.

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