SNNN-011/skill-authoring

Skill Authoring

에이전트의 행동을 실제로 바꾸는 스킬을 만드는 가이드입니다. 읽히지 않는 문서가 아닙니다.

핵심 원칙: 스킬은 운영 지침이지, 글이 아닙니다. 이 스킬을 로드한 후 에이전트가 다르게 행동하지 않는다면, 그 스킬은 실패한 것입니다.

이 스킬 사용법

이 스킬은 대화를 통해 사용되며, 한 번에 끝나는 작업이 아닙니다. 흐름은 다음과 같습니다:

1. 사용자가 스킬을 실행합니다 (예: "스킬 skill-authoring 사용해서 내 에이전트용 스킬 만들고 싶어").
2. 에이전트는 글쓰기를 멈추고 1단계 인터뷰를 시작합니다: 한 번에 한 질문씩, 답변을 기다립니다.
3. 다섯 가지 질문에 모두 답하면, 에이전트는 2단계부터 5단계까지 실행하고 초안을 사용자에게 보여줍니다.
4. 사용자가 승인하면 에이전트는 파일을 작성하고(6단계), 트리거 테스트(7단계)와 체크리스트(8단계)를 실행합니다.

에이전트를 위한 규칙:

• 1단계의 다섯 가지 질문에 모두 답하기 전에는 SKILL.md를 작성하지 마세요. 조기 초안은 인터뷰를 중단시킵니다.
• 다섯 가지 질문을 한꺼번에 던지지 마세요. 한 번에 하나씩, 각 질문에 짧은 예시를 함께 제시하세요.
• 사용자가 "간단한 예시만 원해"라고 하면, 1번과 4번 질문만 하고 계속 진행하세요.
• 처음에 최종 결과물은 바로 사용할 수 있는 하나의 SKILL.md 파일이라고 알려주세요.

이 스킬이 활성화되는 경우

• 사용자가 "스킬 만들어", "스킬 작성", "스킬 만드는 법", "내 에이전트용 스킬"이라고 말할 때.
• 사용자에게 에이전트 기능에 대한 아이디어가 있지만 어떻게 표현해야 할지 모를 때.
• 기존 스킬이 전혀 트리거되지 않거나 에이전트가 따르지 않을 때.
• 이것이 스킬, 에이전트, 명령, 훅 중 무엇이 되어야 하는지 결정해야 할 때.

기존 스킬을 찾으려면 먼저 skill-scout을 사용하세요. 쌓여 있는 스킬을 감사하려면 skill-stocktake을 사용하세요.

0단계 - 작성 전 기본 규칙

좋은 스킬은 네 가지 특성을 갖습니다:

특성	의미
구체적	하나의 작업 유형에 집중, "백엔드에 관한 모든 것"이 아님
운영적	단계, 명령, 실제 예시 포함, 이론이 아님
트리거 가능	description에 사용자가 실제로 사용하는 단어가 포함됨
제한적	500줄 미만, 이상적으로는 100-250줄

스킬 아이디어가 이 네 가지를 충족하지 못하면, 먼저 아이디어를 수정하고 파일을 작성하지 마세요.

1단계 - 기능이 아닌 실제 문제 파악

"테스트용 스킬"부터 시작하지 마세요. 구체적인 실패에서 시작하세요.

사용자에게 다섯 가지 질문을 던지세요 (한 번에 하나씩, 한꺼번에 하지 마세요):

1. 지금 에이전트가 잘못 또는 일관성 없이 하는 것은 무엇인가요? 실제 예시를 하나 들어주세요.
2. 그 상황은 언제 발생하나요? (코드 작성, PR 리뷰, 배포, 사용자 응답, 데이터 분석)
3. 올바른 결과는 어떤 모습인가요? 사용자가 좋다고 생각하는 출력 예시를 하나 보여주세요.
4. 이 스킬을 통해 에이전트에게 알려줘야 할 정보는 무엇인가요? (팀 규칙, 단계 순서, 함정)
5. 이 스킬을 실행할 때 에이전트가 절대 해서는 안 되는 것은 무엇인가요?

4번과 5번 답변이 실제 스킬의 내용입니다. 1번과 2번 답변이 description의 내용입니다.

사용자가 1번 질문에 답하지 못하면, 프로세스를 중단하세요. 아직 만들 스킬이 없는 것입니다 - 그저 바람일 뿐입니다. 그렇게 말하세요.

2단계 - 올바른 형태 선택

모든 것을 스킬로 만들지 마세요. 문제를 해결하는 가장 가벼운 형태를 선택하세요.

필요	형태	이유
코드 작성 시 반복적으로 사용하는 지식/규칙	스킬	자동 로드, 호출 불필요
별도 컨텍스트가 필요한 독립적 다단계 작업	에이전트	병렬 실행 가능, 자체 컨텍스트 보유
사용자가 인식하고 인수와 함께 실행하는 작업	명령	/{이름} 명시적, 자동 아님
이벤트 기반 자동 동작 (커밋 전, 편집 후)	훅	모델 결정 없이 실행
모든 작업에 적용되는 짧은 규칙	규칙	항상 활성화, 트리거 불필요
인간이 읽을 긴 설명	문서	에이전트 로드 불필요

실용 규칙:

• 트리거가 필요한가? 스킬.
• 별도 컨텍스트나 제한된 도구가 필요한가? 에이전트.
• 매개변수와 함께 수동 호출이 필요한가? 명령.
• 요청 없이 실행되어야 하는가? 훅.
• 항상 옳고, 절대 위반되지 않아야 하는가? 규칙.
• 인간이 읽고, 에이전트가 읽지 않아도 되는가? 문서.

스킬과 규칙 사이에서犹豫된다면: 내용이 10줄 미만이고 어디서나 적용된다면 규칙입니다.

3단계 - 먼저 중복 검색

작성하기 전에 먼저 찾으세요. 스킬 폴더는 하네스마다 다릅니다 - 사용자의 것에 맞추세요:

하네스	스킬 폴더
Claude Code	~/.claude/skills/ 또는 프로젝트의 .claude/skills/
OpenCode	~/.config/opencode/skills/ 또는 .opencode/skills/
Cursor	.cursor/skills/
Codex	.agents/skills/

# 이미 설치된 스킬 (위 표에 따라 <스킬-폴더> 변경)
grep -ril "키워드" <스킬-폴더> --include=SKILL.md

# skills/ 폴더가 있는 repo 내부에 있을 때
grep -ril "키워드" skills --include=SKILL.md

사용자가 자신의 스킬 폴더를 모르면, 위 표를 설명하고 사용 중인 하네스를 선택하도록 하세요. 추측하지 마세요.

이미 비슷한 것이 있다면 선택하세요: 있는 그대로 사용, 기존 것을 확장, 또는 새로 만들기. 중복 스킬은 에이전트가 선택을 혼동하고 컨텍스트에 부담을 줍니다.

4단계 - description 작성 (가장 중요한 부분)

description은 에이전트가 스킬을 로드할지 결정하기 위해 읽는 유일한 부분입니다. 여기서 잘못되면 스킬은 죽습니다.

공식:

[수행하는 활동] + [트리거 컨텍스트] + [사용자가 사용하는 키워드] + [사용하지 않는 경우]

나쁜 예:

description: 테스팅 지원

좋은 예:

description: React 컴포넌트 테스트 패턴 (Vitest + Testing Library) - 렌더링, 사용자 이벤트, 네트워크 모킹, 접근성 검증. React 컴포넌트 테스트를 작성하거나 수정할 때 사용하세요. E2E 테스트에는 사용하지 마세요 (e2e-testing 사용).

규칙:

• 사용자가 실제로 입력하는 단어를 사용하고, 내부 용어는 사용하지 마세요.
• 다른 스킬의 작업을 침범하지 않도록 범위를 명시하세요.
• 한 줄로 작성하고, 문자열 내에 줄바꿈을 넣지 마세요.
• "코드", "도움", "다양한" 같은 단일 일반 용어는 피하세요.

빠른 테스트: 파일을 닫고 description만 읽으세요. 에이전트로서 언제 로드해야 할지 정확히 모르겠다면 다시 작성하세요.

5단계 - 내용 구성

효과적인 것으로 입증된 섹션 순서:

---
name: 스킬-이름
description: <4단계의 공식>
metadata:
  origin: ECC
---

# 제목

한 문단: 이 스킬이 에이전트의 행동을 어떻게 바꾸는지.

## 활성화 조건
구체적인 트리거 목록.

## 핵심
작업 단계, 결정 테이블 또는 규칙. 스킬 내용의 70%를 차지합니다.

## 예시
하나는 잘못된 예, 하나는 올바른 예. 실제 예시여야 하며, placeholder가 아니어야 합니다.

## 안티 패턴
피해야 할 실수와 그 이유.

## 체크리스트
확인 가능한 체크박스.

## 관련 스킬
2-4개의 스킬 이름.

내용 작성 규칙:

• 명령형 문장 사용 ("X를 하십시오"), 수동적 설명 사용 금지 ("X를 할 수 있습니다").
• 결정에는 표를, 순서에는 번호 목록을, 명령에는 코드 블록을 사용하세요.
• 각 규칙은 확인 가능해야 합니다 - "깨끗한 코드 작성"은 불가능, "함수 최대 50줄"은 가능.
• 에이전트가 실행하는 부분에 [여기에 입력], TODO, ...와 같은 placeholder를 두지 마세요.
• 외부 제품의 정체성을 그대로 복사하지 마세요 - 아이디어를 가져와 자신의 맥락에 맞게 다시 작성하세요.
• 비밀 정보를 포함하지 마세요: API 키, 토큰, 절대 개인 경로, 내부 회사 이름.

길이 제한: 500줄 (엄격한 최대 800줄). 초과하면 두 개의 스킬로 나누거나 세부 사항을 같은 스킬 폴더의 references/로 옮기세요.

6단계 - 파일 작성

작성하기 전에 마지막 두 가지를 물어보세요:

1. 스킬 언어 - 사용자가 일상적으로 사용하는 언어, 아니면 이식성을 위한 영어? 답변을 따르고, 임의로 선택하지 마세요.
2. 폴더 이름 - 설명적인 kebab-case 이름을 제안하고 (예: react-컴포넌트-테스트), 승인을 받으세요.

그런 다음 <스킬-폴더>/<이름>/SKILL.md에 작성하세요. 절대 위반하지 말아야 할 규칙:

• 프론트매터의 name:이 폴더 이름과 정확히 일치해야 합니다. 이것이 없으면 일부 하네스가 스킬 로드를 거부합니다.
• 먼저 전체 초안을 사용자에게 보여주고 저장하세요. 몰래 저장하지 마세요.
• 에이전트가 실행할 부분에 placeholder (TODO, [여기에 입력], ...)를 두지 마세요.
• 저장 후 전체 경로와 트리거 방법을 한 문장으로 보고하세요: "이제 에이전트에게 <트리거> 시 <스킬 이름> 스킬을 사용하라고 요청하세요."

7단계 - 사용 전 테스트

최소 세 가지 테스트. 하나도 건너뛰지 마세요.

테스트 1 - 긍정 트리거 (켜짐) 스킬 이름을 언급하지 않고 이 스킬을 트리거해야 하는 작업을 에이전트에게 주세요.

"LoginButton 컴포넌트 테스트를 작성해 주세요."

스킬이 로드되면 통과. 실패하면 description에 키워드가 부족한 것입니다.

테스트 2 - 부정 트리거 (꺼짐) 비슷하지만 영역이 다른 작업을 주세요.

"로그인 흐름의 E2E 테스트를 작성해 주세요."

스킬이 로드되지 않으면 통과 (또는 에이전트가 다른 적절한 스킬을 선택). 실패하면 description이 너무 넓은 것입니다.

테스트 3 - 실행 스킬을 실제로 트리거하는 작업을 에이전트에게 요청하고, 스킬 없을 때의 출력과 비교하세요.

스킬 없음: 에이전트가 X 스타일로 테스트 작성
스킬 있음: 에이전트가 Y 스타일로 테스트 작성 (팀 규칙 준수)

보여줄 수 있는 행동 차이가 있으면 통과. 출력이 동일하면 스킬은 쓸모없습니다 - 삭제하거나 통합하세요.

8단계 - 전송 준비 체크리스트

• 파일이 <스킬-폴더>/{이름}/SKILL.md에 있고, name:이 폴더 이름과 정확히 일치합니다.
• description이 한 줄이며, 사용자 키워드와 범위 제한을 포함합니다.
• description이 블록 리터럴 (|)을 사용하지 않고, 인라인 문자열만 사용합니다.
• 명시적인 "활성화 조건" 섹션이 있습니다.
• 각 규칙이 확인 가능하며, "좋은 코드 작성"과 같은 모호한 표현이 없습니다.
• 최소 하나의 잘못된 예와 하나의 올바른 예가 있습니다.
• 안티 패턴이 있습니다.
• 500줄 미만입니다.
• 비밀, 토큰 또는 절대 개인 경로가 없습니다.
• 테스트 1, 2, 3이 실행되었고 결과가 기록되었습니다.
• 3단계가 실행되었고 중복이 없습니다.
• 마지막 부분에 2-4개의 관련 스킬이 언급되어 있습니다.

자동 유효성 검사는 사용자 repo에서 사용 가능한 경우에만:

# ECC / 스킬 유효성 검사기가 있는 repo
node scripts/ci/validate-skills.js

유효성 검사기가 없으면 가장 자주 실패하는 네 가지를 수동으로 확인하세요: name:이 폴더와 일치하는지, description이 한 줄인지, 줄 수가 500 미만인지, placeholder가 없는지. 사용자에게 이 수동 검사가 사용된다고 알리세요.

바로 사용 가능한 템플릿

---
name: 스킬-이름
description: <활동> - <범위>. <구체적인 트리거> 시 사용하세요. <범위 외>에는 사용하지 마세요.
metadata:
  origin: ECC
---

# 스킬 이름

이 스킬을 로드한 후 에이전트의 행동이 어떻게 바뀌는지.

## 활성화 조건
- <트리거 1>
- <트리거 2>

## 단계
1. <즉시 실행 가능한 첫 단계>
2. <두 번째 단계>
3. <검증>

## 예시
잘못됨: <자주 나타나는 코드 또는 답변>
올바름: <원하는 버전, 간단한 이유 포함>

## 안티 패턴
- <실수> - <이유>

## 체크리스트
- [ ] <기계나 눈으로 확인 가능한 것>

## 관련 스킬
- `<스킬-a>`, `<스킬-b>`

Authoring 안티 패턴

• 트리거 없는 스킬. description이 모호하여 스킬이 절대 로드되지 않음. 이것이 가장 흔한 실패 원인입니다.
• 텍스트 벽 스킬. 명령 없이 900줄의 이론. 에이전트가 로드한 후 무시합니다.
• "도움이 되세요" 스킬. 특정 지식이 없으면 결과가 스킬 없을 때와 동일합니다.
• 중복 스킬. 두 스킬이 같은 영역을 주장하며, 에이전트가 무작위로 선택합니다.
• 타인 스킬 전체 복사. 당신이 모르는 숨겨진 지침과 의존성을 포함할 수 있습니다.
• 비밀 또는 개인 경로가 있는 스킬. 스킬이 공유될 때 함께 유출됩니다.
• 한 번만 사용할 스킬 작성. 한 번만 사용된다면 스킬이 아니라 문서나 명령입니다.
• 찾기 전에 스킬 만들기. 항상 3단계를 실행하세요.

스킬을 만들 필요가 없는 경우

다음 중 하나라도 해당되면 사용자에게 솔직하게 말하세요:

• 문제가 에이전트의 지식 부족이 아니라 코드의 버그일 때.
• 한 번만 실행하면 될 때 - 직접 지시를 내리면 충분합니다.
• 내용이 10줄 미만의 일반 규칙일 때 - 규칙입니다.
• 프로젝트의 AGENTS.md나 CLAUDE.md에 추가하는 것으로 충분할 때.
• 요구 사항의 80%를 충족하는 기존 스킬이 있을 때 - 기존 것을 확장하세요.

관련 스킬

• skill-scout - 새로 만들기 전에 기존 스킬 검색
• skill-stocktake - 쌓여 있는 스킬의 품질 감사
• skill-comply - 스킬이 에이전트에 의해 실제로 준수되는지 측정
• agent-harness-construction - 에이전트 도구 및 행동 경계 설계