AI 에이전트가 실제로 사용할 수 있는 터미널 스킬(Terminal Skills)을 작성하는 방법

대부분의 AI 에이전트 관련 조언은 여전히 프롬프트(Prompt) 조언처럼 들립니다.

더 많은 컨텍스트(Context)를 추가하세요.
더 명확한 지침을 작성하세요.
모델에게 예시를 제공하세요.
더 나은 시스템 프롬프트(System Prompt)를 사용하세요.

그것들도 도움이 되지만, 실제 업무에서 문제를 일으키는 부분을 놓치고 있습니다.

문제는 항상 에이전트가 명령어를 모른다는 것이 아닙니다. 문제는 에이전트가 당신의 워크플로우(Workflow)를 모른다는 것입니다.

에이전트는 언제 먼저 검사해야 하는지 모릅니다.
어떤 기본값(Defaults)이 안전한지 모릅니다.
'완료(Done)'가 무엇을 의미하는지 모릅니다.
추측하는 대신 언제 멈춰야 하는지 모릅니다.
무언가가 로컬 머신(Local Machine)을 떠나기 전에 어떤 확인 절차가 중요한지 모릅니다.

이 지점에서 터미널 스킬(Terminal Skills)이 유용해집니다.

터미널 스킬은 단순한 명령어 단축키가 아닙니다. 그것은 에이전트를 위한 작고 재사용 가능한 운영 절차(Operating Procedure)입니다.

터미널 스킬은 다음을 가르칩니다:

언제 워크플로우를 사용할지
어떤 입력값(Inputs)이 허용되는지
어떤 명령어 또는 스크립트(Scripts)가 선호되는지
어떤 출력값(Output)이 존재해야 하는지
결과를 어떻게 검증할지
언제 멈추고 도움을 요청할지

마지막 부분이 유용한 에이전트 워크플로우와 자신감 넘치는 난장판 사이의 차이를 만듭니다.

다음은 제가 스킬을 작성할 때 사용하는 패턴입니다.

도구가 아닌 작업(Task)부터 시작하세요

가장 흔한 실수는 도구 이름으로 시작하는 것입니다.

잘못된 시작점:

FFmpeg 스킬을 만드세요.

더 나은 시작점:

가공되지 않은 비디오 파일을 X-ready MP4로 변환한 다음, 업로드가 성공할 가능성이 있는지 검증하는 스킬을 만드세요.

이것들은 범위(Scope)가 다릅니다.

첫 번째는 도구 래퍼(Tool Wrapper)입니다.

두 번째는 워크플로우(Workflow)입니다.

에이전트에게 가능한 모든 FFmpeg 플래그(Flag)가 필요한 것이 아닙니다. 그들에게 필요한 것은 일반적인 문제를 해결하는 안정적인 경로입니다.

이는 모든 터미널 워크플로우에도 동일하게 적용됩니다:

유용한 스킬은 계약(Contract)을 가집니다

저는 터미널 스킬(Terminal Skill)을 인간, 에이전트(Agent), 그리고 기계 사이의 계약(Contract)이라고 생각하는 것을 좋아합니다.

이 계약은 다음과 같이 명시합니다:

만약 이러한 종류의 작업이 나타나고,
이러한 입력값(Inputs)이 존재한다면,
다음의 워크플로우(Workflow)를 따르십시오,
...

단순하게 들릴 수 있지만, 이는 많은 무작위성(Randomness)을 제거해 줍니다.

계약이 없다면, 에이전트는 즉흥적으로 행동합니다.

계약이 있다면, 에이전트는 기본 운영 경로(Default operating path)를 갖게 됩니다.

그렇다고 해서 에이전트의 지능이 낮아지는 것은 아닙니다. 매번 새로운 추론(Reasoning)에 의존해야 하는 비중을 줄여주는 것입니다.

기본 구조

대부분의 터미널 스킬을 위해, 저는 다음과 같은 폴더 구조로 시작할 것입니다:

my-skill/
  SKILL.md
  scripts/
...

모든 스킬에 스크립트(Script)가 필요한 것은 아닙니다.

어떤 스킬은 주로 절차적(Procedural)입니다. 어떤 스킬은 기존 CLI(Command Line Interface)를 감싸는 래퍼(Wrapper)입니다. 어떤 스킬은 강력한 지침(Instructions)과 검증 명령(Verification commands)만으로 구성되기도 합니다.

하지만 SKILL.md가 중요한 부분입니다.

이 파일은 단순히 도구가 무엇을 하는지가 아니라, 에이전트가 어떻게 작업해야 하는지를 알려주어야 합니다.

다음은 실용적인 템플릿입니다.

# 스킬 이름 (Skill Name)

## 사용 시점 (Use When)
...
```bash
./scripts/run.sh input-file
```

## 검증 (Verification)

...

이것은 이미 느슨한 프롬프트(Prompt)보다 훨씬 유용합니다.

에이전트에게 지도(Map)를 제공하기 때문입니다.

가장 중요한 섹션은 "중단 조건 (Stop Conditions)"입니다

대부분의 사람들은 이 부분을 간과합니다.

그들은 성공 경로(Happy path)만을 문서화하고 실패 경계(Failure boundaries)는 건너뜁니다.

하지만 에이전트에게는 중단 조건이 절실히 필요합니다.

좋은 스킬은 다음과 같이 명시해야 합니다:

저장소(Repo)에 관련 없는 사용자 변경 사항이 있는 경우 중단
API 토큰이 누락된 경우 중단
공개 페이지를 검증할 수 없는 경우 중단
출력 파일에 비디오 스트림이 없는 경우 중단
명령어가 소스 파일을 삭제하거나 덮어쓰는 경우 중단
사용자가 초안(Draft)은 승인했지만 게시(Publishing)는 승인하지 않은 경우 중단

이 지점에서 에이전트 워크플로우가 안전해집니다.

예를 들어, 소셜 게시(Social publishing) 스킬은 단순히 다음과 같이 말해서는 안 됩니다:

작성기(Composer)를 열고 게시물을 게시하십시오.

대신 다음과 같이 말해야 합니다:

게시하기 전에, 작성기(composer)에 승인된 정확한 텍스트가 포함되어 있는지 확인하십시오.
게시한 후에는, 최종 퍼머링크(permalink)에 전체 텍스트와 첨부된 미디어가 표시되는지 확인하십시오.
미디어가 누락되었다면, 성공했다고 보고하지 마십시오.

이것이 바로 실제 작동 규칙(operating rule)입니다.

이는 보통 사람의 머릿속에만 머물러 있는 워크플로(workflow)의 일부를 포착해낸 것입니다.

검증(Verification)은 구체적이어야 합니다

"제대로 작동했는지 확인하십시오"라는 말로는 충분하지 않습니다.

좋은 터미널 스킬(Terminal Skill)은 실제 확인 작업을 명시합니다.

비디오 스킬의 경우:

ffprobe -v error -show_streams -show_format output.mp4

코드 스킬의 경우:

npm test
git diff --check

콘텐츠 게시 스킬의 경우:

최종 라이브 URL을 엽니다.
제목, 본문, 태그, 캐노니컬 URL(canonical URL), 그리고 미디어가 보이는지 확인합니다.
에디터 미리보기를 최종 검증 수단으로 신뢰하지 마십시오.

데이터 내보내기(data export) 스킬의 경우:

파일을 보내기 전에 행 수(row count), 헤더(headers), 인코딩(encoding), 그리고 샘플 레코드(sample records)를 확인하십시오.

에이전트(Agents)는 너무 일찍 "완료"라고 말하는 데 매우 능숙합니다.

검증 명령(Verification commands)은 "완료"를 속이기 어렵게 만듭니다.

스킬을 좁게 유지하십시오

가장 좋은 스킬은 지루할 정도로 구체적인 것입니다.

나쁜 예:

content-automation

더 나은 예:

devto-draft-from-markdown
x-safe-video-export
reddit-comment-visibility-check
...

좁은 범위의 스킬은 트리거(trigger)가 더 명확하고 숨겨진 가정이 적습니다.

또한 개선하기도 더 쉽습니다.

비디오 내보내기가 실패하면, 비디오 스킬을 수정하십시오.
DEV.to 초안에서 캐노니컬 URL(canonical URL)이 누락되었다면, DEV.to 스킬을 수정하십시오.
Reddit 댓글이 작성자에게는 보이지만 공개적으로 보이지 않는다면, 가시성 확인(visibility check) 스킬을 수정하십시오.

하나의 거대한 "콘텐츠 자동화(content automation)" 스킬은 이러한 모든 실패를 하나의 모호한 덩어리 안에 숨겨버릴 것입니다.

작은 스킬들은 워크플로(workflow)를 조사 가능하게(inspectable) 만듭니다.

메커니즘에는 스크립트를, 판단에는 지침을 사용하십시오

모든 스킬이 거대한 스크립트가 되어야 한다고 생각하지는 않습니다.

스크립트는 기계적인 반복 작업에 좋습니다:

이 파일 변환
이 JSON 유효성 검사
이 이미지 크기 조정
이 API 호출
이 보고서 생성

지침(Instructions)은 판단(judgment)을 내리는 데 더 적합합니다:

스크립트를 언제 사용할지
어떤 후보를 거절할지
승인(approval)을 어떻게 처리할지
무엇을 검증(verification)으로 간주할지
언제 중단할지

스킬(skill)은 이 두 가지를 모두 결합해야 합니다.

예를 들어:

SKILL.md는 워크플로(workflow)를 설명합니다.
scripts/export.sh는 변환을 수행합니다.
검증(Verification) 명령은 출력을 증명합니다.
...

이것이 유용한 형태입니다.

"에이전트가 도구(tool)를 가지고 있다"가 아니라,

"에이전트가 일하는 방식(way of working)을 가지고 있다"가 되어야 합니다.

예시: 아주 작은 리포지토리 조사(repo-inspection) 스킬

스크립트가 필요 없는 작은 예시입니다.

# 리포지토리 조사 (Repo Inspection)

## 사용 시점 (Use When)
...
```bash
pwd
git status --short
rg --files | head -80
rg -n "keyword|component|route" .
```

## 중단 조건 (Stop Conditions)

...

이것은 화려하지 않습니다.

하지만 에이전트가 흔히 범하는 많은 실수를 방지해 줍니다.

에이전트에게 신중하게 작업하는 방식(shape of careful work)을 가르쳐 줍니다.

무엇이 좋은 스킬을 만드는가?

저는 보통 다섯 가지 질문으로 스킬을 판단합니다.

1. 명확한 트리거(trigger)가 있는가?

에이전트는 언제 이를 사용해야 하는지 알아야 합니다.
트리거가 모호하면 스킬은 무시되거나 과도하게 사용될 것입니다.

2. 반복적인 추론(reasoning)을 줄여주는가?

좋은 스킬은 에이전트가 동일한 워크플로를 다시 발견해야 하는 수고를 덜어줍니다.
워크플로가 단 한 번만 사용된다면, 아직 스킬이 필요하지 않을 수도 있습니다.

3. 완료(done)의 정의를 내리는가?

스킬은 어떤 출력이 존재해야 하는지, 그리고 그것을 어떻게 검증할지를 명시해야 합니다.
"완료"가 주관적이라면, 에이전트는 추측하게 될 것입니다.

4. 중단 조건(stop conditions)을 포함하는가?

이것은 안전 계층(safety layer)입니다.
워크플로에 필수 입력값, 외부 승인, 또는 검증이 누락되었을 때, 스킬은 에이전트가 확신을 가지고 작업을 계속하는 것을 방지해야 합니다.

5. 유지 관리할 수 있을 만큼 충분히 작은가?

스킬이 모든 것을 위한 거대한 매뉴얼이 되어버리면, 더 이상 유용하지 않게 됩니다.
작고 조합 가능한(composable) 스킬이 신뢰하기 더 쉽습니다.

더 중요한 점

AI 에이전트들은 도구 사용(tool use) 능력이 점점 좋아지고 있습니다.

그렇다고 해서 모든 워크플로를 채팅창에서 즉흥적으로 처리해야 한다는 뜻은 아닙니다.

에이전트의 능력이 향상될수록, 운영 절차(operating procedures)는 더욱 중요해집니다.

프롬프트(Prompts)는 의도(intent)를 전달하는 데 좋습니다.
도구(Tools)는 능력(capability)을 제공하는 데 좋습니다.
스킬(Skills)은 반복 가능한 작업(repeatable work)을 수행하는 데 좋습니다.

그것이 바로 더 많은 개발자가 구축해야 한다고 생각하는 계층입니다.

그것이 화려하기 때문이 아닙니다.

지루하고 재사용 가능한 워크플로(workflows)야말로 에이전트를 단순한 데모 수준에서 실제로 신뢰할 수 있는 무언가로 변화시키기 때문입니다.

저는 Terminal Skills에서 이 패턴의 더 많은 사례를 수집하고 있습니다.

만약 여러분만의 에이전트 워크플로(agent workflows)를 구축하고 있다면, 매주 반복하는 짜증 나는 작업 하나부터 시작해 보세요.

트리거(trigger), 워크플로(workflow), 검증(verification), 그리고 중단 조건(stop conditions)을 작성하십시오.

그것이 여러분의 첫 번째 스킬(skill)입니다.