같은 작업을 다시 맡길 때마다 빠뜨리는 순서가 있었다.

문서를 고칠 때는 근거 확인을, git 작업에서는 변경 파일 분리를, UI 검수에서는 모바일 화면 확인을 자꾸 다시 말해야 했다.

처음에는 이런 절차를 긴 프롬프트에 붙였다. 그런데 세 번째 반복부터는 다음에도 같은 순서로 보게 만들 방법이 필요했다.

그때 필요한 것은 반복 절차 묶음(Codex Skill)에 가까웠다. 새 능력치가 아니라, 특정 작업에서 다시 펼쳐 볼 순서표다.

그래서 Skill 후보를 볼 때는 “이걸 설치하면 더 똑똑해질까”가 아니라 “다음번에도 같은 순서를 설명할 수 있을까”를 먼저 본다.

작업 요청을 저장소 규칙, 재사용 절차, 실행 경계, 외부 연결로 나누는 구조.

하나의 요청도 이번 프롬프트, 저장소 기본값, 반복 절차로 나눠야 관리 비용이 줄어든다.

이번 한 번이면 프롬프트에 둔다. 저장소 전체 기본값이면 AGENTS.md에 둔다. 특정 작업에서 매번 같은 순서가 필요하면 Skill 후보로 본다.

먼저 잡을 용어

이 글에서 쓰는 이름은 도구명보다 역할이 먼저다.

  • 반복 절차 묶음(Codex Skill): 특정 작업에서 매번 다시 볼 순서표다.
  • 절차 파일(SKILL.md): 그 순서와 적용 조건을 적어두는 중심 파일이다.
  • 필요한 만큼만 펼쳐 보기(progressive disclosure): 목록으로 후보를 보고, 선택된 절차와 보조 자료만 나중에 여는 방식이다.

이렇게 보면 Skill은 “에이전트를 강화하는 플러그인”이 아니다. “빠뜨리기 쉬운 절차를 다시 보게 하는 작은 파일 묶음”이다.

반복 비용이 Skill 후보가 된다

Skill 후보는 그럴듯한 주제에서 나오지 않는다. 같은 일을 세 번쯤 반복했는데 매번 빠지는 단계가 보이면 그때 후보가 된다.

예를 들어 “공식 문서 확인”, “변경 파일 분리”, “모바일 화면 확인”, “발행 전 공개 안전성 점검”은 한 번의 취향이 아니다. 특정 작업을 할 때 반복해서 필요한 절차다. 이런 절차를 매번 프롬프트에 붙이면 언젠가 빠진다.

여기서 바로 Skill을 만들 필요는 없다. 먼저 “이번 한 번의 요청인가, 저장소 전체 기본값인가, 특정 작업에서만 반복되는 절차인가”를 나눠보면 된다. 이 구분이 잡히면 프롬프트에는 이번 요청의 목표가 남고, AGENTS.md에는 저장소 기본값이 남고, Skill에는 특정 작업을 다시 할 때 필요한 순서가 남는다.

내가 이 구분을 신경 쓰게 된 이유도 비슷하다. 처음에는 “공식 문서 확인”, “git 변경 분리”, “고객 문서 공개 안전성 점검”을 전부 프롬프트에 붙였다. 그러다 보니 어떤 기준은 저장소 전체 규칙처럼 굳어졌고, 어떤 기준은 제품 문서나 릴리스 노트를 쓸 때만 필요했고, 어떤 기준은 실제 차단 장치가 필요한 위험 작업이었다. 이 셋을 같은 칸에 넣으면 AGENTS.md도 길어지고, Skill도 만능 체크리스트처럼 부풀었다.

공식 문서에서 말하는 Skill

이 정의가 필요했던 이유는 거창한 기능 이름을 외우기 위해서가 아니다. 내가 매번 프롬프트에 붙이던 반복 절차를 어디에 둘지 정해야 했기 때문이다.

OpenAI Codex의 Agent Skills 문서는 Skill을 반복 가능한 workflow를 위한 재사용 capability로 설명한다. 보통 SKILL.md가 중심이고, 필요하면 scripts/, references/, assets/ 같은 보조 파일을 함께 둔다.

Skill은 “프롬프트 묶음”이 아니다. 에이전트가 특정 작업에서 어떤 순서로 판단하고, 어떤 자료를 읽고, 무엇을 검증할지 묶어둔 작업 절차다.

공식 문서에서 특히 중요한 점은 앞에서 말한 필요한 만큼만 펼쳐 보기(progressive disclosure)다. Codex는 먼저 Skill의 이름, 설명, 경로 같은 metadata를 보고, 해당 Skill이 선택됐을 때 SKILL.md를 읽고, reference 문서나 script는 필요할 때만 본다. 즉 목록만 먼저 보고, 실제로 필요하다고 판단한 절차의 자세한 파일만 나중에 여는 방식이다.

내가 지금 이해하는 정의는 이렇다.

Skill은 SKILL.md를 중심으로 반복 작업 절차를 묶어두고,
필요할 때만 references, scripts, assets를 더 읽게 하는 작은 작업 절차 패키지(workflow package)다.

AGENTS.md와 Skill은 자리가 다르다

둘 다 에이전트에게 지시를 주는 파일처럼 보인다. 그래서 처음에는 헷갈린다.

문서 작업으로 가져오면 차이가 더 분명하다.

“새 문서는 먼저 비공개 초안 상태로 둔다”는 저장소 기본값이다. 매번 문서를 만들 때마다 달라지는 조건이 아니므로 AGENTS.md에 맞다.

“보안 공지나 API 문서를 쓸 때 공식 근거와 운영 경험을 분리한다”는 모든 작업의 기본값은 아니다. 하지만 고객에게 공개되는 기술 문서를 쓸 때마다 반복된다. 이런 것은 Skill 후보가 된다.

“승인 전 push를 막는다”는 또 다르다. 그건 Skill로 기억시키는 것보다 실행 경계에서 멈추게 만들어야 한다.

AGENTS.md는 저장소의 운영 기준이다. 작업 전 어디를 봐야 하는지, 어떤 명령으로 검증해야 하는지, 무엇을 하면 안 되는지처럼 반복되는 기본값을 둔다. Codex에서는 global, project, 현재 작업 경로에 가까운 instruction이 층을 이루기 때문에, 가까운 파일일수록 더 구체적인 기준이 될 수 있다.

Skill은 더 좁다. 작업 종류가 맞을 때만 꺼내 쓰는 workflow다. 공식 문서 확인, git 안전 점검, UI 디자인 기준, 긴 글 편집, 릴리스 점검처럼 “이 일을 할 때는 항상 이 순서가 필요하다” 싶은 것에 맞다.

그래서 Skill은 AGENTS.md를 대체하지 않는다. 반복 절차를 분리해 AGENTS.md가 너무 길어지는 것을 막는다.

저장소 전체 기본값과 특정 반복 절차가 서로 다른 층에 놓인 구조.

Skill 후보는 세 가지 질문으로 걸러낸다

Skill로 만들 만한 일에는 공통점이 있다. 같은 작업을 여러 번 반복하고, 매번 빠뜨리면 안 되는 단계가 있으며, 참고해야 할 문서나 검증 명령이 있다. 한 번의 프롬프트보다 길지만 모든 작업에 항상 필요한 규칙은 아닐 때 Skill 후보가 된다.

나는 세 가지 질문으로 나눠 본다.

  • 오늘 한 번만 필요한가. 그렇다면 프롬프트에 둔다.
  • 프로젝트 전체에서 항상 지켜야 하는가. 그렇다면 저장소 규칙 문서(AGENTS.md)에 둔다.
  • 특정 작업에서 반복되는 절차인가. 그렇다면 반복 절차 묶음(Codex Skill) 후보로 본다.

예를 들어 “보안 공지를 고객 문서로 정리한다”는 작업은 Skill에 잘 맞는다. 공식 공지 확인, 영향 범위와 추정 분리, 출처 표기, 공개 안전성 점검이 반복되기 때문이다.

반대로 “오늘은 리뷰만 하고 수정하지 마”는 프롬프트다. “생성된 산출물은 직접 수정하지 않는다”는 AGENTS.md다. “승인 전 외부 공개나 push를 실제로 막는다”는 Skill만으로는 부족하다. 그런 일은 실행 직전에 멈추는 장치가 필요하다.

잘못 배치하면 비용이 생긴다. 한 번짜리 취향을 AGENTS.md에 넣으면 저장소 기본값이 오염된다. 실제 차단이 필요한 일을 Skill에만 맡기면 문서상 기준은 있어도 실행 경계가 비어 있다.

늘릴 때는 설치보다 설명 가능성을 본다

처음에는 공개 repo에서 좋아 보이는 Skill을 많이 가져오면 에이전트가 더 잘 일할 것처럼 보인다. 실제로는 반대 문제가 먼저 생긴다.

어떤 Skill이 언제 불리는지 내가 설명하지 못하면, 결과가 좋아져도 왜 좋아졌는지 알 수 없다. 반대로 결과가 이상해졌을 때도 어떤 기준이 개입했는지 추적하기 어렵다.

OpenAI 문서 기준으로도 Skill 자동 호출은 name, description, 경로 같은 metadata에서 시작한다. Skill이 많거나 설명이 겹치면 어떤 절차가 작동했는지 사람이 따라가기 어려워진다. 많이 설치하는 것 자체가 곧 품질이 되지는 않는다.

가져오기 전에 최소한 아래는 봐야 한다.

  • 이 Skill은 어떤 상황에서 호출되어야 하는가.
  • description만 봐도 trigger와 제외 조건이 분명한가.
  • 내 저장소의 AGENTS.md와 충돌하지 않는가.
  • 파일 삭제, push, deploy, credential 접근 같은 위험 작업을 직접 하라고 시키지 않는가.
  • script가 있다면 무엇을 실행하는지 이해할 수 있는가.

특히 script가 붙은 Skill은 더 보수적으로 봐야 한다. instruction-only Skill은 잘못돼도 대개 지시 품질 문제로 끝난다. 하지만 script는 실제 파일, 명령, 외부 시스템 접근으로 이어진다. 그래서 “좋아 보인다”보다 “무엇을 하는지 설명한다”가 먼저다.

직접 만들 때는 작게 시작한다

Skill을 직접 만들 때도 처음부터 크게 만들 필요가 없다.

처음에는 SKILL.md 하나면 충분하다.

---
name: doc-source-check
description: 고객 문서나 릴리스 노트에서 공식 사실과 내부 추정을 분리해야 할 때 사용한다.
---

1. 문서의 핵심 주장을 목록으로 뽑는다.
2. 각 주장을 공식 문서, 운영 경험, 내부 추정으로 분류한다.
3. 공식 문서가 필요한 주장은 출처를 확인한다.
4. 확인하지 못한 문장은 단정하지 말고 "확인 필요"로 낮춘다.
5. 본문에는 공개하면 안 되는 내부 경로, 고객 정보, 비공개 대화 원문을 남기지 않는다.

이 정도만 있어도 “이 문서 사실성 좀 봐줘”라는 프롬프트보다 낫다. 해야 할 일이 단계로 남아 다음에도 같은 방식으로 반복된다.

다만 description은 더 구체적으로 다듬는 편이 좋다. 나쁜 description은 “문서를 잘 쓰게 한다”처럼 넓다. 좋은 description은 “고객 문서나 릴리스 노트에서 공식 사실, 영향 범위, 내부 추정을 분리해야 할 때 사용한다. 단순 오탈자 수정에는 사용하지 않는다”처럼 trigger와 제외 조건이 같이 보인다.

처음부터 scripts를 붙일 필요는 없다. 반복 실행해야 하는 검증 명령이 생기거나, 사람이 매번 똑같이 하는 기계적 작업이 보일 때 붙여도 늦지 않다.

작은 Skill 패키지가 절차 문서, 참고 자료, 실행 도구로 작게 묶인 모습.

Skill을 많이 갖는 것보다 중요한 건 내가 설명하는 Skill만 남기는 것이다. 에이전트가 똑똑해지는 느낌보다, 내가 검토하는 작업 절차가 늘어나는 쪽이 더 믿을 만하다.

내가 남기는 기준

AGENTS.md를 만들었다고 Skill이 필요 없어지는 것은 아니다. 둘은 자리가 다르다.

다만 Skill을 늘릴수록 에이전트가 저절로 좋아진다고 믿지는 않는다. 설명할 수 없는 Skill은 문제가 생겼을 때 추적하기 어렵다. 좋은 결과가 나와도 왜 좋아졌는지 알기 어렵고, 나쁜 결과가 나오면 어느 절차가 개입했는지 찾기 어렵다.

그래서 다음 반복 작업을 만났을 때 나는 먼저 하나만 묻는다.

이 절차를 다음번에도 같은 순서로 설명할 수 있는가?

그렇다면 Skill 후보가 된다. 아니라면 아직 프롬프트나 작업 메모로 남겨도 된다.

Skill은 에이전트를 마법처럼 바꾸는 장치가 아니다. 다음 작업에서 빠뜨리지 않을 작은 절차 하나를 남기는 방식이다.

시리즈 연결

참고