첫 번째 에이전트 스킬 작성 방법

코딩 에이전트를 위한 집안 규칙이 있습니다. 커밋 메시지는 어떻게 보여야 하는지, 코드 리뷰는 무엇을 확인해야 하는지, 회의록은 어떻게 구조화되어야 하는지 같은 것들입니다. 그래서 매 세션 시작 시 채팅창에 붙여넣지만, 메시지 열 개가 지나면 에이전트는 이미 이탈해 버립니다. 다음 세션에서는 다시 붙여넣습니다.

문제는 메모리가 아닙니다. 지침이 에이전트가 매번 로드하는 파일 안에 있는 것이 아니라 클립보드에 존재한다는 것입니다. 스킬(skill)은 바로 그 파일입니다.

스킬이란 무엇인가

스킬은 SKILL.md라는 하나의 파일을 담고 있는 폴더입니다. 이 파일은 두 부분으로 구성됩니다.

YAML 프런트매터(frontmatter)는 name과 description이라는 두 필드를 가집니다. description이 트리거 역할을 합니다. 에이전트는 자신의 스킬들을 검사하여 어떤 것이 사용자의 요청에 적용되는지 결정합니다. 따라서 description은 두 가지 역할을 합니다. 스킬이 무엇을 하는지 설명하고, 언제 발동되어야 하는 상황의 이름을 붙여주는 것입니다.

1. 변경 사항 확인하기 (git status --short, git diff --cached --stat). 스테이징된 내용이 없으면 멈추고 질문하세요 — 절대로 아무것도 아닌 것으로 메시지를 만들어내지 마세요.

2. 정확히 하나의 타입 접두사 선택하기: feat, fix, docs, refactor, test, chore. 여러 타입을 혼합하는 변경 사항은 하나로 평균화되지 않고 두 개의 커밋으로 분리됩니다.

3. 제목 작성하기: type + 명령형 구문, ≤50자.

4. 최소 세 번 이상 설명한 워크플로우를 선택하세요. 반복이 선정 기준입니다.

5. 먼저 설명을 작성하세요. 명확한 트리거(trigger)를 작성할 수 없다면, 해당 스킬의 범위가 너무 넓다는 의미입니다.

6. 실행 순서에 따라 번호가 매겨진 단계로 워크플로우를 작성하고, 진행하지 않아야 할 경우를 위한 중지 조건(stop conditions)을 명시하세요.

7. 항상 수정하게 되는 규칙들을 추가하세요 — 이름, 형식, 입력이 모호할 때 무엇을 해야 하는지 등입니다.

8. 작동 예제 하나를 추가하세요 — 실제 입력, 예상 출력이며, 플레이스홀더(placeholder)는 사용하지 마세요.

9. 반례(anti-patterns)를 추가하세요. 이 워크플로우가 잘못 작동하는 방식은 단계만큼이나 교육적입니다.

10. 간결하게 유지하세요. 읽는 데 2분이 걸려야 합니다. 규칙이 한 번도 발동되지 않는다면 삭제하고; 짧고 정확한 스킬이 길고 오래된 스킬보다 낫습니다.

사용하기

해당 폴더를 에이전트의 스킬 디렉터리(skills directory)에 넣으면, 에이전트가 설명을 매칭하여 자동으로 가져갑니다 — 추가적인 설정은 필요 없습니다. 만약 작동 예제를 먼저 원한다면, 이 분석 자료가 나온 패키지 안에 있는 다섯 가지 스킬(commit messages, 코드 리뷰, 회의록 작성, 기술 교정, 구조화된 심층 연구)은 무료이며 MIT 라이선스가 적용됩니다.

Repo: https://github.com/alapha888/agent-skills-en

npx skills add alapha888/agent-skills-en

구조는 안정적인 부분이고, 규칙은 여러분의 몫입니다. 이번 주에 세 번 설명했던 워크플로우를 가져와서 한 번 작성해 보세요.