Agentic Basic Course

화면 모드

스킬 ​

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

기준일: 2026-09-30.

스킬로 옮길 만한 것 ​

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

한 줄 기준은 이렇다. 매 작업에 항상 필요한 짧은 내용은 룰로, 특정 작업에서만 필요한 긴 내용은 스킬로 간다.

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

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는 description을 보고 스킬을 자동 선택하거나 /이름으로 호출하며, disable-model-invocation: true로 자동 호출을 제한할 수 있다. Codex는 $이름 호출과 설명 기반 자동 선택을 지원한다. Claude Skills, Codex 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 스킬을 따른다’처럼 참조 한 줄만 두고 상세 절차는 스킬에 둔다. 이렇게 하면 룰 길이를 늘리지 않고 절차를 추가할 수 있다. 룰 자체의 구성은 룰에서 다룬다.

© 2026 qus0in

v0.2.0