당신의 첫 번째 에이전트 워크플로(workflow)는 하나의 신중한 프롬프트(prompt), 몇 가지 도구(tools), 그리고 그것이 어떻게 동작해야 하는지 아는 개발자로 시작됩니다. 그러다 제품이 성장합니다. 고객 지원팀은 환불 워크플로를 원합니다. 영업팀은 CRM 업데이트를 원합니다. 운영팀은 보고서 생성을 원합니다. 엔지니어링 팀은 MCP 도구, 브라우저 액션(browser actions), 재시도(retries), 승인(approvals) 기능을 추가합니다.

곧, "에이전트"는 하나의 시스템이 아니게 됩니다. 그것은 복사된 프롬프트 더미, 숨겨진 규칙, 일회성 도구 설명, 오래된 런북(runbooks), 그리고 아무도 안전하게 재사용할 수 없는 Slack 스레드 상의 결정사항들이 쌓인 덩어리가 됩니다.

이것이 바로 프롬프트 확산(prompt sprawl)입니다. 이는 당신의 AI 제품을 엉망으로 만듭니다. 또한 프로덕션 동작을 테스트하기 어렵게 만들고, 검토하기 어렵게 하며, 롤백(roll back)하기 어렵게 만듭니다.

AI 에이전트 스킬 레지스트리(AI agent skill registry)는 더 깔끔한 재사용 단위를 제공합니다. 즉, 에이전트가 무엇을 할 수 있는지, 어떤 도구를 사용할 수 있는지, 어떤 입력(inputs)이 필요한지, 성공을 증명하는 증거는 무엇인지, 그리고 절대로 일어나서는 안 되는 일은 무엇인지를 명시하는 버전 관리되고 테스트 가능한 패키지입니다.

이 가이드는 소규모 팀을 플랫폼 팀으로 변모시키지 않으면서도 스킬 레지스트리를 구축하는 방법을 보여줍니다.

이것이 지금 중요한 이유

최근의 AI 빌더(builder) 트렌드는 모두 같은 방향을 가리키고 있습니다. 에이전트는 점점 더 도구 중심적(tool-heavy)이 되고, 상태 유지(stateful)가 강화되며, 실제 워크플로와 더 많이 연결되고 있습니다. 이제 개발자 코스에서는 도구(tools), 메모리(memory), 컨텍스트 엔지니어링(context engineering), 품질 측정(quality measurement)을 핵심 에이전트 스킬로 가르칩니다. 코딩 어시스턴트(coding assistants)는 재사용 가능한 스킬, 브라우저 액션, 컴퓨터 사용(computer-use) 워크플로를 향해 나아가고 있습니다.

이러한 변화는 새로운 실패 모드(failure mode)를 만들어냅니다.

모든 워크플로가 각자의 프롬프트를 소유하게 되면, 모든 프롬프트는 하나의 작은 프로덕션 시스템이 됩니다:

• 권한(permissions)을 가집니다.
• 비즈니스 규칙(business rules)을 가집니다.
• 숨겨진 가정(hidden assumptions)을 가집니다.
• 비용 영향(cost impact)을 가집니다.
• 실제 제품으로부터 드리프트(drift, 괴리)될 수 있습니다.
• 적절하지 않은 곳으로 복사될 수 있습니다.

스킬 레지스트리는 이러한 워크플로를 마법 같은 텍스트가 아닌 소프트웨어 아티팩트(software artifacts)처럼 취급할 수 있도록 도와줍니다.

AI 에이전트 스킬 레지스트리란 무엇인가?

AI 에이전트 스킬 레지스트리는 에이전트를 위한 재사용 가능한 워크플로 패키지의 카탈로그입니다.

스킬은 단순한 프롬프트가 아닙니다. 유용한 프로덕션 스킬은 다음을 포함합니다:

• 이름 및 목적 (Name and purpose)
• 지원되는 입력 스키마 (Supported input schema)
• 필수 컨텍스트 (Required context)
• 도구 권한 (Tool permissions)
• 안전 제한 (Safety limits)
• 성공 기준 (Success criteria)
• 테스트 케이스 및 평가 (Test cases and evals)
• 버전 이력 (Version history)
• 소유자 및 검토 상태 (Owner and review status)
• 배포 단계 (Rollout stage)
• 폐기 규칙 (Deprecation rules)

이를 가공되지 않은 프롬프트 (raw prompts)와 완전한 에이전트 프레임워크 (agent frameworks) 사이의 누락된 중간 계층 (middle layer)이라고 생각하십시오.

간단한 레지스트리 항목은 다음과 같은 질문에 답할 수 있습니다:

“이 에이전트가 결제 실패 사례를 요약하고, 청구 기록을 확인하며, 지원 응답 초안을 작성한 뒤, 계정 변경을 수행하기 전에 멈출 수 있는가?”

이는 모델에게 긴 프롬프트를 건네주고 모든 수정 사항 이후에도 올바른 동작이 유지되기를 바라는 것보다 훨씬 명확합니다.

프롬프트 확산 (Prompt Sprawl)의 문제점

프롬프트 확산 (Prompt sprawl)은 보통 조용히 나타납니다.

한 팀이 좋은 지원 프롬프트를 작성합니다. 다른 팀이 이를 결제 워크플로 (billing workflow)에 복사하고 다섯 줄을 수정합니다. 세 번째 팀은 도구 호출 (tool call)을 추가합니다. 누군가는 정책 노트를 중간에 붙여넣습니다. 아무도 어떤 버전이 라이브 상태인지 기억하지 못합니다.

그 결과, 비슷해 보이지만 다르게 동작하는 워크플로 세트가 만들어집니다.

일반적인 증상은 다음과 같습니다:

• 서로 다른 프롬프트가 동일한 작업을 약간씩 다른 방식으로 해결함
• 지침 (instructions)에 오래된 도구 이름이 여전히 나타남
• 승인 규칙이 한 워크플로에는 복사되어 있지만 다른 워크플로에는 누락됨
• 하드코딩된 고객 예시가 테스트에 유출됨
• 에이전트가 고장 났을 때 소유자가 불분명함
• 어떤 프롬프트 버전이 잘못된 답변을 생성했는지 알 수 있는 신뢰할 수 있는 방법이 없음
• 스킬 수준의 테스트 스위트 (test suite)가 없어 수동 QA를 수행해야 함

이는 단순히 깔끔함의 문제가 아닙니다. 신뢰의 문제입니다.

AI 워크플로가 고객 데이터를 변경하거나, 메시지를 보내거나, 레코드를 생성하거나, 비즈니스 작업을 권장하는 경우, 팀은 어떤 스킬이 사용되었는지, 그리고 왜 실행이 허용되었는지 알아야 합니다.

스킬 패키지에는 무엇이 포함되어야 하는가?

좋은 스킬 패키지는 검토하기에 충분히 작으면서도 안전하게 실행될 수 있을 만큼 완전해야 합니다.

다음은 실질적인 구조입니다:

id: billing.refund_reviewer
name: Refund Review Assistant
version: 1.4.0
...

이 형식은 프롬프트가 종종 숨겨버리는 결정들을 강제합니다:

• 에이전트가 무엇을 읽을 수 있는가?
• 에이전트가 무엇을 할 수 있는가?
• 작업의 경계는 어디인가?
• 작업을 수행했음을 증명하는 증거는 무엇인가?
• 명시적으로 범위 외(out of scope)인 것은 무엇인가?

반드시 이와 똑같은 스키마(schema)를 사용할 필요는 없습니다. 중요한 점은 스킬이 검토 가능(reviewable)하고, 버전 관리(versioned)가 되며, 테스트 가능(testable)해야 한다는 것입니다.

지침(Instructions), 도구(Tools), 정책(Policy)의 분리

흔히 하는 실수 중 하나는 모든 것을 하나의 거대한 지침 블록(instruction block)에 집어넣는 것입니다.

이렇게 하면 스킬을 테스트하기 어려워집니다. 또한 비즈니스 정책(business policy), 톤(tone), 도구 사용(tool usage), 안전 규칙(safety rules)이 서로 뒤엉켜 있기 때문에 모든 변경 사항이 위험해집니다.

더 깔끔한 패키징 방식은 네 가지 계층을 분리하는 것입니다.

1. 작업 지침 (Task Instructions)

이는 작업을 수행하는 방법에 대해 에이전트에게 제공하는 가이드라인입니다.

예시:

당신은 환불 요청을 검토합니다. 결제 증거를 수집하고, 이를 환불 정책과 비교한 뒤, 사람 검토자를 위한 권고안을 초안으로 작성하세요.

환불을 승인하지 마세요. 환불을 약속하지 마세요. 증거가 불충분하다면 추측하는 대신 검토를 요청하세요.

2. 도구 계약 (Tool Contract)

어떤 도구가 존재하며 어떻게 사용되어야 하는지를 명시합니다.

tool_rules:
  billing.get_invoice:
    allowed_when: "refund_request_id belongs to tenant_id"
...

3. 런타임 정책 (Runtime Policy)

이는 모델이 잘 행동하기를 바라는 것이 아니라, 코드로 강제(enforced)됩니다.

type SkillPolicy = {
  skillId: string;
  allowedTools: string[];
...

4. 평가 케이스 (Evaluation Cases)

수정 후에도 스킬이 여전히 제대로 작동하는지 증명합니다.

  "case_id": "refund_missing_invoice",
  "input": {
...

이러한 분리는 실질적인 규칙을 제공합니다: 프롬프트는 행동을 제안할 수 있지만, 정책(policy)과 테스트(tests)는 중요한 부분을 강제해야 합니다.

API처럼 스킬 버전 관리하기

스킬은 프로덕션 인터페이스(production interfaces)입니다. 이를 API처럼 취급하세요.

도움이 된다면 유의적 버전(semantic versioning)을 사용하되, 의미는 단순하게 유지하십시오:

• 패치 버전 (Patch version): 문구 변경, 행동 변화 없음
• 마이너 버전 (Minor version): 새로운 지원 케이스 추가, 안전한 도구 추가, 더 나은 출력 형식
• 메이저 버전 (Major version): 권한 변경, 작업 경계 변경, 성공 기준 변경

레지스트리(registry)는 다음과 같은 별칭(aliases)을 유지해야 합니다:

• refund_reviewer@dev
• refund_reviewer@staging
• refund_reviewer@prod
• refund_reviewer@1.4.0

'latest'에 프로덕션 환경을 직접 지정하는 것은 피하세요. 이는 무해한 수정이 바쁜 지원 업무 중에 동작을 변경할 때까지는 괜찮아 보입니다.

더 안전한 조회 방법은 다음과 같습니다:

async function resolveSkill(skillId: string, env: "dev" | "staging" | "prod") {
  const alias = await db.skill_alias.findUnique({
    where: { skill_id_env: { skill_id: skillId, env } }
... 

이 방법을 사용하면 모든 워크플로가 조용히 변경되는 대신 알려진 버전을 승격(promote)시킬 수 있습니다.

검토 상태 추가 (Add Review States)

모든 스킬이 모든 환경에서 실행되어야 하는 것은 아닙니다. 각 버전에 draft, review, staging, canary, production, deprecated, 또는 blocked와 같은 상태를 부여하세요. Draft 스킬은 로컬에 머무릅니다. Staging 스킬은 테스트 테넌트(test tenants)나 합성 데이터(synthetic data)를 사용합니다. Canary 스킬은 제한된 노출만 받습니다. Blocked 스킬은 실행될 수 없습니다.

이것이 중요한 이유는 작은 프롬프트 수정은 위험도가 낮을 수 있지만, 새로운 도구 권한은 프로덕션 데이터를 변경할 수 있기 때문입니다. 승격 규칙(Promotion rules)은 이러한 차이를 감지해야 합니다.

레지스트리에 보안 검사 추가 (Put Security Scans in the Registry)

스킬 자체가 공급망 위험(supply-chain risk)이 될 수 있습니다.

이는 스킬이 종종 포함하는 내용을 생각하면 과장되게 들릴 수 있습니다:

• 도구 설명(Tool descriptions)
• 셸 명령어(Shell commands)
• URL
• 정책 텍스트(Policy text)
• 실수로 포함된 자격 증명(Credentials by mistake)
• 마크다운 내 숨겨진 지침(Hidden instructions in markdown)
• 예시 데이터(Example data)
• MCP 서버 참조(MCP server references)
• 설치 명령어(Install commands)

스킬이 스테이징 환경에 도달하기 전에 검사하세요.

최소한 다음 사항을 확인해야 합니다:

• 하드코딩된 비밀값(Hardcoded secrets)
• 외부 웹훅 URL(External webhook URLs)
• 셸 실행 명령어(Shell execution instructions)
• 고정되지 않은 패키지 설치(Unpinned package installs)
• 지침이 포함된 숨겨진 HTML 주석(Hidden HTML comments with instructions)
• 시스템 또는 개발자 정책을 무시하려는 시도(Attempts to override system or developer policy)
• 크로스 테넌트 데이터 예시(Cross-tenant data examples)
• 광범위한 접근을 유도하는 도구 설명(Tool descriptions that invite broad access)

간단한 로컬 검사만으로도 많은 명백한 문제를 포착할 수 있습니다:

const riskyPatterns = [
  /api[_-]?key\s*[:=]/i,
  /BEGIN (RSA|OPENSSH|PRIVATE) KEY/, 
... 

이것은 완전한 보안 프로그램은 아닙니다. 유용한 첫 번째 관문(gate) 역할을 합니다. 레지스트리는 승인(promotion)을 제어하기 때문에 스캔 결과를 저장하기에 적합한 장소입니다.

스킬을 평가(Evals)와 연결하기

평가(evals)가 없는 레지스트리는 그저 보기 좋은 프롬프트 폴더가 될 뿐입니다.

각 스킬은 워크플로의 위험도(workflow risk)에 부합하는 테스트 세트(test set)를 가져야 합니다.

위험도가 낮은 스킬의 경우, 테스트는 형식(formatting), 어조(tone), 그리고 기본적인 작업 성공 여부를 확인할 수 있습니다.

위험도가 더 높은 스킬의 경우, 다음 사항을 테스트합니다:

• 권한 경계 (Permission boundaries)
• 도구 호출 순서 (Tool-call order)
• 거부 동작 (Refusal behavior)
• 누락된 컨텍스트 처리 (Missing context handling)
• 잘못된 입력 처리 (Bad input handling)
• 프롬프트 주입 저항성 (Prompt-injection resistance)
• 비용 및 지연 시간 제한 (Cost and latency limits)
• 인간 승인 라우팅 (Human approval routing)
• 증거 품질 (Evidence quality)

아주 작은 평가 실행기(eval runner)는 다음과 같이 시작할 수 있습니다:

type EvalCase = {
  id: string;
  input: unknown;
...

10개의 강력한 케이스로 시작하세요. 운영 환경(production)에서 고통스러운 교훈을 얻을 때마다 새로운 케이스를 추가하세요.

단순 저장이 아닌 발견(Discovery)을 위한 설계

레지스트리는 빌더(builders)가 적절한 스킬을 찾을 수 있도록 도와야 합니다.

검색과 재사용을 지원하는 메타데이터(metadata)를 추가하세요:

tags:
  - billing
  - support
...

효과적인 발견 기능은 중복된 스킬 생성을 방지합니다.

개발자가 "refund"를 검색했을 때, 새로운 스킬을 작성하기 전에 이미 승인된 환불 검토자(refund reviewer)를 볼 수 있어야 합니다. 만약 "write action"을 검색한다면, 어떤 스킬이 데이터 수정을 허용하는지, 그리고 어떤 스킬이 승인을 필요로 하는지 확인할 수 있어야 합니다.

스킬 실행의 추적 가능성 유지

모든 운영 환경의 실행(production run)은 스킬 버전을 기록해야 합니다.

최소한 다음 항목들을 저장하세요:

• 스킬 ID (Skill ID)
• 스킬 버전 (Skill version)
• 사용된 레지스트리 별칭 (Registry alias used)
• 입력 해시 (Input hash)
• 프롬프트 템플릿 해시 (Prompt template hash)
• 도구 정책 버전 (Tool policy version)
• 모델 및 설정 (Model and settings)
• 평가 스위트 버전 (Eval suite version, 해당되는 경우)
• 출력 해시 (Output hash)
• 승인 ID (Approval ID, 필요한 경우)

실행 메타데이터 예시:

{
  "run_id": "run_01",
  "skill_id": "billing.refund_reviewer",
...

이를 통해 디버깅이 훨씬 쉬워집니다. 고객이 에이전트가 왜 그런 권장 사항을 내놓았는지 물을 때, 현재 프롬프트를 보고 추측하는 대신 정확한 스킬 버전을 조사할 수 있습니다.

최소한의 데이터베이스 스키마 (A Minimal Database Schema)

다음 네 가지 테이블로 시작하세요: agent_skills, agent_skill_versions, agent_skill_aliases, 그리고 agent_skill_eval_results. 운영 환경 (Production)은 변경 가능한 프롬프트 파일이 아니라, 승인된 불변 버전 (Immutable version)을 가리켜야 합니다. 패키지 JSON, 프롬프트 해시 (Prompt hash), 정책 해시 (Policy hash), 상태 (Status), 소유자 (Owner), 그리고 최신 평가 결과 (Latest eval result)를 저장하세요.

이렇게 하면 무엇이 실행되었는지, 누가 소유하고 있는지, 무엇이 변경되었는지, 그리고 어떤 별칭 (Alias)이 운영 환경에 서비스되고 있는지를 답변하기에 충분합니다.

후회를 방지하는 승격 규칙 (Promotion Rules That Prevent Regret)

실용적인 승격 파이프라인 (Promotion pipeline)은 간단할 수 있습니다:

1. 개발자가 스킬을 생성하거나 편집합니다.
2. 레지스트리 (Registry)가 패키지를 스캔합니다.
3. 테스트 케이스에 대해 평가 스위트 (Eval suite)를 실행합니다.
4. 검토자 (Reviewer)가 목적, 도구 (Tools), 그리고 위험 수준 (Risk level)을 확인합니다.
5. 스킬이 스테이징 (Staging) 환경으로 승격됩니다.
6. 카나리 (Canary) 실행을 통해 트레이스 (Traces)와 실패 사례를 수집합니다.
7. 운영 (Production) 별칭이 승인된 버전으로 이동합니다.

다음의 경우 승격이 실패해야 합니다:

• 필수 평가 (Evals) 실패 시
• 금지된 도구 (Forbidden tool)가 나타날 시
• 검토 없이 위험 수준이 증가했을 시
• 스킬이 누락된 컨텍스트 (Context)를 참조할 시
• 비밀 정보 (Secrets) 또는 위험한 명령어가 감지될 시
• 소유자 (Owner)가 없을 시
• 성공 증거 (Success evidence)가 정의되지 않았을 시

이것이 바로 재사용 가능한 스킬이 재사용 가능한 사고 (Reusable incidents)가 되지 않도록 유지하는 방법입니다.

구현 체크리스트 (Implementation Checklist)

다음 내용을 시작 계획으로 사용하세요:

• 기존 프롬프트 및 에이전트 워크플로 (Workflows) 인벤토리 작성
• 작업, 대상, 도구별로 중복 항목 그룹화
• 스킬로 변환할 가치가 높은 워크플로 하나 선정
• 입력 스키마 (Input schema) 및 필수 컨텍스트 정의
• 허용된 도구 및 금지된 도구 목록 작성
• 성공 증거 (Success evidence) 추가
• 10개의 평가 케이스 (Eval cases) 추가
• 기본적인 보안 스캐닝 (Security scanning) 추가
• 소유자 및 검토 상태 추가
• 스테이징 및 운영 별칭 (Staging and production aliases) 추가
• 매 실행 시 스킬 버전 기록
• 매월 실패한 실행을 검토하고 평가 케이스 추가

검토 과정에서 가장 큰 고통을 주는 워크플로부터 시작하세요. 레지스트리가 효과를 발휘하기 전부터 완벽할 필요는 없습니다.

마지막 생각 (Final Thought)

스킬 레지스트리의 가장 큰 이점은 재사용이 아닙니다. 재사용도 좋지만, 제어 (Control)가 더 중요합니다.

레지스트리를 통해 팀은 다음과 같이 말할 수 있습니다:

• 이것은 승인된 워크플로 (Workflow)입니다.
• 이것은 프로덕션 (Production)에서 실행 중인 버전입니다.
• 이것은 에이전트가 사용할 수 있는 도구 (Tools)들입니다.
• 이것은 에이전트가 통과한 테스트 (Tests)들입니다.
• 이것은 에이전트가 반드시 생성해야 하는 증거 (Evidence)입니다.
• 이것은 롤백 (Rollback)을 수행하는 방법입니다.

이것이 에이전트를 영리한 데모 (Demo)로서 출시하는 것과 신뢰할 수 있는 소프트웨어 (Software)로서 운영하는 것의 차이입니다.

FAQ

AI 에이전트 스킬 레지스트리 (AI Agent Skill Registry)란 무엇인가요?

AI 에이전트 스킬 레지스트리란 에이전트를 위한 재사용 가능하고 버전 관리되는 워크플로 패키지 (Workflow packages)의 중앙 카탈로그 (Catalog)입니다. 각 스킬 (Skill)에는 지침 (Instructions), 입력 스키마 (Input schemas), 도구 권한 (Tool permissions), 안전 제한 (Safety limits), 테스트 (Tests), 소유권 (Ownership), 그리고 배포 상태 (Rollout status)가 포함됩니다.

스킬 레지스트리는 프롬프트 레지스트리 (Prompt Registry)와 어떻게 다른가요?