# 스킬

필요 시점에 로드하여 컨텍스트를 절약하는 모듈형 스킬의 구성과 작성법을 설명합니다.

원본 URL: https://abc.noco.kr/harness-basics/skills

스킬은 필요할 때만 읽는 절차 문서다. 룰과 달리 평소에는 로드되지 않으므로 자주 쓰지 않거나 긴 절차를 여기에 둔다.

기준일: 2026-09-30.

## 스킬로 옮길 만한 것

- 커밋·배포처럼 순서가 정해진 작업.
- 클린 아키텍처, 레이어, 도메인 경계 같은 구조 규칙.
- 클라우드와 도구 설정(배포 설정, 계정 관리).
- 프레임워크 최신 정보(Spring Boot, Docker, React 등).
- 코딩·API·테스트·저장소 convention.

한 줄 기준은 이렇다. 매 작업에 항상 필요한 짧은 내용은 [룰](/glossary#rules)로, 특정 작업에서만 필요한 긴 내용은 스킬로 간다.

-  룰에 넣기 망설여질 만큼 길거나 자주 쓰지 않는 절차는 스킬로 옮기고, 룰에는 참조 한 줄만 남긴다.

Convention도 같은 기준으로 나눈다. 커밋 형식처럼 항상 지키는 짧은 규칙은 룰에, API 응답 형식이나 테스트 구조처럼 작업별로 적용되는 상세한 규칙은 스킬에 둔다.

## SKILL.md 구조

스킬 하나는 폴더 하나다. 폴더 안에 `SKILL.md`를 두고 이름과 설명, 절차를 적는다. 설명은 에이전트가 이 스킬을 쓸지 판단하는 기준이므로 언제 쓰는지까지 적는다.

- 나쁨: `description: 커밋 스킬`
- 좋음: `description: 작업 단위의 변경을 커밋할 때 쓰는 절차. 검증이 끝난 뒤에만 사용한다.`

절차는 짧게 시작한다. 예를 들어 다음과 같다.

```markdown
---
name: commit
description: 작업 단위의 변경을 커밋할 때 쓰는 절차. 검증이 끝난 뒤에만 사용한다.
---

1. git status와 git diff로 바뀐 파일을 확인한다.
2. 이번 작업 단위의 파일만 stage한다.
3. 메시지를 <type>(<scope>): <요약> 형식으로 쓴다.
4. 빌드·테스트가 통과하지 않았으면 커밋하지 않는다.
5. push는 요청받았을 때만 한다.
```

배포처럼 단계가 더 긴 작업도 같은 형태로 만든다.

```markdown
---
name: deploy
description: 배포를 요청받았을 때 쓰는 절차.
---

1. 대상 환경과 버전을 확인한다.
2. 빌드와 검증을 다시 실행한다.
3. 배포를 실행하고 결과를 확인한다.
4. 주요 경로의 응답을 확인하고 기록을 남긴다.
```

- 긴 참고 자료는 같은 폴더의 `references/`로 분리한다. `SKILL.md` 본문은 500줄 미만을 목표로 한다.
- 참고 파일이 100줄을 넘으면 목차를 둔다.
- 커밋·배포처럼 부작용이 있는 작업은 자동 호출을 제한하고 직접 부를 때만 실행되게 할 수 있다.

참고: [Claude Code](/glossary#claude-code)는 description을 보고 스킬을 자동 선택하거나 `/이름`으로 호출하며, `disable-model-invocation: true`로 자동 호출을 제한할 수 있다. [Codex](/glossary#codex)는 `$이름` 호출과 설명 기반 자동 선택을 지원한다. [Claude Skills](https://code.claude.com/docs/en/skills), [Codex Skills](https://learn.chatgpt.com/docs/build-skills)

## 스킬을 만드는 순서

1. 반복해서 설명하게 되는 절차를 그대로 적는다.
2. 실제 작업에서 그대로 실행해 보고 빠진 단계를 채운다.
3. 이름과 설명 문장을 다듬어 자동 선택이 잘 되게 한다.
4. 절차가 길어지면 `references/`로 분리한다.

처음부터 완성된 문서를 만들 필요는 없다. 쓰면서 다듬는 편이 실제 작업과 맞는다.

## 로컬·전역과 링크 공유

- 로컬(저장소) 스킬: `.agents/skills` 또는 `.claude/skills`.
- 전역(개인) 스킬: `~/.agents/skills` 또는 `~/.claude/skills`.

두 런타임이 같은 스킬을 보게 하려면 한쪽 폴더를 링크한다.

```bash
mkdir -p .agents/skills .claude
ln -s ../.agents/skills .claude/skills
ls -l .claude/skills
```

내용은 한 벌만 관리하고, 호출은 각 런타임 문법으로 한다. 어떤 스킬을 저장소에 둘지와 개인 폴더에 둘지는 범위로 나눈다. 모두에게 필요한 절차는 저장소에, 개인 취향은 전역에 둔다.

## 호출 방법

- Claude Code는 `/이름`으로 직접 부르거나 설명을 보고 자동 선택된다.
- Codex는 `$이름`으로 부르거나 같은 방식으로 자동 선택된다.

자동 호출이 불편한 스킬(커밋, 배포)은 수동 호출만 가능하게 두는 설정을 쓴다. 자동 선택은 이름과 설명으로 이뤄지므로, 스킬이 늘어날수록 설명 문장을 정확하게 쓰는 일이 중요해진다.

## 룰의 스킬 참조

룰에는 ‘커밋은 commit 스킬을 따른다’처럼 참조 한 줄만 두고 상세 절차는 스킬에 둔다. 이렇게 하면 룰 길이를 늘리지 않고 절차를 추가할 수 있다. 룰 자체의 구성은 [룰](/harness-basics/rules)에서 다룬다.