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

> Learn how to report a bug in k-skill by opening a GitHub issue. Follow our step-by-step guide and contributing workflow for a clear, reproducible bug report. Fix k-skill faster.

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

---

**Report bugs in k-skill by opening a GitHub issue with a clear, reproducible description written in Korean, following the [`CONTRIBUTING.md`](https://github.com/NomaDamas/k-skill/blob/main/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`](https://github.com/NomaDamas/k-skill/blob/main/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:

```markdown

# [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`](https://github.com/NomaDamas/k-skill/blob/main/CONTRIBUTING.md) | Official contribution and bug-report workflow |
| [`README.md`](https://github.com/NomaDamas/k-skill/blob/main/README.md) | Project overview and issue tracker links |
| `docs/**/*.md` | Skill-specific specifications (e.g., [`docs/features/kbo-results.md`](https://github.com/NomaDamas/k-skill/blob/main/docs/features/kbo-results.md)) |
| [`packages/k-skill-proxy/src/server.js`](https://github.com/NomaDamas/k-skill/blob/main/packages/k-skill-proxy/src/server.js) | Proxy server implementation for API-related bugs |
| [`AGENTS.md`](https://github.com/NomaDamas/k-skill/blob/main/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`](https://github.com/NomaDamas/k-skill/blob/main/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`](https://github.com/NomaDamas/k-skill/blob/main/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`](https://github.com/NomaDamas/k-skill/blob/main/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`](https://github.com/NomaDamas/k-skill/blob/main/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`](https://github.com/NomaDamas/k-skill/blob/main/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.