4,749
같은 업무를 AI에 맡기면서 매번 긴 설명을 다시 붙여 넣고 있다면, 필요한 것은 더 긴 prompt보다 공유할 수 있는 작업 절차일 수 있습니다. Agent Skills는 특정 업무의 지침과 참고 자료, 필요한 스크립트를 폴더로 묶는 공개 형식입니다.[33]
토스는 10월 23일 로그 정의 업무를 AI 스킬로 개선한 사례를 공개했습니다.[22] 이 글은 그 사례를 바탕으로, 절차를 문서화하는 것과 규칙을 실제로 강제하는 것을 어떻게 나눌지 살펴봅니다.
💡 💡 핵심: 스킬은 판단 순서를 안내하고, 필요한 자료를 찾아 읽게 하는 곳입니다. 기계적으로 확인할 규칙과 저장 단계의 거부는 실행 도구·시스템에 남기는 설계가 토스 사례의 핵심입니다.[22]
스킬의 최소 구성은 SKILL.md 파일 하나를 가진 디렉터리입니다.[33] 파일 앞부분에는 YAML frontmatter, 그 뒤에는 Markdown 지침을 둡니다.[33]
description은 단순한 소개 문장이 아니라, 작업의 활성화 판단을 돕는 필드입니다.[33] 어떤 작업을 수행하고 언제 사용해야 하는지를 설명합니다.[33]
추가 자료는 역할에 맞게 나눕니다. references/에는 필요할 때 읽을 문서를, scripts/에는 실행 가능한 코드를, assets/에는 템플릿 같은 정적 자원을 둘 수 있습니다.[33]
이 형식이 정의하는 것은 지식을 담는 구조입니다. 스크립트 실행 언어와 선택적 allowed-tools 지원은 구현에 따라 다를 수 있으므로, 폴더를 복사하는 것만으로 같은 실행 환경까지 옮겨지는 것은 아닙니다.[33]
공식 문서의 핵심은 progressive disclosure, 즉 단계적으로 정보를 여는 방식입니다.[33] 처음에는 스킬의 이름과 설명을 보고, 관련 작업에서 전체 SKILL.md를 읽고, 세부 자료는 필요할 때 추가로 읽습니다.[34]
따라서 스킬의 본문은 거대한 사전보다 업무의 길잡이에 가깝게 설계할 수 있습니다. 어떤 입력을 확인하고, 어떤 조건에서 어느 문서를 읽고, 언제 도구를 호출할지 남기는 방식입니다. 이는 단계적 로딩을 활용하기 위한 설계 제안입니다.[33]
호스트는 로컬 파일을 읽을 수도 있고, 전용 도구나 프로그램의 prompt 주입으로 스킬 내용을 전달할 수도 있습니다.[34] 스킬 발견·내용 접근 방법은 에이전트가 실행되는 환경에 따라 달라집니다.[34]
편집 의견: 재사용할 핵심 절차와 환경별 연결부를 분리하는 편이 좋습니다. 업무 순서는 공유하되, 사내 CLI 경로·인증·쓰기 권한까지 Markdown 문서 하나가 해결한다고 가정하지 않는 것입니다.
토스가 소개한 것은 실제 사용자 로그를 수집하거나 분석하는 자동화가 아니라, 로그 명세를 정의하는 업무를 돕는 스킬입니다.[22] 원문은 이 스킬이 사용자의 로그를 읽거나 처리하지 않는다고 명시합니다.[22]
현재 본문에 설명된 역할은 다음과 같습니다.[22]
lctl과 로그센터: CLI가 저장 전에 형식 규칙을 검사하고, 로그센터가 규칙에 맞지 않는 명세의 발행을 거절합니다.[22]형식 규칙을 스킬에 복사해 두는 대신 실행할 때마다 CLI에 묻는다는 점도 중요합니다.[22] 변경되는 규칙의 기준을 지침 문서와 실행기에 따로 유지하지 않는 구조입니다.[22]
토스는 처음에 규칙과 절차를 한 문서에 넣었지만, 문서가 길어지며 AI가 중요한 규칙을 놓쳤다고 설명합니다.[22] 이후 작업별로 나누고, 스킬에는 필요한 문서를 찾아가는 안내를 남겼습니다.[22]
또한 이미 정의된 로그 명세를 정답지로 삼아 같은 화면을 다시 정의하고 비교하는 평가를 했다고 보고했습니다.[22] 도메인 맥락을 지식 베이스로 축적하는 것은 원문에서 앞으로의 계획으로 제시됩니다.[22]
💡 🔬 검증 범위: 여기까지는 토스가 공개한 운영 사례를 읽은 결과입니다. 사내 도구를 사용하거나 품질·시간 절감 효과를 독립 측정하지 않았으므로, 다른 조직에서도 같은 성과가 난다고 일반화하지 않습니다.
설계 제안: 릴리스 노트 초안 작성처럼 반복되지만 맥락 판단이 필요한 업무 하나를 고르세요. 아래는 실제 도입 결과나 공식 데모가 아니라, 앞의 구조를 적용한 예시입니다.
SKILL.md에는 순서를 남깁니다. 변경 확인, 분류, 근거 연결, 불확실한 항목의 사람 확인 순서로 구성합니다.공개 통합 사례로는 GitHub CLI의 gh skill이 있습니다.[43] GitHub는 스킬을 발견·설치·관리하는 기능과 특정 tag·commit에 고정하는 기능을 소개했습니다.[43] 다만 이 글에서는 해당 명령을 실행하거나 호스트 간 호환성을 시험하지 않았습니다.
편집 판단: 한 번만 하는 일이라면 짧은 prompt나 체크리스트면 충분할 수 있습니다. 입력과 출력이 명확하고 규칙이 결정적이라면 CLI·테스트·CI에 먼저 구현하는 편이 더 단순합니다.
스킬은 업무 순서와 도메인 맥락을 반복해서 전달해야 하고, 필요한 자료를 작업별로 골라 읽어야 할 때 검토할 만합니다. 토스 사례도 판단을 안내하는 스킬과 기계적 검사를 수행하는 도구를 함께 사용합니다.[22]
반대로 스킬을 도입하면 지침의 소유자, 참고 문서의 최신성, 실행 의존성, 호스트별 동작을 관리해야 합니다. 공식 통합 문서가 환경별 발견·접근 방식을 구분하는 이유를 도입 검토에 반영할 필요가 있습니다.[34]
과거 GitHub Community에는 VS Code Insider 환경에서 요청한 스킬이 일부만 로드된다는 사용자 보고가 있습니다.[42] 이는 특정 환경의 사용자 경험이며, 현재 모든 호스트의 결함이나 정확한 내부 원인이 검증됐다는 뜻은 아닙니다.
따라서 형식 검증을 통과한 것과 업무가 제대로 수행된 것을 구분해야 합니다. 공식 skills-ref 검증 설명도 frontmatter와 이름 규칙 확인에 관한 것이며, 업무 품질을 인증한다는 설명은 아닙니다.[33]
현재 명세의 allowed-tools는 실험적이며 구현마다 지원이 다를 수 있습니다.[33] 편집 판단: 문서의 도구 목록을 모든 호스트에서 동일하게 강제되는 권한 정책으로 취급해서는 안 됩니다.
Red Hat의 보안 해설은 스킬의 스크립트 검토, 에이전트 권한 축소, 격리 환경과 외부 통신 제한을 함께 제안합니다.[35] GitHub도 배포된 스킬을 검증해 주는 것이 아니며, prompt injection이나 악성 스크립트를 포함할 수 있다고 경고합니다.[43]
💡 ⚠️ 도입 기준: 외부 스킬은 본문과 함께 스크립트·의존성을 검토하고, 자격증명을 스킬에 넣지 마세요. Red Hat 역시 스킬에 자격증명을 평문으로 저장하거나 직접 포함하지 말라고 명시합니다.[35]
가져갈 판단 기준은 세 가지입니다.
이 글은 공식 명세·통합 문서, 조직의 운영 사례, 외부 보안 해설과 사용자 보고를 대조한 문서 기반 학습 자료입니다. 설치·API 호출·성능 측정·운영 변경은 수행하지 않았고, 현재 문서의 세부 내용을 10월 24일 당시 상태로 소급하지 않았습니다.
[18] https://www.anthropic.com/news/donating-agent-skills-to-the-agentic-ai-foundation — Anthropic: Donating Agent Skills to the Agentic AI Foundation
[22] https://toss.tech/article/dataops-log-definition-skill — 토스: 머릿속에 있던 로그 정의 기준을 모두의 AI 스킬로 만들기
[33] https://agentskills.io/specification — Agent Skills Specification
[34] https://agentskills.io/integrate-skills — How to add skills support to your agent
[35] https://developers.redhat.com/articles/2026/03/10/agent-skills-explore-security-threats-and-controls — Red Hat: Agent Skills security threats and controls
[42] https://github.com/orgs/community/discussions/182117 — GitHub Community: Skill activation user report (2025)
[43] https://github.blog/changelog/2026-04-16-manage-agent-skills-with-github-cli — GitHub: Manage agent skills with GitHub CLI